herosdevices.hardware.teledyne.pvcam

HEROS drivers for teledyne cameras using the PVCam API.

Module Contents

herosdevices.hardware.teledyne.pvcam.pvc = None

herosdevices.hardware.teledyne.pvcam.DEFAULT_CONFIG

class herosdevices.hardware.teledyne.pvcam.PvcamCamera(cam_id: str, config_dict: dict, default_config: str | None = None, lib_path: str | None = None)

Bases: herosdevices.core.templates.camera.CameraTemplate

A class to interface with Teledyne PVCam Cameras.

It manages camera configuration, acquisition, and data streaming compatible with the atomiq camera template.

gain is the PVCam gain index, an integer >= 1. The valid indices depend on readout_port and speed_table_index. The setter places gain behind these keys, so set them first.

Parameters:

• cam_id – Serial number of the cam. Can be obtained for example from the PVCamTest program shipped with the vendor library. If you specify a wrong id, this driver will also log a list of available devices.

• lib_path – Path to vendor library. Can also be set via the environmental variable PVCAM_SDK_PATH

• config_dict – Dict of configuration values like shown in the json example above.

• default_config – Default key in config_dict to use.

Note

The vendor library must be obtained from the official website Make sure that after the installation either the environment variable PVCAM_SDK_PATH is set to the correct path or pass it via the lib_path argument.

Note

Other than the special config keys listed below, the keys are property names of the pyvcam Camera object. You can find the full list of available properties sometimes in the pyvcam documentation or by crawling this file.

Special Config Keys:

• exposure_time: exposure time in seconds. Automatically sets the coarsest resolution (exp_res camera parameter, ms or us) that represents the value exactly. The value must be a whole number of microseconds, otherwise a ValueError is raised. If you want to set the exp_res attribute manually, use the camera key exp_time (in the corresponding units) instead of exposure_time.

• trigger_delay: Is added to the trigger delay that can be obtained by PvcamCamera.trigger_delay and can be used for a cable and camera dependent delay.

• frame_count: number of frame buffers to set up, -1 means infinite number of frames. Note, that this is currently not supported though. If you need it implemented via a circular buffer, please open an issue or get in contact with us.

• post_processing: A dict of post processing parameters (only if camera supports it), of the form {'feature_name': ['param_name', 'param_value']}. See the documentation of the camera for details.

trigger_delay: float | None = None

default_config_dict

cam_id

get_pyvcam_property(name: str) → Any

Read a property value from the underlying pyvcam camera class.

This is for example useful to get possible configuration options for the camera. Possible properties can be found in the source code of the pyvcam driver.

Parameters:

name – name of the property as defined in the driver

get_camera

supported_features() → list[str]

Return the names of the camera helper features this class supports.

A feature is supported if the class overrides both its getter and its setter hook. If only one of the two is overridden, a warning is logged once per class and the feature is treated as unsupported.

Returns:

sorted feature names, equal to the names of the corresponding properties

property exposure_time: float | None

Exposure time in seconds. None if not set or not supported, see supported_features().

property roi_coordinates: tuple[int, int, int, int] | None

ROI as (x_offset, y_offset, width, height) in sensor pixels.

None if not set or not supported, see supported_features().

property binning: tuple[int, int] | None

Binning as (horizontal, vertical). None if not set or not supported, see supported_features().

property gain: float | None

Gain in the native unit of the driver, see Gain and frame rate.

The setter raises ValueError for NaN, infinity, booleans and non-numbers. The valid range is driver specific and checked by the driver. The getter returns None if not set or not supported, see supported_features().

property frame_rate: float | None

Frame rate limit in Hz, see Gain and frame rate.

Setting None removes the limit. Other values must be positive finite numbers, not booleans, otherwise the setter raises ValueError. The getter returns None if the limit is removed, if no frame rate is configured and if the feature is not supported, see supported_features().

acquisition_running: bool = False

payload_metadata: dict

keep_device_open = True

default_config: str

get_device() → collections.abc.Iterator[None]

Yield a device handle.

# use the device in a with statement
with self.get_device() as camera:
    camera.do_something()

open() → Any

Open the device handler and assign it to self._device.

teardown() → None

Release the device handler and potentially de-initialize the API.

start() → bool

Fire a software trigger.

Returns:

True if successful

stop() → bool

Abort the exposure and release queued buffers.

Returns:

True if successful

reset() → None

Reset the device by aborting any ongoing exposure, closing and re-opening the handler.

get_status() → dict

Get a dict with the current device status.

Returns:

A dict with the device status

get_available_options() → dict

Get all configurable options/features of the device.

Returns:

Dict mapping option names to their properties (value, readable, writable, etc.).

property config_dict: dict

Get a copy of the configuration dict.

Returns:

Copy of the configuration dict

update_configuration(new_config_dict: dict, merge: bool = True) → None

Update the configuration dict with new configuration.

Each dict key corresponds a (new) configuration name. Each value is a dict with config property -> config value.

Parameters:

• new_config_dict – A dict of configurations where the keys are the configuration names

• merge – If True, the new dict is recursively merged with the current set config dict. If False the old configurations with the provided names (keys) are overwritten. In this case each new configuration, merged over default_config_dict, must contain all _required_config_keys.

Raises:

ValueError – If merge is False and a required config key is missing. No configuration is changed.

get_configuration() → dict

Get the currently active configuration.

Returns:

The currently active configuration.

configure(config: str = '', metadata: dict | None = None) → bool

Configure the device with the known configuration config.

To add a configuration to the device, use update_configuration().

Parameters:

• config – Key (name) of the configuration

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

Returns:

False if the acquisition is running or if _set_config() returned False, True otherwise. Exceptions raised by _set_config() are not caught.

set_configuration

update_payload_metadata(metadata: dict, merge: bool = True) → None

Update metadata dict send with every emitted frame by the acquisition_data event method.

Parameters:

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

• merge – If True, the new dict is merged with the current set metadata dict. If False the old metadata is overwritten by the given dict.

arm(metadata: dict | None = None, kill_running: bool = False) → bool

Arm the device with the currently active configuration.

Parameters:

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

• kill_running – If True any running acquisition will be stopped. If False and an acquisition is

• running (already)

• raised. (an error will be)

Returns:

True if arming was successful else False

acquisition_data(frame: numpy.ndarray, metadata: dict | None = None) → tuple

Event to emit new frames.

Note

The dtype of the frame is not changed here.

Parameters:

• frame – The frame payload data (for example an image or an scope trace)

• metadata – The metadata which is passed along the payload. This argument takes precedence over the payload_metadata attribute (for example set by the update_payload_metadata method) while merging the two dicts.

Returns:

A tuple of image and metadata(-dict)

acquisition_started(metadata: dict | None = None) → dict

Event emitted when the acquisition thread starts.

Returns:

A dict with acquisition metadata

acquisition_stopped(metadata: dict | None = None) → dict

Event emitted when the acquisition thread stops.

Returns:

A dict with acquisition metadata

class herosdevices.hardware.teledyne.pvcam.Kinetix(cam_id: str, config_dict: dict, default_config: str | None = None, lib_path: str | None = None)

Bases: PvcamCamera

Driver class for the Kinetix camera.

This class adds the following device specific functionality:

• The trigger delay stored in the Kinetix.trigger_delay is calculated from the user specified trigger delay and the delay from the trigger input to the All Rows condition.

For more information refer to PvcamCamera

Note

It is well possible to that other PVCam cameras that support the fake global shutter concept (e.g. defined All Rows condition) can also be used with this driver.

trigger_delay: float | None = None

default_config_dict

cam_id

get_pyvcam_property(name: str) → Any

Read a property value from the underlying pyvcam camera class.

This is for example useful to get possible configuration options for the camera. Possible properties can be found in the source code of the pyvcam driver.

Parameters:

name – name of the property as defined in the driver

get_camera

supported_features() → list[str]

Return the names of the camera helper features this class supports.

A feature is supported if the class overrides both its getter and its setter hook. If only one of the two is overridden, a warning is logged once per class and the feature is treated as unsupported.

Returns:

sorted feature names, equal to the names of the corresponding properties

property exposure_time: float | None

Exposure time in seconds. None if not set or not supported, see supported_features().

property roi_coordinates: tuple[int, int, int, int] | None

ROI as (x_offset, y_offset, width, height) in sensor pixels.

None if not set or not supported, see supported_features().

property binning: tuple[int, int] | None

Binning as (horizontal, vertical). None if not set or not supported, see supported_features().

property gain: float | None

Gain in the native unit of the driver, see Gain and frame rate.

The setter raises ValueError for NaN, infinity, booleans and non-numbers. The valid range is driver specific and checked by the driver. The getter returns None if not set or not supported, see supported_features().

property frame_rate: float | None

Frame rate limit in Hz, see Gain and frame rate.

Setting None removes the limit. Other values must be positive finite numbers, not booleans, otherwise the setter raises ValueError. The getter returns None if the limit is removed, if no frame rate is configured and if the feature is not supported, see supported_features().

acquisition_running: bool = False

payload_metadata: dict

keep_device_open = True

default_config: str

get_device() → collections.abc.Iterator[None]

Yield a device handle.

# use the device in a with statement
with self.get_device() as camera:
    camera.do_something()

open() → Any

Open the device handler and assign it to self._device.

teardown() → None

Release the device handler and potentially de-initialize the API.

start() → bool

Fire a software trigger.

Returns:

True if successful

stop() → bool

Abort the exposure and release queued buffers.

Returns:

True if successful

reset() → None

Reset the device by aborting any ongoing exposure, closing and re-opening the handler.

get_status() → dict

Get a dict with the current device status.

Returns:

A dict with the device status

get_available_options() → dict

Get all configurable options/features of the device.

Returns:

Dict mapping option names to their properties (value, readable, writable, etc.).

property config_dict: dict

Get a copy of the configuration dict.

Returns:

Copy of the configuration dict

update_configuration(new_config_dict: dict, merge: bool = True) → None

Update the configuration dict with new configuration.

Each dict key corresponds a (new) configuration name. Each value is a dict with config property -> config value.

Parameters:

• new_config_dict – A dict of configurations where the keys are the configuration names

• merge – If True, the new dict is recursively merged with the current set config dict. If False the old configurations with the provided names (keys) are overwritten. In this case each new configuration, merged over default_config_dict, must contain all _required_config_keys.

Raises:

ValueError – If merge is False and a required config key is missing. No configuration is changed.

get_configuration() → dict

Get the currently active configuration.

Returns:

The currently active configuration.

configure(config: str = '', metadata: dict | None = None) → bool

Configure the device with the known configuration config.

To add a configuration to the device, use update_configuration().

Parameters:

• config – Key (name) of the configuration

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

Returns:

False if the acquisition is running or if _set_config() returned False, True otherwise. Exceptions raised by _set_config() are not caught.

set_configuration

update_payload_metadata(metadata: dict, merge: bool = True) → None

Update metadata dict send with every emitted frame by the acquisition_data event method.

Parameters:

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

• merge – If True, the new dict is merged with the current set metadata dict. If False the old metadata is overwritten by the given dict.

arm(metadata: dict | None = None, kill_running: bool = False) → bool

Arm the device with the currently active configuration.

Parameters:

• metadata – Metadata that is merged into the current payload metadata dict which is send with every emitted acquisition_data event.

• kill_running – If True any running acquisition will be stopped. If False and an acquisition is

• running (already)

• raised. (an error will be)

Returns:

True if arming was successful else False

acquisition_data(frame: numpy.ndarray, metadata: dict | None = None) → tuple

Event to emit new frames.

Note

The dtype of the frame is not changed here.

Parameters:

• frame – The frame payload data (for example an image or an scope trace)

• metadata – The metadata which is passed along the payload. This argument takes precedence over the payload_metadata attribute (for example set by the update_payload_metadata method) while merging the two dicts.

Returns:

A tuple of image and metadata(-dict)

acquisition_started(metadata: dict | None = None) → dict

Event emitted when the acquisition thread starts.

Returns:

A dict with acquisition metadata

acquisition_stopped(metadata: dict | None = None) → dict

Event emitted when the acquisition thread stops.

Returns:

A dict with acquisition metadata