docs/source/application_notebooks/TZYX_fast_sequencing_z_indexing.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "# Fast 3D + time imaging with hardware triggering\n",
    "\n",
    "This notebook acquires a fast `TZYX` data series.\n",
    "\n",
    "The camera is run at reduced `ROI` to achieve higher `framerate` (here 200 frames per second).\n",
    "\n",
    "Movement of the z stage is \"sequenced\" to speed up acquisition. The z stage advances to the next position in the sequence\n",
    "when a trigger from the camera is received. This eliminates delays due to software communication.\n",
    "\n",
    "Here a piezo z stage from ASI Imaging is used. The stage is put in \"Fast Sequencing\" mode such that the position sequence\n",
    "is repeated if a trigger is received after the last position in the sequence has been reached. In this way the camera is\n",
    "run in \"burst mode\" for multiple z stack acquisitions without having to resend the sequence buffer.\n",
    "\n",
    "A custom z position sequence representing a triangle waveform is used. This means that the stage will move from\n",
    "`start_end_pos = -2.5` to `mid_pos = 2.5` in steps of `step_size = 0.25` and then back from `mid_pos` to `start_end_pos`\n",
    "in steps of `-step_size`. This set of stage positions avoids the large jump from the end of the sequence back to the\n",
    "beginning of the sequence which may take more time to complete than a single step and may disturb the sample.\n",
    "\n",
    "Using `pycro-manager` this set of acquisition events is encoded as follows:\n",
    "\n",
    "```python\n",
    "events = []\n",
    "z_idx_ = z_idx.copy()\n",
    "for i in range(num_time_points):\n",
    "    for j in z_idx_:\n",
    "        events.append({'axes': {'time':i, 'z': j}})\n",
    "    z_idx_.reverse()\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from pycromanager import Acquisition, Core, Studio"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "def upload_piezo_sequence(start_end_pos, mid_pos, step_size, relative=True):\n",
    "    \"\"\"\n",
    "    Upload a triangle waveform of z_stage positions and set the z_stage in UseFastSequence mode\n",
    "\n",
    "    :param bridge: pycro-manager java bridge\n",
    "    :type bridge: pycromanager.core.Bridge\n",
    "    :param start_end_pos: start and end position of triangle waveform\n",
    "    :type start_end_pos: float\n",
    "    :param mid_pos: mid position of the triangle waveform\n",
    "    :type mid_pos: float\n",
    "    :param step_size: z_stage step size\n",
    "    :type step_size: float\n",
    "    :param relative: set to False if given start_end_pos and mid_pos are absolute\n",
    "\n",
    "    :return: current z position and absolute positions of triangle waveform\n",
    "    \"\"\"\n",
    "\n",
    "    mmc = Core()\n",
    "\n",
    "    z_stage = mmc.get_focus_device()\n",
    "\n",
    "    pos_sequence = np.hstack(\n",
    "        (\n",
    "            np.arange(start_end_pos, mid_pos + step_size, step_size),\n",
    "            np.arange(mid_pos, start_end_pos - step_size, -step_size),\n",
    "        )\n",
    "    )\n",
    "\n",
    "    z_pos = 0\n",
    "    if relative:\n",
    "        z_pos = mmc.get_position(z_stage)\n",
    "        pos_sequence += z_pos\n",
    "\n",
    "    # construct java object\n",
    "    positionJ = bridge.construct_java_object(\"mmcorej.DoubleVector\")\n",
    "    for i in pos_sequence:\n",
    "        positionJ.add(float(i))\n",
    "\n",
    "    # send sequence to stage\n",
    "    mmc.set_property(z_stage, \"UseSequence\", \"Yes\")\n",
    "    mmc.set_property(z_stage, \"UseFastSequence\", \"No\")\n",
    "    mmc.load_stage_sequence(z_stage, positionJ)\n",
    "    mmc.set_property(z_stage, \"UseFastSequence\", \"Armed\")\n",
    "\n",
    "    return z_pos, pos_sequence"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Construct java objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "mmc = Core()\n",
    "mmStudio = Studio()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set acquisition parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# Data set parameters\n",
    "path = r\"C:\\test\"\n",
    "name = \"pycromanager test\"\n",
    "\n",
    "# z stack parameters\n",
    "start_end_pos = -2.5\n",
    "mid_pos = 2.5\n",
    "step_size = 0.25\n",
    "relative = True\n",
    "\n",
    "# time series parameters\n",
    "duration = 2  # in seconds\n",
    "exposure_time = 3  # in milliseconds\n",
    "framerate = 200\n",
    "\n",
    "# FOV parameters\n",
    "ROI = [924, 770, 616, 514]\n",
    "\n",
    "num_z_positions = int(abs(mid_pos - start_end_pos) / step_size + 1)\n",
    "z_idx = list(range(num_z_positions))\n",
    "num_time_points = np.ceil(duration * framerate / num_z_positions).astype(np.int)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Prepare for acquisition"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# setup cameras\n",
    "mmc.set_exposure(exposure_time)\n",
    "mmc.set_roi(*ROI)\n",
    "mmc.set_property(\"Camera\", \"Framerate\", framerate)\n",
    "\n",
    "# setup z stage\n",
    "z_stage = mmc.get_focus_device()\n",
    "z_pos, pos_sequence = upload_piezo_sequence(\n",
    "    bridge, start_end_pos, mid_pos, step_size, relative\n",
    ")\n",
    "num_z_positions = len(pos_sequence)\n",
    "\n",
    "# move to first position\n",
    "mmc.set_position(z_stage, pos_sequence[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Generate events"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "events = []\n",
    "z_idx_ = z_idx.copy()\n",
    "for i in range(num_time_points):\n",
    "    for j in z_idx_:\n",
    "        events.append({\"axes\": {\"time\": i, \"z\": j}})\n",
    "    z_idx_.reverse()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Acquire data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "with Acquisition(directory=path, name=name) as acq:\n",
    "    acq.acquire(events)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "pycharm": {
     "name": "#%% md\n"
    }
   },
   "source": [
    "### Reset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "pycharm": {
     "name": "#%%\n"
    }
   },
   "outputs": [],
   "source": [
    "# turn off sequencing\n",
    "mmc.set_property(z_stage, \"UseFastSequence\", \"No\")\n",
    "mmc.set_property(z_stage, \"UseSequence\", \"No\")\n",
    "\n",
    "# move back to initial position\n",
    "mmc.set_position(z_stage, z_pos)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}