Pylon Cameras

Overview

This device allows control of Basler scientific cameras via the Pylon API with the PyPylon python wrapper. In order to use this device, both the Basler Pylon API and the PyPylon wrapper must be installed.

labscript_devices.PylonCamera.labscript_devices
labscript_devices.PylonCamera.blacs_tabs
labscript_devices.PylonCamera.blacs_workers

Installation

First ensure that the Basler Pylon SDK is installed. It is available for free here (after signing up for a free account with Basler). It is advisable to use the Pylon Viewer program that comes with the SDK to test communications with the camera.

The python wrapper is installed via pip:

pip install -U pypylon

At present, the wrapper is tested and confirmed compatible with Pylon 5 for USB3 and GigE interface cameras.

For GigE cameras, ensure that the network interface card (NIC) on the computer with the BLACS controlling the camera has enabled Jumbo Frames. That maximum allowed value (typically 9000) is preferable to avoid dropped frames.

For USB3 cameras, care should be taken to use a USB3 host that is compatible with the Basler cameras. Basler maintains a list of compatible host controllers. The cameras will work on any USB3 port, but non-compatible hosts will not allow for the faster performance.

Usage

Like the IMAQdxCamera device, the bulk of camera configuration is performed using a dictionary of kwargs, where the key names and values mirror those provided by the Pylon SDK interface. Which parameters can/need to be set depend on the communication interface. Discovery of what parameters are available can be done in three ways:

1. Careful reading of the Pylon SDK docs.

2. Mirroring the Pylon Viewer parameter names and values.

3. Connecting to the camera with a minimal configuration, viewing the current parameters dictionary, and copying the relevant values to the connection table (preferred).

Below are generic configurations for GigE and USB3 based cameras.

from labscript import *

from labscript_devices.PylonCamera.labscript_devices import PylonCamera

PylonCamera('gigeCamera',parent_device=parent,connection=conn,
            serial_number=1234567, # set to the camera serial number
            minimum_recovery_time=20e-3, # the minimum exposure time depends on the camera model & configuration
            camera_attributs={
               'ExposureTimeAbs':1000, #in us
               'ExposureMode':'Timed',
               'ExposureAuto':'Off',
               'GainAuto':'Off',
               'PixelFormat':'Mono12Packed',
               'Gamma':1.0,
               'BlackLevelRaw':0,
               'TriggerSource':'Line 1',
               'TriggerMode':'On'
            },
            manual_camera_attributes={
               'TriggerSource':'Software',
               'TriggerMode':'Off'
            })

PylonCamera('usb3Camera',parent_device=parent,connection=conn,
            serial_number=12345678,
            minimum_recovery_time=36e-3,
            camera_attributs={
               'ExposureTime':1000, #in us
               'ExposureMode':'Timed',
               'ExposureAuto':'Off',
               'GainAuto':'Off',
               'PixelFormat':'Mono12Packed',
               'Gamma':1.0,
               'BlackLevel':0,
               'TriggerSource':'Line 1',
               'TriggerMode':'On',
               'ShutterMode':'Global'
            },
            manual_camera_attributes={
               'TriggerSource':'Software',
               'TriggerMode':'Off'
            })

start()

gigeCamera.expose(t=0.5,'exposure1')

usb3Camera.expose(t=0.45,'exposure2')

stop(1)

Utilities

The Pylon labscript device includes a script in the testing subfolder that can automatically determine the full-frame sensor readout time and maximum possible framerate. This tool helps in correctly determining the appropriate minimum_recovery_time to set for each device. The minimum recovery time is a function of the model used, the communication bus used, and minor details of the setup (such as host controller firmwares, cable lengths, host computer workload, etc). As a result, live testing of the device is often needed to accurately determine the actual recovery time needed between shots.

The script is run from within the testing folder using

python ExposureTiming.py [camera_sn]

with [camera_sn] being the serial number of the camera to connect to and test.

The script reports the minimum recovery time between two shots of 1 ms exposure each, without the use of overlapped exposure mode. Editing the script to include your typical experiment parameters will help in more accurately determining your minimum recovery time. Typically, the minimum recovery time should be slightly longer than the reported sensor readout time.

Note that in overlapped exposure mode, a second exposure is begun before the first exposure has finished reading out and must end after the readout of the first exposure frame is complete. This allows for a series of two exposures with shorter delay between them, at the expense of limitations on the length of the second exposure. The script will also report the minimum time between the end of one exposure and the beginning of the second (nominally readout_time - exposure_time). Note that this feature is automatically handled at the Pylon API level; this labscript device is not actively aware of it. As a result, incorrect uses of overlapped mode will not be caught at compile time, but rather during the shot as hardware errors.

Detailed Documentation

class labscript_devices.PylonCamera.labscript_devices.PylonCamera(name, parent_device, connection, serial_number, orientation=None, pixel_size=[1.0, 1.0], magnification=1.0, trigger_edge_type='rising', trigger_duration=None, minimum_recovery_time=0.0, camera_attributes=None, manual_mode_camera_attributes=None, stop_acquisition_timeout=5.0, exception_on_failed_shot=True, saved_attribute_visibility_level='intermediate', mock=False, **kwargs)

Bases: IMAQdxCamera

A camera to be controlled using NI IMAQdx and triggered with a digital edge.

Parameters:

• name (str) – device name

• parent_device (IntermediateDevice) – Device with digital outputs to be used to trigger acquisition

• connection (str) – Name of digital output port on parent device.

• serial_number (str or int) – string or integer (integer allows entering a hex literal) of the camera’s serial number. This will be used to idenitfy the camera.

• orientation (str, optional) – <name> Description of the camera’s location or orientation. This will be used to determine the location in the shot file where the images will be saved. If not given, the device name will be used instead.

• pixel_size ([float,float], optional) – [1.0, 1.0] The x and y size of the pixels in micrometers. This can be used in setting the scale in the blacs image display as well as extracted in lyse for analysis.

• magnification (float, optional) – 1.0 Imaging system magnification.

• trigger_edge_type (str) – 'rising' The direction of the desired edges to be generated on the parent devices’s digital output used for triggering. Must be ‘rising’ or ‘falling’. Note that this only determines the edges created on the parent device, it does not program the camera to expect this type of edge. If required, one must configure the camera separately via camera_attributes to ensure it expects the type of edge being generated. Default: 'rising'

• trigger_duration (float or None) – None Duration of digital pulses to be generated by the parent device. This can also be specified as an argument to expose() - the value given here will be used only if nothing is passed to expose().

• minimum_recovery_time (float) – 0 Minimum time between frames. This will be used for error checking during compilation.

• camera_attributes (dict, optional) – Dictionary of camera attribute names and values to be programmed into the camera. The meaning of these attributes is model-specific. Attributes will be programmed in the order they appear in this dictionary. This can be important as some attributes may not be settable unless another attrbiute has been set first. After adding this device to your connection table, a dictionary of the camera’s default attributes can be obtained from the BLACS tab, appropriate for copying and pasting into your connection table to customise the ones you are interested in.

• manual_mode_camera_attributes (dict, optional) – Dictionary of attributes that will be programmed into the camera during manual mode, that differ from their values in camera_attributes. This can be useful for example, to have software triggering during manual mode (allowing the acquisition of frames from the BLACS manual mode interface) but hardware triggering during buffered runs. Any attributes in this dictionary must also be present in camera_attributes.

• stop_acquisition_timeout (float) – 5.0 How long, in seconds, to wait during transition_to_buffered for the acquisition of images to complete before giving up. Whilst all triggers should have been received, this can be used to allow for slow image download time.

• exception_on_failed_shot (bool) – True. If acquisition does not complete within the given timeout after the end of a shot, whether to raise an exception. If False, instead prints a warning to stderr (visible in the terminal output pane in the BLACS tab), saves the images acquired so far, and continues. In the case of such a ‘failed shot’, the HDF5 attribute f[‘images’][orientation/name].attrs[‘failed_shot’] will be set to True (otherwise it is set to False). This attribute is acessible in the lyse dataframe as df[orientation/name, 'failed_shot'].

• saved_attribute_visibility_level (str or None) – ‘intermediate’ The detail level of the camera attributes saved to the HDF5 file at the end of each shot. If None, no attributes will be saved. Must be one of 'simple', 'intermediate', 'advanced', or None. If None, no attributes will be saved.

• mock (bool, optional) – False For testing purpses, simulate a camera with fake data instead of communicating with actual hardware.

• **kwargs – Further keyword arguments to be passed to the __init__ method of the parent class (TriggerableDevice).

description = 'Pylon Camera'

Brief description of the device.

class labscript_devices.PylonCamera.blacs_tabs.PylonCameraTab(notebook, settings, restart=False)

Bases: IMAQdxCameraTab

worker_class = 'labscript_devices.PylonCamera.blacs_workers.PylonCameraWorker'

class labscript_devices.PylonCamera.blacs_workers.PylonCameraWorker(*args, **kwargs)

Bases: IMAQdxCameraWorker

Pylon API Camera Worker.

Inherits from IMAQdxCameraWorker. Overloads get_attributes_as_dict to use PylonCamera.get_attributes() method.

get_attributes_as_dict(visibility_level)

Return a dict of the attributes of the camera for the given visibility level

interface_class

alias of Pylon_Camera

class labscript_devices.PylonCamera.blacs_workers.Pylon_Camera(serial_number)

Bases: object

abort_acquisition()

close()

configure_acquisition(continuous=True, bufferCount=10)

Configure acquisition by calling StartGrabbing with appropriate grab strategy: LatestImageOnly for continuous, OneByOne otherwise.

get_attribute(name)

Return current value of attribute of the given name

get_attributes(visibility_level, writeable_only=True)

Return a dict of all attributes of readable attributes, for the given visibility level. Optionally return only writeable attributes.

grab(continuous=True)

Grab single image during pre-configured acquisition.

grab_multiple(n_images, images)

Grab n_images into images array during buffered acquistion.

set_attribute(name, value)

Set the value of the attribute of the given name to the given value

set_attributes(attributes_dict)

Sets all attribues in attr_dict. Pylon cameras require that ROI settings be done in correct order, so we do them separately.

snap()

Acquire a single image and return it

stop_acquisition()