ASLM-calculations.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ASLM parameters optimization\n",
    "\n",
    "Optimize acquisition parameters of mesoSPIM: \n",
    "- $t_{exp}$, pixel exposure time, typically 5-20 ms\n",
    "- $f_{gal}$, galvo scanning frequency, typically 99.99 or 199.9 Hz. Lower is preferred due to heating issues.\n",
    "    * Galvo one-way sweep time (half-cycle): $t_{gal} = 0.5 * 1000/f_{gal}$ ms, typically 5 or 2.5 ms.\n",
    "\n",
    "### Experimental setup\n",
    "Benchtop mesoSPIM with Iris 15 camera, $FOV_X = 12.61$ mm, rolling shutter mode (pixels are read out by columns with defined exposure time per pixel).\n",
    "\n",
    "The measured gaussian beam (488 nm) sigma along propagation axis is $\\sigma=85$ um, so $L_{beam}=2\\sigma = 170$ um. Strictly speaking, LS length is $FWHM_z = 2.355\\sigma = 2 Z_R$, two Rayleigh lengths. But using $2\\sigma$ is more conservative and should yield somewhat thinner LS. Aven more conservative estimate 120 um is used here for thinner effective LS.\n",
    "\n",
    "### Optimization assumptions\n",
    "1. Each pixel is illuminated via galvo sweep one or more times, : $n=1,2,...$, depending on $t_{exp}$ setting.\n",
    "2. During $t_{exp}$ interval, laser waist travels some distance\n",
    "    * beam waist speed $V_{beam}=FOV_X/T_{etl-ramp}$\n",
    "    * ideally, beam waist should travel no more than $L_{beam}$ distance during $t_{exp}$ interval.\n",
    "3. Waveform delays are not accounted here, but they are very important for optimal timing. **The necessary delays are hand-tuned in the acquisition software.**\n",
    "    \n",
    "### Disclaimer\n",
    "For any inaccuracies blame Nikita Vladimirov (@nvladimus)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Optics and sensor params\n",
    "MAG = np.array([2, 5, 7.5, 10])\n",
    "FOV_X_sensor_um = 12610 # Iris 15 shorter axis\n",
    "FOV_X_um = FOV_X_sensor_um / MAG\n",
    "ETL_ramp_duty_ratio = 0.83 # default 0.83\n",
    "f_gal = 99.9 # user-defined parameter, galvo frequency\n",
    "t_exp_ms = 10 # user-defined parameter, pixel exposure time\n",
    "T_waveform_ms = 267 # user-defined parameter, total waveform duration, default 267\n",
    "L_beam_um = 120 # conservative estimate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated beam length, um: 120\n",
      "Galvo freq, Hz: 99.9\n",
      "Galvo single sweep time, ms: 5.0 (= minimal recommended exposure)\n",
      "User-defined exposure, ms: 10.0\n",
      "# galvo sweeps during user-defined exposure time (10.0 ms): 2.0\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>0</th>\n",
       "      <th>1</th>\n",
       "      <th>2</th>\n",
       "      <th>3</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>MAG</th>\n",
       "      <td>2.000000</td>\n",
       "      <td>5.000000</td>\n",
       "      <td>7.500000</td>\n",
       "      <td>10.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>t_exp_max_ms</th>\n",
       "      <td>4.217795</td>\n",
       "      <td>10.544489</td>\n",
       "      <td>15.816733</td>\n",
       "      <td>21.088977</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>n_sweeps_per_max_exp</th>\n",
       "      <td>0.842716</td>\n",
       "      <td>2.106789</td>\n",
       "      <td>3.160183</td>\n",
       "      <td>4.213578</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                             0          1          2          3\n",
       "MAG                   2.000000   5.000000   7.500000  10.000000\n",
       "t_exp_max_ms          4.217795  10.544489  15.816733  21.088977\n",
       "n_sweeps_per_max_exp  0.842716   2.106789   3.160183   4.213578"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "T_ETL_ramp_ms = T_waveform_ms * ETL_ramp_duty_ratio # active time of ETL ramp\n",
    "t_gal = 0.5 * 1000/f_gal # half-cycle of the galvo, single sweep\n",
    "V_beam = FOV_X_um / T_ETL_ramp_ms # physical speed of the beam waist along the beam axis\n",
    "t_exp_max_ms = L_beam_um/V_beam # maximum recommended exposure time, based on beam length and waist speed\n",
    "n_sweeps_per_max_exp = t_exp_max_ms/t_gal # how many galvo sweeps contained in the maximum recommended exposure time\n",
    "n_sweeps_per_curr_exp = t_exp_ms/t_gal # how many galvo sweeps contained in actual user-selected exposure time\n",
    "#hint = '<' if t_exp_ms < t_exp_max_ms else 'exceeds (!)'\n",
    "\n",
    "print(f\"Estimated beam length, um: {L_beam_um}\")\n",
    "print(f\"Galvo freq, Hz: {f_gal}\")\n",
    "print(f\"Galvo single sweep time, ms: {t_gal:.2} (= minimal recommended exposure)\")\n",
    "# print(f\"Beam waist speed, um/ms: {V_beam:.2f}\")\n",
    "# print(f\"Current exposure, ms: {t_exp_ms:.2f} {hint} maximum allowed {t_exp_max_ms:.2f}\")\n",
    "print(f\"User-defined exposure, ms: {t_exp_ms:.1f}\")\n",
    "print(f\"# galvo sweeps during user-defined exposure time ({t_exp_ms:.1f} ms): {t_exp_ms/t_gal:.1f}\")\n",
    "# print(f\"# of beam sweeps per current exposure: {n_sweeps_per_curr_exp:.1f} {hint} maximum allowed {n_sweeps_per_max_exp:.1f}\")\n",
    "opt_params = pd.DataFrame({'MAG': MAG,  't_exp_max_ms': t_exp_max_ms, 'n_sweeps_per_max_exp': n_sweeps_per_max_exp})\n",
    "opt_params.T"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Legend\n",
    "- `t_exp_max_ms` is the maximum recommended exposure time, based on beam length and waist speed, see notes below.\n",
    "- `n_sweeps_per_max_exp` is how many galvo sweeps occur within the one `t_exp_max_ms` (should be at least 1). Non-integer values are likely to create stripes.\n",
    "\n",
    "# Notes\n",
    "- exposure higher than `t_exp_max_ms` worsens the axial resolution by using wider-than-optimal LS length (with increasingly widening LS lobes)\n",
    "\n",
    "- exposure smaller than `t_exp_max_ms` uses narrower LS length => somewhat higher z-resolution (10-20%?), but dark vertical stripes may apper due to missing galvo sweeps during a short exposure.\n",
    "\n",
    "- it is better to guarantee at least 2 galvo sweeps per pixel (instead of ~1 or less), because non-sufficient sweep coverage creates dark stripes.\n",
    "\n",
    "- higher magnification => higher recommended `t_exp_max_ms`\n",
    "\n",
    "- 199.9 Hz galvo freq is generally no better than 99.9 Hz in resolution, but allows more galvo sweeps per exposure => better averaging, less striping. 199.9 Hz freq generates a lot of heat at 2X (large amplitude), but tolerable at 5X or more.\n",
    "\n",
    "- 2X has challenging scanning parameters - FOV is large, so the exposure of 10 ms is suboptimal (thicker LS sectioning). However, XY resolution of 2X is 5 um at best, so widening of axial resolution to the same value is OK (isotropic resolution).\n",
    "\n",
    "- the recommended exposure time for 2x-10X is **10 ms or higher**.\n",
    "\n",
    "- the recommended galvo frequency for 2x-10s is **99.9Hz**\n",
    "\n",
    "- the recommended total sweep (waveform) time is **250 ms**.\n",
    "\n",
    "\n",
    "# Troubleshooting\n",
    "## Dark vertical stripes\n",
    "The vertical stripes appear when some pixels are not illuminated (black stripes) or illuminated non-integer number of times (gray stripes). This occurs when pixel exposure too low or galvo frequency too low.\n",
    "- increase exposure (5=>10. 15 ms, etc)\n",
    "- increase galvo frequency (99=>199)\n",
    "\n",
    "## Low (or fluctuating high/low) axial resolution\n",
    "- decrease exposure (15 => 10, 5 ms, but not below 5 ms)\n",
    "\n",
    "## Dim signal (low SNR image)\n",
    "- increase the laser power\n",
    "- double both the total waveform time and the exposure time (slows the acquisition speed by 2X!)\n",
    "    - double only the exposure time, if you can tolerate worsening of axial resolution but want to keep the same acquisition speed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}