FlyCapture2 Cameras

This device allows control of FLIR (formerly Point Grey) scientific cameras via the FlyCapture2 SDK with the now deprecated PyCapture2 wrapper. In order to use this device, both the SDK and the python wrapper must be installed. Note that PyCapture2 only supports up to Python 3.6.

The new FLIR SDK is supported using the SpinnakerCamera labscript device.

labscript_devices.FlyCapture2Camera.labscript_devices

labscript_devices.FlyCapture2Camera.blacs_tabs

labscript_devices.FlyCapture2Camera.blacs_workers

Installation

First ensure that the FlyCapture2 SDK is installed.

The python wrapper is available via FLIR and is only released for Python up to 3.6. It must be installed separately, pointed to the correct conda environment during install.

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.

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 FlyCapture2 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 FlyCapture2 SDK docs.

  2. Mirroring the FlyCap 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).

The python structure for setting these values differs somewhat from other camera devices in labscript, taking the form of nested dictionaries. This structure most closely matches the structure of the FlyCapture2 SDK in that each camera property has multiple sub-elements that control the feature. In this implementation, the standard camera properties are set using keys with ALL CAPS. The control of the Trigger Mode and Image Mode properties is handled separately, using a slightly different nesting structure than the other properties.

Below is a generic configuration for a Point Grey Blackfly PGE-23S6M-C device.

from labscript import *

from labscript_devices.FlyCapture2Camera.labscript_devices import FlyCapture2Camera

FlyCapture2Camera('gigeCamera',parent_device=parent,connection=conn,
            serial_number=1234567, # set to the camera serial number
            minimum_recovery_time=36e-6, # the minimum exposure time depends on the camera model & configuration
            camera_attributs={
                              'GAMMA':{
                                       'onOff':False,
                                       'absControl':True,
                                       'absValue':1},
                              'AUTO_EXPOSURE':{
                                       'onOff':True,
                                       'absControl':True,
                                       'autoManualMode':False,
                                       'absValue':0},
                              'GAIN':{
                                       'autoManualMode':False,
                                       'absControl':True,
                                       'absValue':0},
                              'SHARPNESS':{
                                       'onOff':False,
                                       'autoManualMode':False,
                                       'absValue':1024},
                              'FRAME_RATE':{
                                       'autoManualMode':False,
                                       'absControl':True},
                              'SHUTTER':{
                                       'autoManualMode':False,
                                       'absValue':0},
                              'TriggerMode':{
                                       'polarity':1,
                                       'source':0,
                                       'mode':1,
                                       'onOff':True},
                              'ImageMode':{
                                       'width':1920,
                                       'height':1200,
                                       'offsetX':0,
                                       'offsetY':0,
                                       'pixelFormat':'MONO16'}
            },
            manual_camera_attributes={'TriggerMode':{'onOff':False}})

start()

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


stop(1)

Detailed Documentation

class labscript_devices.FlyCapture2Camera.labscript_devices.FlyCapture2Camera(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)[source]

Bases: IMAQdxCamera

Thin sub-class of 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 = 'FlyCapture2 Camera'

Brief description of the device.

class labscript_devices.FlyCapture2Camera.blacs_tabs.FlyCapture2CameraTab(notebook, settings, restart=False)[source]

Bases: IMAQdxCameraTab

Thin sub-class of obj:IMAQdxCameraTab.

This sub-class only defines worker_class to point to the correct FlyCapture2CameraWorker.

worker_class = 'labscript_devices.FlyCapture2Camera.blacs_workers.FlyCapture2CameraWorker'
class labscript_devices.FlyCapture2Camera.blacs_workers.FlyCapture2CameraWorker(*args, **kwargs)[source]

Bases: IMAQdxCameraWorker

FlyCapture2 API Camera Worker.

Inherits from obj:IMAQdxCameraWorker. Defines interface_class and overloads get_attributes_as_dict to use FlyCapture2Camera.get_attributes() method.

get_attributes_as_dict(visibility_level)[source]

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

Parameters:

visibility_level (str) – Normally configures level of attribute detail to return. Is not used by FlyCapture2_Camera.

interface_class

alias of FlyCapture2_Camera

class labscript_devices.FlyCapture2Camera.blacs_workers.FlyCapture2_Camera(serial_number)[source]

Bases: object

The backend hardware interface class for the FlyCapture2Camera.

This class handles all of the API/hardware implementation details for the corresponding labscript device. It is used by the BLACS worker to send appropriate API commands to the camera for the standard BLACS camera operations (i.e. transition_to_buffered, get_attributes, snap, etc).

camera

Handle to connected camera.

Type:

PyCapture2.Camera

get_props

This list sets which values of each property object are returned when queried by get_attribute.

Type:

list

pixel_formats

An IntEnum object that is automatically populated with the supported pixel types of the connected camera.

Type:

IntEnum

width

Width of images for most recent acquisition. Used by _decode_image_data to format images correctly.

Type:

int

height

Height of images for most recent acquisition. Used by _decode_image_data to format images correctly.

Type:

int

pixelFormat

Pixel format name for most recent acquisition. Used by _decode_image_data to format images correctly.

Type:

str

_abort_acquisition

Abort flag that is polled during buffered acquisitions.

Type:

bool

Initialize FlyCapture2 API camera.

Searches all cameras reachable by the host using the provided serial number. Fails with API error if camera not found.

This function also does a significant amount of default configuration.

  • It defaults the grab timeout to 1 s

  • Ensures use of the API’s HighPerformanceRetrieveBuffer

  • Ensures the camera is in Format 7, Mode 0 with full frame readout and MONO8 pixels

  • If using a GigE camera, automatically maximizes the packet size and warns if Jumbo packets are not enabled on the NIC

Parameters:

serial_number (int) – serial number of camera to connect to

_decode_image_data(img)[source]

Formats returned FlyCapture2 API image buffers.

FlyCapture2 image buffers require significant formatting. This returns what one would expect from a camera. configure_acquisition must be called first to set image format parameters.

Parameters:

img (numpy.array) – A 1-D array image buffer of uint8 values to format

Returns:

Formatted array based on width, height,

and pixelFormat.

Return type:

numpy.array

_send_format7_config(image_config)[source]

Validates and sends the Format7 configuration packet.

Parameters:

image_config (PyCapture2.Format7ImageSettings) – Format7ImageSettings object to validate and send to camera.

abort_acquisition()[source]

Sets _abort_acquisition flag to break buffered acquisition loop.

close()[source]

Closes camera handle to the camera.

configure_acquisition(continuous=True, bufferCount=10)[source]

Configure acquisition buffer count and grab mode.

This method also saves image width, heigh, and pixelFormat to class attributes for returned image formatting.

Parameters:
  • continuous (bool, optional) – If True, camera will continuously acquire and only keep most recent frames in the buffer. If False, all acquired frames are kept and error occurs if buffer is exceeded. Default is True.

  • bufferCount (int, optional) – Number of memory buffers to use in the acquistion. Default is 10.

get_attribute(name)[source]

Return current values dictionary of attribute of the given name.

Parameters:

name (str) – Property name to read

Returns:

Dictionary of property values with structure as defined in

set_attribute.

Return type:

dict

get_attributes(visibility_level, writeable_only=True)[source]

Return a nested dict of all readable attributes.

Parameters:
  • visibility_level (str) – Not used.

  • writeable_only (bool, optional) – Not used

Returns:

Dictionary of property dictionaries

Return type:

dict

grab()[source]

Grab and return single image during pre-configured acquisition.

Returns:

Returns formatted image

Return type:

numpy.array

grab_multiple(n_images, images)[source]

Grab n_images into images array during buffered acquistion.

Grab method involves a continuous loop with fast timeout in order to poll _abort_acquisition for a signal to abort.

Parameters:
  • n_images (int) – Number of images to acquire. Should be same number as the bufferCount in configure_acquisition.

  • images (list) – List that images will be saved to as they are acquired

set_attribute(name, values)[source]

Set the values of the attribute of the given name using the provided dictionary values.

Generally, absControl should be used to configure settings. Note that invalid settings tend to coerce instead of presenting an error.

Parameters:
  • name (str) –

  • values (dict) –

    Dictionary of settings for the property. Allowed keys are:

    • ’onOff’: bool

    • ’autoManualMode’: bool

    • ’absControl’: bool

    • ’absValue’: float

    • ’valueA’: int

    • ’valueB’: int

    • ’onePush’: bool

set_attributes(attr_dict)[source]

Sets all attribues in attr_dict.

FlyCapture does not control all settings through same interface, so we must do them separately. Interfaces are: <Standard PROPERTY_TYPE>, TriggerMode, ImageMode

Parameters:

attr_dict (dict) – dictionary of property dictionaries to set for the camera. These property dictionaries assume a specific structure, outlined in set_attribute, set_trigger_mode and , set_image_mode methods.

set_image_mode(image_settings)[source]

Configures ROI and image control via Format 7, Mode 0 interface.

Parameters:

image_settings (dict) –

dictionary of image settings. Allowed keys:

  • ’pixelFormat’: valid pixel format string, i.e. ‘MONO8’

  • ’offsetX’: int

  • ’offsetY’: int

  • ’width’: int

  • ’height’: int

set_trigger_mode(trig_dict)[source]

Configures triggering options via Trigger Mode interface.

Parameters:

trig_dict (dict) –

dictionary with trigger mode property settings. Allowed keys:

  • ’onOff’: bool

  • ’polarity’: 0,1

  • ’source’: int

  • ’mode’: int

snap()[source]

Acquire a single image and return it

Returns:

Acquired image

Return type:

numpy.array

stop_acquisition()[source]

Tells camera to stop current acquistion.