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.
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:
Careful reading of the FlyCapture2 SDK docs.
Mirroring the FlyCap Viewer parameter names and values.
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 viacamera_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 toexpose()
- the value given here will be used only if nothing is passed toexpose()
.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 incamera_attributes
.stop_acquisition_timeout (float) –
5.0
How long, in seconds, to wait duringtransition_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 toTrue
(otherwise it is set toFalse
). This attribute is acessible in the lyse dataframe asdf[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'
, orNone
. IfNone
, 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 correctFlyCapture2CameraWorker
.- 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
. Definesinterface_class
and overloadsget_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:
- 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:
- height
Height of images for most recent acquisition. Used by
_decode_image_data
to format images correctly.- Type:
- pixelFormat
Pixel format name for most recent acquisition. Used by
_decode_image_data
to format images correctly.- Type:
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
.
- Formatted array based on
- 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.
- 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
- Return type:
- get_attributes(visibility_level, writeable_only=True)[source]
Return a nested dict of all readable attributes.
- 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.
- 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