notebooks/grabstrategies.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import pypylon.pylon as py\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "# handle exception trace for debugging \n",
    "# background loop\n",
    "import traceback\n",
    "\n",
    "import time\n",
    "import random"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "cam = py.InstantCamera(py.TlFactory.GetInstance().CreateFirstDevice())\n",
    "cam.Open()\n",
    "\n",
    "# to get consistant results it is always good to start from \"power-on\" state\n",
    "cam.UserSetSelector = \"Default\"\n",
    "cam.UserSetLoad.Execute()\n",
    "\n",
    "cam.ExposureTime = cam.ExposureTime.Min"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "156.20118712902217"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# show expected framerate max framerate ( @ minimum exposure time)\n",
    "cam.ResultingFrameRate.Value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "6402.000000000001"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# this results in frame period in µs\n",
    "1 / cam.ResultingFrameRate.Value * 1e6"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "we now compare different pylon grab strategies and their resulting frameperiod to this minimum frameperiod"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Grab scenarios"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## GrabOne Loop\n",
    "\n",
    "most simple style to grab"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "def GrabOneSample():\n",
    "    # fetch some images with foreground loop\n",
    "    img_sum = np.zeros((cam.Height.Value, cam.Width.Value), dtype=np.uint16)\n",
    "\n",
    "    for i in range(100):\n",
    "        with cam.GrabOne(1000) as res:\n",
    "            img = res.Array\n",
    "            img_sum += img\n",
    "    return img_sum"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3.27 s ± 41.8 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<TimeitResult : 3.27 s ± 41.8 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "%%timeit -o\n",
    "GrabOneSample()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "grab_one_average = _.average / 100"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'time to capture one frame is: 32655.76 µs'"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "f\"time to capture one frame is: {grab_one_average*1e6:.2f} µs\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "this is very easy to use, but will have the overhead of starting and stopping the grab engine for every frame"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Foreground Loop\n",
    "\n",
    "move the start and stop of the grab engine out of the inner grab loop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "def ForegroundLoopSample():\n",
    "    # fetch some images with foreground loop\n",
    "    img_sum = np.zeros((cam.Height.Value, cam.Width.Value), dtype=np.uint16)\n",
    "    cam.StartGrabbingMax(100)\n",
    "    while cam.IsGrabbing():\n",
    "        with cam.RetrieveResult(1000) as res:\n",
    "            if res.GrabSucceeded():\n",
    "                img = res.Array\n",
    "                img_sum += img\n",
    "            else:\n",
    "                raise RuntimeError(\"Grab failed\")\n",
    "    cam.StopGrabbing()\n",
    "    return img_sum"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "%%timeit -o \n",
    "ForegroundLoopSample()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "foreground_average = _.average / 100"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f\"average time to capture one frame is: {foreground_average*1e6:.2f} µs\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Background loop\n",
    "\n",
    "* use this mode to communicate with the camera while the images are collected in the backgound.\n",
    "* Allows async communication"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pylon uses classes with callback handler to let usercode communicate with the grab loop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "class ImageHandler(py.ImageEventHandler):\n",
    "    def __init__(self):\n",
    "        super().__init__()\n",
    "        self.img_sum = np.zeros((cam.Height.Value, cam.Width.Value), dtype=np.uint16)\n",
    "        \n",
    "    def OnImageGrabbed(self, camera, grabResult):\n",
    "        \"\"\" we get called on every image\n",
    "            !! this code is run in a pylon thread context\n",
    "            always wrap your code in the try .. except to capture\n",
    "            errors inside the grabbing as this can't be properly reported from \n",
    "            the background thread to the foreground python code\n",
    "        \"\"\"\n",
    "        try:\n",
    "            if grabResult.GrabSucceeded():\n",
    "                # check image contents\n",
    "                img = grabResult.Array\n",
    "                self.img_sum += img\n",
    "            else:\n",
    "                raise RuntimeError(\"Grab Failed\")\n",
    "        except Exception as e:\n",
    "            traceback.print_exc()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "def BackGroundLoopSample():\n",
    "\n",
    "    # instantiate callback handler\n",
    "    handler = ImageHandler()\n",
    "    # register with the pylon loop\n",
    "    cam.RegisterImageEventHandler( handler , py.RegistrationMode_ReplaceAll, py.Cleanup_None)\n",
    "\n",
    "    # fetch some images with background loop\n",
    "    cam.StartGrabbingMax( 100, py.GrabStrategy_LatestImages, py.GrabLoop_ProvidedByInstantCamera)\n",
    "    while cam.IsGrabbing():\n",
    "        # random exposuretime changes every 100ms\n",
    "        cam.ExposureTime = random.uniform(cam.ExposureTime.Min, 1000)\n",
    "        time.sleep(0.1)\n",
    "\n",
    "    cam.StopGrabbing()\n",
    "    cam.DeregisterImageEventHandler(handler)\n",
    "    \n",
    "    return handler.img_sum"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "jupyter": {
     "outputs_hidden": false
    },
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "%%timeit -o\n",
    "BackGroundLoopSample()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "background_average = _.average / 100"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f\"average time to capture one frame is: {background_average*1e6:.2f} µs\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.StopGrabbing()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cam.Close()"
   ]
  },
  {
   "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.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}