notebooks/Ace2_USB_hdr_exposure_bracketing_using_sequencer.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exposure bracketing using the sequencer feature of USB3 ace2devices\n",
    "\n",
    "Documentation for sequencer feature on Ace2 and Boost-R is in https://docs.baslerweb.com/sequencer-(ace-2-and-boost-r)"
   ]
  },
  {
   "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(\"a2A\"):\n",
    "    print(\"_This_ sequencer configuration only works to basler ace2 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": [
    "# reset to known state\n",
    "cam.SequencerMode = \"Off\"\n",
    "cam.SequencerConfigurationMode = \"Off\"\n",
    "cam.UserSetSelector = \"Default\"\n",
    "cam.UserSetLoad.Execute()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "exp_0 = 100\n",
    "exp_1 = 200\n",
    "exp_2 = 300\n",
    "exp_3 = 400"
   ]
  },
  {
   "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\n",
    "# enable sequencer set info\n",
    "cam.ChunkSelector = \"SequencerSetActive\"\n",
    "cam.ChunkEnable = True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### sequencer setup\n",
    "\n",
    "The configuration in this example will switch to the next sequencer set for each image\n",
    "\n",
    "* exp_0\n",
    "* exp_1\n",
    "* exp_2\n",
    "* exp_3\n",
    "* exp_0\n",
    "* exp_1\n",
    "* ...\n",
    "  "
   ]
  },
  {
   "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.ExposureTime = exp_0\n",
    "\n",
    "# switch to the next set after image taken\n",
    "cam.SequencerPathSelector = 0\n",
    "cam.SequencerSetNext = 1\n",
    "cam.SequencerTriggerSource = \"ExposureStart\"\n",
    "\n",
    "cam.SequencerSetSelector = 0\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### setup set 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.ExposureTime = exp_1\n",
    "\n",
    "# switch to the next set after image taken\n",
    "cam.SequencerPathSelector = 0\n",
    "cam.SequencerSetNext = 2\n",
    "cam.SequencerTriggerSource = \"ExposureStart\"\n",
    "\n",
    "cam.SequencerSetSelector = 1\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### setup set 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.ExposureTime = exp_2\n",
    "\n",
    "# switch to the next set after image taken\n",
    "cam.SequencerPathSelector = 0\n",
    "cam.SequencerSetNext = 3\n",
    "cam.SequencerTriggerSource = \"ExposureStart\"\n",
    "\n",
    "cam.SequencerSetSelector = 2\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### setup set 3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.ExposureTime = exp_3\n",
    "\n",
    "# switch to the _first_ set after image taken\n",
    "cam.SequencerPathSelector = 0\n",
    "cam.SequencerSetNext = 0\n",
    "cam.SequencerTriggerSource = \"ExposureStart\"\n",
    "\n",
    "cam.SequencerSetSelector = 3\n",
    "cam.SequencerSetSave.Execute();"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dump Configuration"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "set 0: -> 1 ( ExposureStart )\n",
      "Exposure time 100.0\n",
      "set 1: -> 2 ( ExposureStart )\n",
      "Exposure time 200.0\n",
      "set 2: -> 3 ( ExposureStart )\n",
      "Exposure time 300.0\n",
      "set 3: -> 0 ( ExposureStart )\n",
      "Exposure time 400.0\n"
     ]
    }
   ],
   "source": [
    "for seq_set in range(cam.SequencerSetSelector.Max + 1):\n",
    "    cam.SequencerSetSelector = seq_set\n",
    "    cam.SequencerSetLoad.Execute()\n",
    "    if cam.SequencerTriggerSource.Value == \"Off\":\n",
    "        continue\n",
    "    cam.SequencerPathSelector = 0\n",
    "    next_set = cam.SequencerSetNext.Value\n",
    "    print(f\"set {seq_set}: -> {next_set} ( {cam.SequencerTriggerSource.Value} )\")\n",
    "    print(\"Exposure time\", cam.ExposureTime.Value)\n",
    "    \n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### exit configuration mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerConfigurationMode = \"Off\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### activate sequencer mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 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": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0\t0\t   100\t  0.00\n",
      "1\t1\t   200\t  0.00\n",
      "2\t2\t   300\t  0.00\n",
      "3\t3\t   400\t  0.00\n",
      "4\t0\t   100\t  0.00\n",
      "5\t1\t   200\t  0.00\n",
      "6\t2\t   300\t  0.00\n",
      "7\t3\t   400\t  0.00\n",
      "8\t0\t   100\t  0.00\n",
      "9\t1\t   200\t  0.00\n",
      "10\t2\t   300\t  0.00\n",
      "11\t3\t   400\t  0.00\n"
     ]
    }
   ],
   "source": [
    "# grab 4 sets of 3 images\n",
    "cam.StartGrabbingMax( 4 * 3)\n",
    "\n",
    "while cam.IsGrabbing():\n",
    "    with cam.RetrieveResult(1000) as res:\n",
    "        exp_time_chunk = res.ChunkDataNodeMap.ChunkExposureTime.Value\n",
    "        sequence_id_chunk = res.ChunkDataNodeMap.ChunkSequencerSetActive.Value\n",
    "        print(\"%d\\t%d\\t%6.0f\\t%6.2f\" %(res.BlockID, sequence_id_chunk, exp_time_chunk, np.mean(res.Array)))\n",
    "        # ... do something with the images\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": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.SequencerMode = \"Off\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.Close()"
   ]
  }
 ],
 "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}