notebooks/USB_hdr_exposure_bracketing_using_sequencer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exposure bracketing using the sequencer feature of USB3 ace devices"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pypylon.pylon as py\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# open the first USB device\n",
    "info = py.DeviceInfo()\n",
    "info.SetDeviceClass(\"BaslerUsb\")\n",
    "cam = py.InstantCamera(py.TlFactory.GetInstance().CreateFirstDevice(info))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# this code only works for ace USB\n",
    "if not cam.GetDeviceInfo().GetModelName().startswith(\"acA\"):\n",
    "    print(\"_This_ sequencer configuration only works to basler ace USB\")\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# open device\n",
    "cam.Open()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## setup camera.\n",
    "sequencer mode is not running if the auto-functions are active"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.UserSetSelector = \"Default\"\n",
    "cam.UserSetLoad.Execute()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# mean exposure time 20ms\n",
    "exp_0 = 2000\n",
    "exp_1 = 20000\n",
    "exp_2 = 200000"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### activate chunks [ embedded data ]\n",
    "This allows to read the exposuretime an image has been taken with from the image data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "# enable camera chunk mode\n",
    "cam.ChunkModeActive = True\n",
    "# enable exposuretime chunk\n",
    "cam.ChunkSelector = \"ExposureTime\"\n",
    "cam.ChunkEnable = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### sequencer setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerMode = \"Off\"\n",
    "cam.SequencerConfigurationMode = \"On\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### setup set 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerSetSelector = 0\n",
    "\n",
    "cam.ExposureTime = exp_0\n",
    "\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "### setup set 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerSetSelector = 1\n",
    "\n",
    "cam.ExposureTime = exp_1\n",
    "\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "### setup set 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerSetSelector = 2\n",
    "\n",
    "cam.ExposureTime = exp_2\n",
    "\n",
    "# select that we jump to set 0 after this set\n",
    "# path 1 is the _next_ path / path 0 would be _reset_ path\n",
    "cam.SequencerPathSelector = 1\n",
    "cam.SequencerSetNext = 0\n",
    "\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### enable sequencer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerConfigurationMode = \"Off\"\n",
    "\n",
    "# this will set the first sequencer set to set _0_ as side effect\n",
    "cam.SequencerMode = \"On\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### test capture with enabled sequencer mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\t  2000\t 17.95\n",
      "1\t 20000\t 77.26\n",
      "2\t200000\t201.53\n",
      "3\t  2000\t 17.94\n",
      "4\t 20000\t 77.25\n",
      "5\t200000\t201.57\n",
      "6\t  2000\t 17.96\n",
      "7\t 20000\t 77.28\n",
      "8\t200000\t201.56\n",
      "9\t  2000\t 17.96\n",
      "10\t 20000\t 77.29\n",
      "11\t200000\t201.55\n"
     ]
    }
   ],
   "source": [
    "# grab 4 sets of 3 images\n",
    "cam.StartGrabbingMax( 4 * 3)\n",
    "\n",
    "while cam.IsGrabbing():\n",
    "    res = cam.RetrieveResult(1000)\n",
    "    exp_time_chunk = res.ChunkDataNodeMap.ChunkExposureTime.Value\n",
    "    print(\"%d\\t%6.0f\\t%6.2f\" %(res.BlockID, exp_time_chunk, np.mean(res.Array)))\n",
    "    # ... do something with the images\n",
    "    \n",
    "    # return to buffer queue\n",
    "    res.Release()\n",
    "    \n",
    "cam.StopGrabbing()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Shutdown session after acquisition\n",
    "\n",
    "This is required to rerun the notebook"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerMode = \"Off\"\n",
    "cam.Close()"
   ]
  }
 ],
 "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}