API Reference

Core Library Functions

class LogLevel(value)

Bases: IntEnum

Defines the possible library log levels.

OFF = 0

Disable logging

ERROR = 1

Log only errors

WARNING = 2

Log warnings and above

INFO = 3

Log info and above

DEBUG = 4

Log debug and above

TRACE = 5

Log trace and above

class LogTarget(value)

Bases: IntFlag

Defines the possible log targets.

DISABLE = 0

Disable logging

STDOUT = 1

Log to stdout

STDERR = 2

Log to stderr

FILE = 4

Log to a file specified by the log_file parameter of Library.init()

WINDEBUG = 8

Log using OutputDebugString (Windows only)

class Library

Bases: object

Static class containing global library initialization functions

classmethod init(api_log_level: LogLevel = LogLevel.OFF, internal_log_level: LogLevel = LogLevel.OFF, log_targets: LogTarget = LogTarget.DISABLE, log_file: str | None = None)

Initializes the IC Imaging Control 4 Python library.

Parameters:

  • api_log_level (LogLevel, optional) – Configures the API log level for the library. Defaults to LogLevel.OFF.

  • internal_log_level (LogLevel, optional) – Configures the internal log level for the library. Defaults to LogLevel.OFF.

  • log_targets (LogTarget, optional) – Configures the log targets. Defaults to LogTarget.DISABLE.

  • log_file (Optional[str], optional) – If log_targets includes LogTarget.FILE, specifies the log file to use. Defaults to None.

Raises:

  • RuntimeError – Failed to initialize the library.

  • FileNotFoundError – Internal error.

classmethod exit()

Un-initializes the IC Imaging Control 4 Python library

Error Handling

class ErrorCode(value)

Bases: IntEnum

Enum describing IC4 error codes.

NoError = 0

No error occurred.

Unknown = 1

An unknown error occurred.

Internal = 2

An internal error (bug) occurred.

InvalidOperation = 3

The operation is not valid in the current state.

OutOfMemory = 4

Out of memory.

LibraryNotInitialized = 5

Library.init() was not called.

DriverError = 6

Device driver behaved unexpectedly.

InvalidParamVal = 7

An invalid parameter was passed in.

ConversionNotSupported = 8

The operation would require an image format conversion that is not supported.

NoData = 9

The requested data is not available.

GenICamFeatureNotFound = 101

No matching GenICam feature found.

GenICamDeviceError = 102

Error occured writing to device.

GenICamTypeMismatch = 103

Attempted an operation on the wrong node type, e.g. command_execute on an integer.

GenICamAccessDenied = 106

Tried to access a camera feature that is currently not available.

GenICamNotImplemented = 107

Tried to access a feature that is not implemented by the current camera.

GenICamValueError = 108

Tried to set an invalid value, e.g. out of range.

GenICamChunkdataNotConnected = 109

Tried to read a value that is only available if chunk data is connected to the property map.

BufferTooSmall = 50

A supplied buffer was too small to receive all available data.

SinkTypeMismatch = 52

Tried to call a sink type-specific function on an instance of a different sink type.

SnapAborted = 53

A snap operation was not completed, because the camera was stopped before all requested frames could be captured.

FileFailedToWriteData = 201

Failed to write data to a file.

FileAccessDenied = 202

Failed to write to a file, because the location was not writable.

FilePathNotFound = 203

Failed to write to a file, because the path was invalid.

FileFailedToReadData = 204

Failed to read data from a file.

DeviceInvalid = 13

The device has become invalid (e. g. it was unplugged).

DeviceNotFound = 16

The device was not found.

DeviceError = 17

The device behaved unexpectedly.

Ambiguous = 18

The parameter did not uniquely identify an item.

ParseError = 21

There was an error parsing the parameter or file.

Timeout = 27

The requested operation could not be completed before the timeout expired.

Incomplete = 34

The operation was only partially successful, e.g. not all properties of the grabber could be restored.

SinkNotConnected = 38

Sink is not yet connected.

ImageTypeMismatch = 39

The passed buffer does not have the expected ImageType.

SinkAlreadyAttached = 40

The sink passed in is already attached to another graph.

SinkConnectAborted = 41

The sink’s connect handler signaled an error.

HandlerAlreadyRegistered = 60

Attempted to register the same notification handler twice.

HandlerNotFound = 61

Attempted to use a non-existing notification handler.

exception IC4Exception(code: ErrorCode, message: str)

Bases: Exception

Exception raised for IC4 errors

code: ErrorCode

Error code

Returns:

The error code that caused this exception

Return type:

Error

message: str

Error message

Returns:

An error message for this exception

Return type:

str

classmethod raise_exception_from_last_error()

Device Enumeration

class DeviceInfo(h: c_void_p)

Bases: object

Contains information about a video capture device

property model_name: str

Get the model name from a device information object.

Returns:

The device’s model name

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property serial: str

Get the textual representation of the serial number from a device information object.

The format of the serial number string is device-specific.

Returns:

The device’s serial number

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property version: str

Get the device version from a device information object.

The format of the device version is device-specific.

Returns:

The device’s verion

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property user_id: str

Get the device’s user-defined identifier from a device information object.

If supported by the device, the device’s user-defined identifier can be configured through the DeviceUserID feature in the device’s property map.

Returns:

The device’s verion

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property unique_name: str

Get the device’s unique name from a device information object.

The unique name consists of an identifier for the device driver and the device’s serial number, allowing devices to be uniquely identified by a single string.

Returns:

The device’s unique name

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property interface: Interface

The interface the device represented by the device information object is attached to.

Returns:

The interface this device is attached to.

Return type:

Interface

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class TransportLayerType(value)

Bases: IntEnum

Defines the possible transport layer types.

UNKNOWN = 0

Other or unknown transport layer type

GIGEVISION = 1

The transport layer uses the GigEVision standard.

USB3VISION = 2

The transport layer uses the USB3 Vision standard.

class Interface(h: c_void_p)

Bases: object

Represents a device interface, e.g. a USB controller or network interface controller.

A interface can be queried for the list of devices attached to it.

Interface-specific configuration options are available interface’s property map.

property display_name: str

The display name of the interface

Returns:

The display name of the interface

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property property_map: PropertyMap

Open the property map for the device interface.

The property map can be used to query advanced interface information or configure the interface and its attached devices.

Returns:

The interface’s property map

Return type:

PropertyMap

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property devices: Sequence[DeviceInfo]

The devices attached to this interface

Returns:

The devices attached to this interface

Return type:

Sequence[DeviceInfo]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property transport_layer_name: str

The name of the transport layer that provides this interface object.

This string can be interpreted as a name for the driver providing access to devices on the interface.

Returns:

The name of the transport layer that provides this interface object.

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property transport_layer_type: TransportLayerType

The type of the transport layer used by this interface.

Returns:

The type of the transport layer used by this interface.

Return type:

TransportLayerType

property transport_layer_version: str

The version of the transport layer that provides this interface object.

This string can be interpreted as driver version for the driver providing access devices on the interface.

Returns:

The version of the transport layer that provides this interface object.

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class DeviceEnum

Bases: object

The device enumerator class is used to gather information about the video capture devices attached to the system.

To query the list of all available video capture devices, use the class method DeviceEnum.devices.

To query the topology of device interfaces and their attached devices, use the class method DeviceEnum.interfaces.

Creating a device enumerator object allows registering a callback function that is called when the list of available devices or interfaces changes.

classmethod devices() → Sequence[DeviceInfo]

Return a list of DeviceInfo objects representing the video capture devices attached to the system

Returns:

The devices attached to this system

Return type:

Sequence[DeviceInfo]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

classmethod interfaces() → Sequence[Interface]

Return a list of Interface objects representing the device interfaces of the system.

Device interfaces can be network adapters, USB controllers or other hardware.

Returns:

The device interfaces of this system

Return type:

Sequence[Interface]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class DeviceListChangedNotificationToken(func: Callable[[c_void_p, c_void_p], None], deleter: Callable[[c_void_p], None])

Bases: object

Represents a registered callback.

When a callback function is registered using event_add_device_list_changed, a token is returned.

The token can then be used to remove the callback using event_remove_device_list_changed at a later time.

event_add_device_list_changed(handler: Callable[[DeviceEnum], None]) → DeviceListChangedNotificationToken

Register a function to be called when the list of available video capture devices has (potentially) changed.

Parameters:

handler (Callable[[DeviceEnum], None]) – The function to be called when the list of available video capture devices has changed.

Returns:

A token that can be used to unregister the callback using DeviceEnum.event_remove_device_list_changed().

Return type:

DeviceListChangedNotificationToken

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_remove_device_list_changed(token: DeviceListChangedNotificationToken)

Unregister a device-list-changed handler.

Parameters:

token (DeviceListChangedNotificationToken) – The token that was returned from the registration function

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Grabber

class StreamSetupOption(value)

Bases: IntEnum

Enum describing options to customize the behavior for Grabber.stream_setup().

ACQUISITION_START = 1

Immediately start image acquisition after the stream was set up.

DEFER_ACQUISITION_START = 0

Don’t start image acquisition after the stream was set up. The program must call Grabber.acquisition_start() or use the AcquisitionStart command on the device’s property map to start image acquisition.

class Grabber

Bases: object

Represents an opened video capture device, allowing device configuration and stream setup.

The Grabber object is the core component used when working with video capture devices.

Some objects, e.g. ImageBuffer, can keep the device and/or driver opened as long as they exist, since they point into device driver memory. To free all device-related resources, all objects references have to be deleted, or ImageBuffer objects have to release their internal reference by calling their ImageBuffer.release() function.

class DeviceLostNotificationToken(func: Callable[[c_void_p, c_void_p], None], deleter: Callable[[c_void_p], None])

Bases: object

Represents a registered device-lost callback.

When a callback function is registered using event_add_device_lost(), a token is returned.

The token can then be used to remove the callback using event_remove_device_lost() at a later time.

property sink: Sink

Return the Sink that was passed to stream_setup() while the data stream is active.

Returns:

Sink

Raises:

RuntimeError – If there was no sink set

property display: Display

Return the Display that was passed to stream_setup while the data stream is active.

Returns:

Display

Raises:

RuntimeError – If there was no display set

device_open(dev: DeviceInfo | str) → None

Open the video capture device specified by the passed identifier or device information object.

Parameters:

dev (DeviceInfo|str) – A identifier or device information object representing the video capture device to be opened

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

If the passed identifier does not uniquely identify a connected device by its model name, unique name, serial or user-defined name, the function fails with ErrorCode.Ambiguous.

device_close() → None

Close the currently opened video capture device.

If there is an aqcuisition active, the acquisition is stopped. If there is a stream established, the stream is stopped.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property is_device_open: bool

Check whether a device is opened.

Returns:

True, if there is currently a video capture device opened, otherwise False.

Return type:

bool

property is_device_valid: bool

Check whether the opened device is accessible.

Returns:

True, if the currently opened video capture device is still accessible, otherwise False.

Return type:

bool

Note

There are multiple reasons for why this function may return False:

  • No device has been opened

  • The device was disconnected

  • There is a loose hardware connection

  • There was an internal error in the video capture device

  • There was a driver error

property device_info: DeviceInfo

Return information about the currently opened video capture device.

Returns:

DeviceInfo

Raises:

IC4Exception – If the Grabber does not have a deviced opened.

stream_setup(sink: Sink | None = None, display: Display | None = None, setup_option: StreamSetupOption = StreamSetupOption.ACQUISITION_START) → None

Establish the data stream from the device.

A data stream is required for image acquisition from the video capture device, and must include a sink, or a display, or both.

Parameters:

  • sink (Sink) – An object derived from the Sink class

  • display (Display) – An object derived from the Display class

  • setup_option (StreamSetupOption) – Specifies whether to immediately start acquisition after the

  • (Default (data stream was set up successfully) – StreamSetupOption.ACQUISITION_START)

Note

A device has to be opened using device_open() or one of its sibling functions before calling stream_setup.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

stream_stop() → None

Stop the data stream from the device.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property is_streaming: bool

Check if a stream is running.

Returns:

True if a data stream has been established, otherwise False.

Return type:

bool

acquisition_start() → None

Start the acquisition of images from the video capture device.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

A data stream has to be established before calling acquisition_start() or by using stream_setup(). This operation is equivalent to executing the AcquisitionStart command on the video capture device’s property map.

acquisition_stop() → None

Stops the acquisition of images from the video capture device.

Raises:

IC4Exception – If the acquisition could not be stopped. Check IC4Exception.code and IC4Exception.message for details.

Note

Acquisition has to be started using acquisition_start() or stream_setup() before calling acquisition_stop. This operation is equivalent to executing the AcquisitionStop command on the video capture device’s property map.

property is_acquisition_active: bool

True if image acquisition was started, otherwise False.

property device_property_map: PropertyMap

Return the property map for the currently opened video capture device.

The property map returned from this function is the origin for all device feature manipulation operations.

Returns:

PropertyMap

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property driver_property_map: PropertyMap

Return the property map for the driver of the currently opened video capture device.

The property map returned from this function is the origin for driver-related feature manipulation operations.

Returns:

PropertyMap

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class StreamStatistics(device_delivered: int, device_transmission_error: int, device_underrun: int, transform_delivered: int, transform_underrun: int, sink_delivered: int, sink_underrun: int, sink_ignored: int)

Bases: object

Contains statistics about a data stream.

device_delivered: int

Number of frames delivered by the video capture device

device_transmission_error: int

Number of frames dropped because of transmission errors, e.g. unrecoverable packet loss

device_underrun: int

Number of frames dropped by the video capture device driver, because there were no free image buffers available

transform_delivered: int

Number of frames transformed by the transform element

transform_underrun: int

Number of frames dropped by the transform element, because there wer no free image buffers available

sink_delivered: int

Number of frames processed by the sink

sink_underrun: int

Number of frames dropped by the sink, because there was no free image buffer available

sink_ignored: int

Number of frames ignored by the sink, because the sink was disabled or not instructed to process the data

property stream_statistics: StreamStatistics

Queries statistics for the currently active or previously stopped data stream.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_add_device_lost(handler: Callable[[Grabber], None]) → DeviceLostNotificationToken

Register a callback function to be called in the event that the currently opened video capture device becomes unavailable.

Parameters:

handler (Callable[[Grabber], None]) – The callback function to be called if the device is lost

Returns:

A token that can be used to unregister the callback using event_remove_device_lost().

Return type:

DeviceLostNotificationToken

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_remove_device_lost(token: DeviceLostNotificationToken)

Unregister a device-lost handler that was previously registered using event_add_device_lost().

Parameters:

token (DeviceLostNotificationToken) – The token that was returned from the registration function

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

device_save_state() → bytearray

Saves the opened device and all its settings in a memory buffer.

Returns:

A byte array containing the device state information.

Return type:

bytearray

Note

Use device_open_from_state() to restore the device state at a later time.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

device_open_from_state(arr: bytearray) → None

Restore the opened device and its settings from a memory buffer containing data that was previously written by device_save_state().

Parameters:

arr (bytearray) – A buffer containing data that was written by device_save_state()

Note

The grabber must not have a device opened when calling this function.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

device_save_state_to_file(path: Path | str) → None

Save the opened device and all its settings in a file.

Parameters:

path (Path|str) – Path to the file to save the device state in.

Note

Use device_open_from_state_file() to restore the device state at a later time.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

device_open_from_state_file(path: Path | str) → None

Restore the opened device and its settings from a file that was previously written by device_save_state_to_file().

Parameters:

path (Path|str) – Path to the file to containing the device state.

Note

The grabber must not have a device opened when calling this function.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Device Properties

class PropId

Bases: object

Contains constans for most properties available in cameras.

ACQUISITION_BURST_FRAME_COUNT = 'AcquisitionBurstFrameCount'

Number of frames to acquire for each trigger.

ACQUISITION_BURST_INTERVAL = 'AcquisitionBurstInterval'

Minimum interval between frames in an acquisition burst.

ACQUISITION_FRAME_RATE = 'AcquisitionFrameRate'

Controls the acquisition rate at which the frames are captured.

ACQUISITION_MODE = 'AcquisitionMode'

Sets the acquisition mode of the device. It defines mainly the number of frames to capture during an acquisition and the way the acquisition stops.

ACQUISITION_START = 'AcquisitionStart'

Starts the Acquisition of the device. The number of frames captured is specified by AcquisitionMode.

ACQUISITION_STOP = 'AcquisitionStop'

Stops the Acquisition of the device at the end of the current Frame. It is mainly used when AcquisitionMode is Continuous but can be used in any acquisition mode.

ACTION_DEVICE_KEY = 'ActionDeviceKey'

Provides the device key that allows the device to check the validity of action commands. The device internal assertion of an action signal is only authorized if the ActionDeviceKey and the action device key value in the protocol message are equal.

ACTION_GROUP_KEY = 'ActionGroupKey'

Provides the key that the device will use to validate the action on reception of the action protocol message.

ACTION_GROUP_MASK = 'ActionGroupMask'

Provides the mask that the device will use to validate the action on reception of the action protocol message.

ACTION_QUEUE_SIZE = 'ActionQueueSize'

Indicates the size of the scheduled action commands queue. This number represents the maximum number of scheduled action commands that can be pending at a given point in time.

ACTION_SCHEDULER_CANCEL = 'ActionSchedulerCancel'

Cancels all scheduled actions.

ACTION_SCHEDULER_COMMIT = 'ActionSchedulerCommit'

Schedules the action to be executed time specified by ActionSchedulerTime, with optional repetition in intervals of ActionSchedulerInterval.

ACTION_SCHEDULER_INTERVAL = 'ActionSchedulerInterval'

Action repetition interval. A value of 0 schedules the action to be executed only once.

ACTION_SCHEDULER_STATUS = 'ActionSchedulerStatus'

Indicates whether there are actions scheduled.

ACTION_SCHEDULER_TIME = 'ActionSchedulerTime'

Camera time for when the action is to be scheduled.

ACTION_SELECTOR = 'ActionSelector'

Selects to which Action Signal further Action settings apply.

AUTO_FOCUS_ROI_ENABLE = 'AutoFocusROIEnable'

Enable the region of interest for auto focus.

AUTO_FOCUS_ROI_HEIGHT = 'AutoFocusROIHeight'

Vertical size of the auto focus region of interest.

AUTO_FOCUS_ROI_LEFT = 'AutoFocusROILeft'

Horizontal offset of the auto focus region of interest.

AUTO_FOCUS_ROI_TOP = 'AutoFocusROITop'

Vertical offset of the auto focus region of interest.

AUTO_FOCUS_ROI_WIDTH = 'AutoFocusROIWidth'

Horizontal size of the auto focus region of interest.

AUTO_FUNCTIONS_ROI_ENABLE = 'AutoFunctionsROIEnable'

Enable the region of interest for auto functions.

AUTO_FUNCTIONS_ROI_HEIGHT = 'AutoFunctionsROIHeight'

Vertical size of the auto functions region of interest.

AUTO_FUNCTIONS_ROI_LEFT = 'AutoFunctionsROILeft'

Horizontal offset of the auto functions region of interest.

AUTO_FUNCTIONS_ROI_PRESET = 'AutoFunctionsROIPreset'

Select a predefined region of interest for auto functions.

AUTO_FUNCTIONS_ROI_TOP = 'AutoFunctionsROITop'

Vertical offset of the auto functions region of interest.

AUTO_FUNCTIONS_ROI_WIDTH = 'AutoFunctionsROIWidth'

Horizontal size of the auto functions region of interest.

BALANCE_RATIO = 'BalanceRatio'

Controls ratio of the selected color component to a reference color component. It is used for white balancing.

BALANCE_RATIO_SELECTOR = 'BalanceRatioSelector'

This enumeration selects a balance ratio control to configuration. Once a balance ratio control has been selected, all changes to the balance ratio settings will be applied to the selected control.

BALANCE_WHITE_AUTO = 'BalanceWhiteAuto'

Controls the mode for automatic white balancing between the color channels. The white balancing ratios are automatically adjusted.

BALANCE_WHITE_AUTO_PRESET = 'BalanceWhiteAutoPreset'

Selects a specific preset for automatic white balance.

BALANCE_WHITE_MODE = 'BalanceWhiteMode'

Configures the way auto white balance works.

BALANCE_WHITE_TEMPERATURE = 'BalanceWhiteTemperature'

Adjusts the white balance controls to match the ambient light temperature

BALANCE_WHITE_TEMPERATURE_PRESET = 'BalanceWhiteTemperaturePreset'

Selects a specific white balance preset.

BINNING_HORIZONTAL = 'BinningHorizontal'

Number of horizontal photo-sensitive cells to combine together. This increases the intensity (or signal to noise ratio) of the pixels and reduces the horizontal resolution (width) of the image. A value of 1 indicates that no horizontal binning is performed by the camera.

BINNING_VERTICAL = 'BinningVertical'

Number of vertical photo-sensitive cells to combine together. This increases the intensity (or signal to noise ratio) of the pixels and reduces the vertical resolution (height) of the image. A value of 1 indicates that no vertical binning is performed by the camera.

BLACK_LEVEL = 'BlackLevel'

Controls the analog black level as an absolute physical value. This represents a DC offset applied to the video signal

CHUNK_BLOCK_ID = 'ChunkBlockId'

Returns the block ID (frame number) of the image

CHUNK_ENABLE = 'ChunkEnable'

Enables the inclusion of the selected Chunk data in the payload of the image.

CHUNK_EXPOSURE_TIME = 'ChunkExposureTime'

Returns the exposure time used to capture the image.

CHUNK_GAIN = 'ChunkGain'

Returns the gain used to capture the image.

CHUNK_IMAGE = 'ChunkImage'

Returns the entire image data included in the payload.

CHUNK_IMX174_FRAME_ID = 'ChunkIMX174FrameId'

IMX174 double exposure frame id.

CHUNK_IMX174_FRAME_SET = 'ChunkIMX174FrameSet'

IMX174 double exposure frame set identifier.

CHUNK_MODE_ACTIVE = 'ChunkModeActive'

Activates the inclusion of Chunk data in the payload of the image.

CHUNK_MULTI_FRAME_SET_FRAME_ID = 'ChunkMultiFrameSetFrameId'

Returns the frame id in the frame set in Multi Frame Set Output Mode.

CHUNK_MULTI_FRAME_SET_ID = 'ChunkMultiFrameSetId'

Returns the id of the frame set in Multi Frame Set Output Mode.

CHUNK_SELECTOR = 'ChunkSelector'

Selects which Chunk to enable or control

COLOR_TRANSFORMATION_ENABLE = 'ColorTransformationEnable'

Activates the selected Color Transformation module.

COLOR_TRANSFORMATION_SELECTOR = 'ColorTransformationSelector'

Selects which Color Transformation module is controlled by the various Color Transformation features.

COLOR_TRANSFORMATION_VALUE = 'ColorTransformationValue'

Represents the value of the selected Gain factor or Offset inside the Transformation matrix.

COLOR_TRANSFORMATION_VALUE_SELECTOR = 'ColorTransformationValueSelector'

Selects the Gain factor or Offset of the Transformation matrix to access in the selected Color Transformation module.

CONTRAST = 'Contrast'

Controls Contrast.

DECIMATION_HORIZONTAL = 'DecimationHorizontal'

Horizontal sub-sampling of the image. This reduces the horizontal resolution (width) of the image by the specified horizontal decimation factor.

DECIMATION_VERTICAL = 'DecimationVertical'

Vertical sub-sampling of the image. This reduces the vertical resolution (height) of the image by the specified vertical decimation factor.

DENOISE = 'Denoise'

Controls the strength of the denoise algorithm.

DEVICE_EVENT_CHANNEL_COUNT = 'DeviceEventChannelCount'

Indicates the number of event channels supported by the device.

DEVICE_FACTORY_RESET = 'DeviceFactoryReset'

Resets all user-programmable non-volatile memory to default. After reset, the device must be rediscovered.

DEVICE_FIRMWARE_VERSION = 'DeviceFirmwareVersion'

Version of the device.

Controls the current heartbeat timeout of the specific Link.

Selects which Link of the device to control.

DEVICE_MODEL_NAME = 'DeviceModelName'

Model of the device.

DEVICE_RESET = 'DeviceReset'

Resets the device to its power up state. After reset, the device must be rediscovered.

DEVICE_SCAN_TYPE = 'DeviceScanType'

Returns the scan type of the sensor of the device.

DEVICE_SERIAL_NUMBER = 'DeviceSerialNumber'

Device’s serial number. This string is a unique identifier of the device.

DEVICE_SFNC_VERSION_MAJOR = 'DeviceSFNCVersionMajor'

Major version of the Standard Features Naming Convention that was used to create the device’s GenICam XML

DEVICE_SFNC_VERSION_MINOR = 'DeviceSFNCVersionMinor'

Minor version of the Standard Features Naming Convention that was used to create the device’s GenICam XML

DEVICE_SFNC_VERSION_SUB_MINOR = 'DeviceSFNCVersionSubMinor'

Sub minor version of the Standard Features Naming Convention that was used to create the device’s GenICam XML

DEVICE_STREAM_CHANNEL_COUNT = 'DeviceStreamChannelCount'

Indicates the number of streaming channels supported by the device.

DEVICE_STREAM_CHANNEL_ENDIANNESS = 'DeviceStreamChannelEndianness'

Endianess of multi-byte pixel data for this stream.

Index of device`s Link to use for streaming the specifed stream channel.

DEVICE_STREAM_CHANNEL_PACKET_SIZE = 'DeviceStreamChannelPacketSize'

Specifies the stream packet size, in bytes, to send on the selected channel.

DEVICE_STREAM_CHANNEL_SELECTOR = 'DeviceStreamChannelSelector'

Selects the stream channel to control.

DEVICE_STREAM_CHANNEL_TYPE = 'DeviceStreamChannelType'

Reports the type of the stream channel.

DEVICE_TEMPERATURE = 'DeviceTemperature'

Device temperature in degrees Celsius (°C). It is measured at the location selected by DeviceTemperatureSelector.

DEVICE_TEMPERATURE_SELECTOR = 'DeviceTemperatureSelector'

Selects the location within the device, where the temperature will be measured.

DEVICE_TL_TYPE = 'DeviceTLType'

Transport Layer type of the device.

DEVICE_TL_VERSION_MAJOR = 'DeviceTLVersionMajor'

Major version of the Transport Layer of the device.

DEVICE_TL_VERSION_MINOR = 'DeviceTLVersionMinor'

Minor version of the Transport Layer of the device.

DEVICE_TL_VERSION_SUB_MINOR = 'DeviceTLVersionSubMinor'

Sub minor version of the Transport Layer of the device.

DEVICE_TYPE = 'DeviceType'

Returns the device type.

DEVICE_USER_ID = 'DeviceUserID'

User-programmable device identifier.

DEVICE_VENDOR_NAME = 'DeviceVendorName'

Name of the manufacturer of the device.

DEVICE_VERSION = 'DeviceVersion'

Version of the device.

DISABLE_INFO_OVERLAY = 'DisableInfoOverlay'

Disables the HDMI format info overlay.

EVENT_EXPOSURE_END = 'EventExposureEnd'

Unique identifier of the Exposure End event. Use this parameter to get notified when the event occurs.

EVENT_EXPOSURE_END_FRAME_ID = 'EventExposureEndFrameID'

Frame ID of the Exposure End event.

EVENT_EXPOSURE_END_TIMESTAMP = 'EventExposureEndTimestamp'

Timestamp of the Exposure End event.

EVENT_FOCUS_MOVE_COMPLETED = 'EventFocusMoveCompleted'

Unique identifier of the Focus Move Completed event. Use this parameter to get notified when the event occurs.

EVENT_FOCUS_MOVE_COMPLETED_FOCUS = 'EventFocusMoveCompletedFocus'

Focus value of the Focus Move Completed event.

EVENT_FOCUS_MOVE_COMPLETED_TIMESTAMP = 'EventFocusMoveCompletedTimestamp'

Timestamp of the Focus Move Completed event.

EVENT_FRAME_TRIGGER_MISSED = 'EventFrameTriggerMissed'

Unique identifier of the Frame Trigger Missed event. Use this parameter to get notified when the event occurs.

EVENT_FRAME_TRIGGER_MISSED_TIMESTAMP = 'EventFrameTriggerMissedTimestamp'

Timestamp of the Frame Trigger Missed event.

EVENT_LINE1_FALLING_EDGE = 'EventLine1FallingEdge'

Unique identifier of the Line1 Falling Edge event. Use this parameter to get notified when the event occurs.

EVENT_LINE1_FALLING_EDGE_TIMESTAMP = 'EventLine1FallingEdgeTimestamp'

Timestamp of the Line1 Falling Edge event.

EVENT_LINE1_RISING_EDGE = 'EventLine1RisingEdge'

Unique identifier of the Line1 Rising Edge event. Use this parameter to get notified when the event occurs.

EVENT_LINE1_RISING_EDGE_TIMESTAMP = 'EventLine1RisingEdgeTimestamp'

Timestamp of the Line1 Rising Edge event.

EVENT_NOTIFICATION = 'EventNotification'

Enables event notifications for the currently selected event. The event can selected using the Event Selector parameter.

EVENT_SELECTOR = 'EventSelector'

Sets the event notification to be enabled. The notification can be enabled using the Event Notification parameter.

EVENT_TEST = 'EventTest'

Unique identifier of the Test event. Use this parameter to get notified when the event occurs.

EVENT_TEST_TIMESTAMP = 'EventTestTimestamp'

Timestamp of the test event.

EVENT_ZOOM_MOVE_COMPLETED = 'EventZoomMoveCompleted'

Unique identifier of the Zoom Move Completed event. Use this parameter to get notified when the event occurs.

EVENT_ZOOM_MOVE_COMPLETED_TIMESTAMP = 'EventZoomMoveCompletedTimestamp'

Timestamp of the Zoom Move Completed event.

EVENT_ZOOM_MOVE_COMPLETED_ZOOM = 'EventZoomMoveCompletedZoom'

Zoom value of the Zoom Move Completed event.

EXPAND_OUTPUT_RANGE = 'ExpandOutputRange'

Use the full brightness range when receiving YUV data via HDMI.

EXPOSURE_AUTO = 'ExposureAuto'

Sets the automatic exposure mode when ExposureMode is Timed.

EXPOSURE_AUTO_HIGHLIGH_REDUCTION = 'ExposureAutoHighlighReduction'

Lets the ExposureAuto/GainAuto algorithm try to avoid over-exposures.

EXPOSURE_AUTO_HIGHLIGHT_REDUCTION = 'ExposureAutoHighlightReduction'

Lets the ExposureAuto/GainAuto algorithm try to avoid over-exposures.

EXPOSURE_AUTO_LOWER_LIMIT = 'ExposureAutoLowerLimit'

Lower limit of the ExposureAuto function.

EXPOSURE_AUTO_REFERENCE = 'ExposureAutoReference'

Configures the target image brightness of the ExposureAuto/GainAuto algorithm.

EXPOSURE_AUTO_UPPER_LIMIT = 'ExposureAutoUpperLimit'

Upper limit of the ExposureAuto function.

EXPOSURE_AUTO_UPPER_LIMIT_AUTO = 'ExposureAutoUpperLimitAuto'

Automatically sets the upper limit to match the Acquisition Frame Rate.

EXPOSURE_TIME = 'ExposureTime'

Sets the Exposure time when ExposureMode is Timed and ExposureAuto is Off. This controls the duration where the photosensitive cells are exposed to light.

FILE_ACCESS_BUFFER = 'FileAccessBuffer'

Defines the intermediate access buffer that allows the exchange of data between the device file storage and the application.

FILE_ACCESS_LENGTH = 'FileAccessLength'

Controls the Length of the mapping between the device file storage and the FileAccessBuffer.

FILE_ACCESS_OFFSET = 'FileAccessOffset'

Controls the Offset of the mapping between the device file storage and the FileAccessBuffer.

FILE_OPEN_MODE = 'FileOpenMode'

Selects the access mode in which a file is opened in the device.

FILE_OPERATION_EXECUTE = 'FileOperationExecute'

Executes the operation selected by FileOperationSelector on the selected file.

FILE_OPERATION_RESULT = 'FileOperationResult'

Represents the file operation result. For Read or Write operations, the number of successfully read/written bytes is returned.

FILE_OPERATION_SELECTOR = 'FileOperationSelector'

Selects the target operation for the selected file in the device. This Operation is executed when the FileOperationExecute feature is called.

FILE_OPERATION_STATUS = 'FileOperationStatus'

Represents the file operation execution status.

FILE_SELECTOR = 'FileSelector'

Selects the target file in the device.

FILE_SIZE = 'FileSize'

Represents the size of the selected file in bytes.

FOCUS = 'Focus'

Changes the Focus setting of the lens.

FOCUS_AUTO = 'FocusAuto'

Enables automatic Focus control.

GAIN = 'Gain'

Controls the gain as an absolute physical value. This is an amplification factor applied to he video signal.

GAIN_AUTO = 'GainAuto'

Sets the automatic gain control mode.

GAIN_AUTO_LOWER_LIMIT = 'GainAutoLowerLimit'

Lower limit of the GainAuto function.

GAIN_AUTO_UPPER_LIMIT = 'GainAutoUpperLimit'

Upper limit of the GainAuto function.

GAIN_MODE = 'GainMode'

Configures the sensor-specific Gain (LCG/HCG) setting

GAMMA = 'Gamma'

Controls the gamma correction of pixel intensity. This is typically used to compensate for nonlinearity of the display system (such as CRT).

GEV_GVSP_EXTENDED_ID_MODE = 'GevGVSPExtendedIDMode'

Enables the extended IDs mode

GEV_SCPS_DO_NOT_FRAGMENT = 'GevSCPSDoNotFragment'

The state of this feature is copied into the “do not fragment” bit of IP header of each stream packet. It can be used by the application to prevent IP fragmentation of packets on the stream channel.

GEV_SCPS_PACKET_SIZE = 'GevSCPSPacketSize'

This GigE Vision specific feature corresponds to DeviceStreamChannelPacketSize and should be kept in sync with it. It specifies the stream packet size, in bytes, to send on the selected channel for a GVSP transmitter or specifies the maximum packet size supported by a GVSP receiver.

GP_IN = 'GPIn'

Status of the digital input pin.

GP_OUT = 'GPOut'

Status of the digital output pin.

HEIGHT = 'Height'

Height of the image provided by the device (in pixels).

HEIGHT_MAX = 'HeightMax'

Maximum height of the image (in pixels). This dimension is calculated after vertical binning, decimation or any other function changing the vertical dimension of the image.

HUE = 'Hue'

Color Hue

IMX174_HARDWARE_WDR_ENABLE = 'IMX174HardwareWDREnable'

Enable IMX174 WDR mode. This mode enables setting a second, longer exposure time (IMX174 WDR Shutter 2), which is used for every other frame.

IMX174_HARDWARE_WDR_SHUTTER_MODE = 'IMX174HardwareWDRShutterMode'

Select the IMX174 WDR shutter mode. This mode decides whether the second shutter time can be choosen freely, or is fixed at a multiple of the configured ExposureTime.

IMX174_WDR_SHUTTER2 = 'IMX174WDRShutter2'

Exposure time that is used for every other frame, if IMX174 WDR mode is enabled.

IMX_LOW_LATENCY_TRIGGER_MODE = 'IMXLowLatencyTriggerMode'

Enables the low-latency mode for IMX global shutter sensors. This mode reduces the jitter between trigger input and exposure start, but disallows trigger overlap.

INPUT_BITS = 'InputBits'

The detected bits per pixel of the HDMI source.

INPUT_FP1KS = 'InputFp1ks'

The detected frame rate of the HDMI source.

INPUT_HEIGHT = 'InputHeight'

The detected width of the HDMI input image.

INPUT_WIDTH = 'InputWidth'

The detected width of the HDMI input image.

IR_CUT_FILTER_ENABLE = 'IRCutFilterEnable'

Enables the IRCutFilter in from of the sensor.

IRIS = 'Iris'

Changes the Iris setting of the lens.

IRIS_AUTO = 'IrisAuto'

Enables automatic Iris control.

LUT_ENABLE = 'LUTEnable'

Activates the LUT.

LUT_INDEX = 'LUTIndex'

Control the index (offset) of the coefficient to access in the LUT.

LUT_SELECTOR = 'LUTSelector'

Selects which LUT to control.

LUT_VALUE = 'LUTValue'

Returns or sets the Value at entry LUTIndex of the LUT.

LUT_VALUE_ALL = 'LUTValueAll'

Accesses all the LUT coefficients in a single access without using individual LUTIndex.

MULTI_FRAME_SET_OUTPUT_MODE_CUSTOM_GAIN = 'MultiFrameSetOutputModeCustomGain'

Enables the sensor to use customizable gain values for the different frames of a frame set.

MULTI_FRAME_SET_OUTPUT_MODE_ENABLE = 'MultiFrameSetOutputModeEnable'

Enables the sensor to output a sequence of 2 or 4 frames with configurable exposure times and gain values.

MULTI_FRAME_SET_OUTPUT_MODE_EXPOSURE_TIME0 = 'MultiFrameSetOutputModeExposureTime0'

Configures the exposure time for frame 0 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_EXPOSURE_TIME1 = 'MultiFrameSetOutputModeExposureTime1'

Configures the exposure time for frame 1 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_EXPOSURE_TIME2 = 'MultiFrameSetOutputModeExposureTime2'

Configures the exposure time for frame 2 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_EXPOSURE_TIME3 = 'MultiFrameSetOutputModeExposureTime3'

Configures the exposure time for frame 3 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_FRAME_COUNT = 'MultiFrameSetOutputModeFrameCount'

Selects the number of frames in multi frame set output mode.

MULTI_FRAME_SET_OUTPUT_MODE_GAIN0 = 'MultiFrameSetOutputModeGain0'

Configures the gain for frame 0 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_GAIN1 = 'MultiFrameSetOutputModeGain1'

Configures the gain for frame 1 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_GAIN2 = 'MultiFrameSetOutputModeGain2'

Configures the gain for frame 2 of the frame set.

MULTI_FRAME_SET_OUTPUT_MODE_GAIN3 = 'MultiFrameSetOutputModeGain3'

Configures the gain for frame 3 of the frame set.

OFFSET_AUTO_CENTER = 'OffsetAutoCenter'

Automatically adjust the values of OffsetX and OffsetY to select the center region of the sensor.

OFFSET_X = 'OffsetX'

Horizontal offset from the origin to the region of interest (in pixels).

OFFSET_Y = 'OffsetY'

Vertical offset from the origin to the region of interest (in pixels).

PAYLOAD_SIZE = 'PayloadSize'

Provides the number of bytes transferred for each image or chunk on the stream channel. This includes any end-of-line, end-of-frame statistics or other stamp data. This is the total size of data payload for a data block.

PIXEL_FORMAT = 'PixelFormat'

Format of the pixels provided by the device

PTP_CLOCK_ACCURACY = 'PtpClockAccuracy'

Indicates the expected accuracy of the device PTP clock when it is the grandmaster, or in the event it becomes the grandmaster.

PTP_ENABLE = 'PtpEnable'

Enables the Precision Time Protocol (PTP).

PTP_STATUS = 'PtpStatus'

Returns the current state of the PTP clock.

REVERSE_X = 'ReverseX'

Flip the image horizontally.

REVERSE_Y = 'ReverseY'

Flip the image vertically.

SATURATION = 'Saturation'

Color Saturation

SENSOR_HEIGHT = 'SensorHeight'

Effective height of the sensor in pixels.

SENSOR_PIXEL_HEIGHT = 'SensorPixelHeight'

Physical size (pitch) in the y direction of a photo sensitive pixel unit.

SENSOR_PIXEL_WIDTH = 'SensorPixelWidth'

Physical size (pitch) in the x direction of a photo sensitive pixel unit.

SENSOR_WIDTH = 'SensorWidth'

Effective width of the sensor in pixels.

SHARPNESS = 'Sharpness'

Controls the strength of the sharpness algorithm.

SIDEBAND_USE = 'SidebandUse'

Enables Trigger/Strobe over USB-C Sideband Use Pins

SIGNAL_DETECTED = 'SignalDetected'

Indicates whether a signal is detected form the HDMI source.

SOFTWARE_TRANSFORM_ENABLE = 'SoftwareTransformEnable'

Enables Software Transform properties. If enabled, properties like Sharpness, Tone Mapping etc. can be enabled and lead to a software transformation in the driver.

SOURCE_CONNECTED = 'SourceConnected'

Indicates whether a HDMI source is connected.

STROBE_DELAY = 'StrobeDelay'

Configures the delay from start of exposure to the generated strobe pulse.

STROBE_DURATION = 'StrobeDuration'

If StrobeOperation is FixedDuration, specifies the pulse length.

STROBE_ENABLE = 'StrobeEnable'

Enable generation of exposure-synchronized output pulses

STROBE_OPERATION = 'StrobeOperation'

Configures the mode of specifying the length of exposure-synchronized output pulses

STROBE_POLARITY = 'StrobePolarity'

Select level of exposure-synchronized output pulses

TEST_EVENT_GENERATE = 'TestEventGenerate'

Generates a Test event that can be used for testing event notification.

TEST_PENDING_ACK = 'TestPendingAck'

Tests the device’s pending acknowledge feature.

TIMESTAMP_LATCH = 'TimestampLatch'

Latches the current timestamp counter into TimestampLatchValue.

TIMESTAMP_LATCH_STRING = 'TimestampLatchString'

Human-readable interpretation of the latched timestamp.

TIMESTAMP_LATCH_VALUE = 'TimestampLatchValue'

Returns the latched value of the timestamp counter. The timestamp must first be latched by using the Timestamp Control Latch command.

TIMESTAMP_RESET = 'TimestampReset'

Resets the current value of the device timestamp counter. After executing this command, the timestamp counter restarts automatically.

TL_PARAMS_LOCKED = 'TLParamsLocked'

Used by the Transport Layer to prevent critical features from changing during acquisition.

TONE_MAPPING_ENABLE = 'ToneMappingEnable'

Enables tone mapping.

TONE_MAPPING_GLOBAL_BRIGHTNESS = 'ToneMappingGlobalBrightness'

Changes the brightness reference used for a individual pixel, which is interpolated between local and global.

TONE_MAPPING_INTENSITY = 'ToneMappingIntensity'

Adjusts the intensity of the tonemapping algorithm.

TRIGGER_ACTIVATION = 'TriggerActivation'

Specifies the activation mode of the trigger

TRIGGER_DEBOUNCER = 'TriggerDebouncer'

Specifies the time for which trigger input has to be low in order accept the next trigger signal.

TRIGGER_DELAY = 'TriggerDelay'

Specifies the delay to apply after the trigger reception before activating it.

TRIGGER_DENOISE = 'TriggerDenoise'

Specifies the time for which trigger input has to be high in order to be accepted as a trigger signal.

TRIGGER_MASK = 'TriggerMask'

Specifies the time for which trigger pulses are ignored after accepting a trigger signal.

TRIGGER_MODE = 'TriggerMode'

Controls if the selected trigger is active.

TRIGGER_OPERATION = 'TriggerOperation'

Controls the operation mode of the sensor in trigger mode.

TRIGGER_OVERLAP = 'TriggerOverlap'

Specifies the type trigger overlap permitted with the previous frame. This defines when a valid trigger will be accepted for a new frame.

TRIGGER_SELECTOR = 'TriggerSelector'

Selects the type of trigger to configure.

TRIGGER_SOFTWARE = 'TriggerSoftware'

Generates an internal trigger. TriggerSource must be set to Software or Any.

TRIGGER_SOURCE = 'TriggerSource'

Specifies the internal signal or physical input Line to use as the trigger source.

USER_SET_DEFAULT = 'UserSetDefault'

Selects the feature User Set to load and make active by default when the device is reset.

USER_SET_LOAD = 'UserSetLoad'

Loads the User Set specified by UserSetSelector to the device and makes it active.

USER_SET_SAVE = 'UserSetSave'

Save the User Set specified by UserSetSelector to the non-volatile memory of the device.

USER_SET_SELECTOR = 'UserSetSelector'

Selects the feature User Set to load, save or configure.

WIDTH = 'Width'

Width of the image provided by the device (in pixels).

WIDTH_MAX = 'WidthMax'

Maximum width of the image (in pixels). The dimension is calculated after horizontal binning, decimation or any other function changing the horizontal dimension of the image.

ZOOM = 'Zoom'

Changes the zoom setting of the lens.

class PropertyType(value)

Bases: IntEnum

Enum describing available property types.

INVALID = 0

Not a valid property type, indicates an error.

INTEGER = 1

Integer property.

FLOAT = 2

Float property.

ENUMERATION = 3

Enumeration property.

BOOLEAN = 4

Boolean property.

STRING = 5

String property.

COMMAND = 6

Command property.

CATEGORY = 7

Category property.

REGISTER = 8

Register property.

PORT = 9

Port property.

ENUMENTRY = 10

Enumeration entry property.

class PropertyVisibility(value)

Bases: IntEnum

Enum describing possible property visibilities.

BEGINNER = 0

Beginner visibility.

EXPERT = 1

Expoert visibility.

GURU = 2

Guru visibility.

INVISIBLE = 3

Should not be displayed per default.

class PropertyIncrementMode(value)

Bases: IntEnum

An enumeration.

INCREMENT = 0

The property used a fixed step between valid values.

Use PropInteger.increment or PropFloat.increment to get the property’s step size.

VALUE_SET = 1

The property defines a set of valid values.

Use PropInteger.valid_value_set or PropFloat.valid_value_set to query the set of valid values.

NONE = 2

The property allows setting all values between its minimum and maximum value.

This mode is only valid for float properties.

Integer properties report increment 1 if they allow every possible value between their minimum and maximum value.

class Property(h: c_void_p)

Bases: object

Base class for IC4 properties.

Implements basic functionality that is common for all properties.

property type: PropertyType

Get property type.

Returns:

Enum entry describing what the property actually is.

Return type:

PropertyType

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property visibility: PropertyVisibility

Get the recommended visibility of the property.

Returns:

PropertyVisibility

property name: str

Get the name of the property.

Returns:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property description: str

Get the description of the property.

Returns:

Description string of the property.

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property tooltip: str

Get the tooltip of the property.

Returns:

Tooltip string of the property.

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property display_name: str

Get human readable display name.

Returns:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property is_locked: bool

Check whether a property is currently locked.

A locked property can be read, but attempts to write its value will fail. A property’s locked status may change upon writing to another property. Common examples for locked properties are ExposureTime or Gain if ExposureAuto or GainAuto are enabled.

Returns:

True if locked

Return type:

bool

property is_likely_locked_by_stream: bool

Tries to determine whether a property is locked because a data stream is active.

For technical reasons, this function cannot always accurately predict the future.

Returns:

true, if the property is currently locked, and will likely be unlocked if the data stream is stopped. false, if the property is not currently locked, or stopping the data stream will probably not lead to the property being unlocked.

Return type:

bool

property is_readonly: bool

Check whether a property is read-only.

A read-only property will never be writable, the read-only status will never change. A common examples for read-only property is DeviceTemperature.

Returns:

True if read-only

Return type:

bool

property is_available: bool

Check whether a property is currently available.

If a property is not available, attempts to read or write its value will fail. A property may become unavailable, if its value does not have a meaning in the current state of the device. The property’s availability status can change upon writing to another property.

Returns:

True if available

Return type:

bool

property is_selector: bool

Check whether this property’s value changes the meaning and/or value of other properties.

Use selected_properties to retrieve properties that will be affected by changes to this property.

Returns:

True if other values will be changed.

Return type:

bool

property selected_properties: Sequence[Property]

Get properties that are affected by this property.

Returns:

Sequence will be emtpy if property is not a selector.

Return type:

Sequence[“Property”]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class NotificationToken(func: Callable[[c_void_p, c_void_p], None], deleter: Callable[[c_void_p], None])

Bases: object

Represents a registered notification callback.

When a property notification function is registered using event_add_notification(), a token is returned.

The token can then be used to remove the callback using event_remove_notification() at a later time.

event_add_notification(notification: Callable[[Property], None]) → NotificationToken

Register a “property changed” callback.

Function will be called when any aspect of the property changes.

Parameters:

notification (Callable[[Property], None]) – Function that shall be called.

Returns:

A token that can be used to unregister the callback using event_remove_notification().

Return type:

NotificationToken

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_remove_notification(token: NotificationToken)

Unregister a property-changed handler that was previously registered using event_add_notification().

Parameters:

token (NotificationToken) – Identification token for callback.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropCommand(h: c_void_p)

Bases: Property

Command properties represent an action that can be performed by the device.

execute()

Execute the property.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property is_done: bool

Checks whether a command has finished executing.

If the command was never executed before, the value is True.

Returns:

True, if the command is completed. False, if the command is still executing.

Return type:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropBoolean(h: c_void_p)

Bases: Property

Boolean properties represent a feature whose value is a simple on/off switch.

property value: bool

The current property value.

Returns:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropIntRepresentation(value)

Bases: IntEnum

Enum describing the different ways an integer property can be represented.

LINEAR = 0

Suggest a slider to edit the value.

LOGARITHMIC = 1

Suggest a slider with logarithmic mapping.

BOOLEAN = 2

Suggest a checkbox.

PURENUMBER = 3

Suggest displaying a decimal number.

HEXNUMBER = 4

Suggest displaying a hexadecimal number.

IPV4ADDRESS = 5

Suggest treating the integer as a IPV4 address.

MACADDRESS = 6

Suggest treating the integer as a MAC address.

class PropInteger(h: c_void_p)

Bases: Property

Integer properties represent a feature whose value is an integer number.

Common examples for a integer properties are Width or Height.

An integer property can limit the range of valid values. The range of possible values can be queried by reading minimum and maximum.

The possible values can be further restricted by an increment value or a set of value values. Check increment_mode, increment and valid_value_set for details.

In integer property supplies hints that can be useful when creating a user interface:

property value: int

Get the current property value.

Returns:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property minimum: int

Get the minimal property value.

Returns:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property maximum: int

Get the maximum property value.

Returns:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property increment_mode: PropertyIncrementMode

Returns the property’s increment mode.

An integer property has 1 of 2 possible increment modes:

Incrment Mode

Behavior

PropertyIncrementMode.INCREMENT

Only multiples of increment can be set.

PropertyIncrementMode.VALUE_SET

Only values that are part of value_value_set can be set
Return type:

PropertyIncrementMode

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property increment: int

Get the increment step.

Only valid if increment_mode is INCREMENT.

Returns:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property unit: str

The unit of this integer property

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property representation: PropIntRepresentation

The suggested representation for this integer property

Return type:

PropIntRepresentation

property valid_value_set: Sequence[int]

Returns the set of valid values for this property.

Only valid if increment_mode is VALUE_SET.

Returns:

The set of valid values for this property

Return type:

Sequence[int]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropFloatRepresentation(value)

Bases: IntEnum

Defines the possible float property representations.

Each float property has a representation hint that can help creating more useful user interfaces.

LINEAR = 0

Suggest a slider with linear mapping to edit the value.

LOGARITHMIC = 1

Suggest a slider with logarithmic mapping to edit the value.

PURENUMBER = 2

Suggest displaying a number to edit.

class PropDisplayNotation(value)

Bases: IntEnum

Defines the possible float property display notations.

AUTOMATIC = 0

Use an automatic mechanism to determine the best display notation.

FIXED = 1

Suggest fixed point notation.

SCIENTIFIC = 2

Suggest scientific notation.

class PropFloat(h: c_void_p)

Bases: Property

Float properties represent a feature whose value is a floating-point number.

Common examples for a float properties are AcquisitionFrameRate, ExposureTime or Gain.

A float property can limit the range of valid values. The range of possible values can be queried by reading minimum and maximum.

The possible values can be further restricted by an increment value or a set of value values. Check increment_mode, increment and valid_value_set for details.

I float property supplies hints that can be useful when creating a user interface:

property representation: PropFloatRepresentation

The suggested representation for this float property

Return type:

PropFloatRepresentation

property unit: str

The unit of this float property

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property display_notation: PropDisplayNotation

A suggested display notation to use when displaying the float property’s value

Return type:

PropDisplayNotation

property display_precision: int

A suggested number of significant digits to use when displaying the float property’s value

Return type:

int

property value: float

The current value of this property

The value is only writable is the property’s writability is not restricted. See is_locked, is_readonly, is_available.

Return type:

float

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property minimum: float

The minimum value accepted by this property.

Return type:

float

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property maximum: float

The maximum value accepted by this property.

Return type:

float

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property increment_mode: PropertyIncrementMode

Indicates how this float property restricts which values are valid between its minimum and maximum value.

A float property has 1 of 3 possible increment modes:

Incrment Mode

Behavior

PropertyIncrementMode.NONE

The property has no restrictions, all values between minimum and maximum can be set.

PropertyIncrementMode.INCREMENT

Only multiples of increment can be set.

PropertyIncrementMode.VALUE_SET

Only values that are part of value_value_set can be set
Return type:

PropertyIncrementMode

property increment: float

The step size for valid values accepted by this float property

The increment restricts the set of valid values for a float property. For example, if the property’s minimum value is 0, the maximum is10, and the increment is 0.5, 0.25 is not a valid value for the property.

Accessing will throw an exception if increment_mode is not equal to PropertyIncrementMode.INCREMENT.

Return type:

float

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property valid_value_set: Sequence[int]

Returns the set of valid values for this property.

Only valid if increment_mode is PropertyIncrementMode.VALUE_SET.

Returns:

The set of valid values for this property

Return type:

Sequence[float]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropEnumEntry(h: c_void_p)

Bases: Property

Represents an entry in a PropEnumeration.

Enumeration entries are derived from Property, since they also have most property aspects like a name, display name, tooltip, visibility and accessibility flags.

In addition to those common attributes, they have a constant value that can be queried using value.

property value: int

The value of the enumeration entry

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropEnumeration(h: c_void_p)

Bases: Property

Enumeration properties represent a feature whose value is selected from a list of named entries.

Common examples for an enumeration properties are PixelFormat, TriggerMode or ExposureAuto. The value of an enumeration property can be get or set by both a enumeration entry’s name or value. Enumeration entries are represented by PropEnumEntry objects.

property entries: Sequence[PropEnumEntry]

Get all enum entries.

Returns:

_description_

Return type:

Sequence[PropEnumEntry]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_entry(name_or_value: str | int) → PropEnumEntry

Find entry via name or value.

Raises IC4Exception if name or value do not exists.

Returns:

Instance representing the enum entry.

Return type:

PropEnumEntry

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property selected_entry: PropEnumEntry

Get the currently active enum entry.

Returns:

Currently selected enum entry.

Return type:

PropEnumEntry

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property value: str

Get the name of the currently active enum entry.

Returns:

Name of the currently selected enum entry.

Return type:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property int_value: int

Get the integer value of the currently active enum entry.

Returns:

Integer value of the currently selected enum entry.

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropString(h: c_void_p)

Bases: Property

String properties represent features whose value is a text.

The maximum length of the text is indicated by max_length.

property value: str

The current value.

Returns:

str

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property max_length: int

The maximum length of the string that can be stored in this property

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropRegister(h: c_void_p)

Bases: Property

Register properties have a value represented by raw bytes.

property size: int

The size of a register property.

The size of a register property is not necessarily constant; it can change depending on the value of other properties.

property value: bytearray

The current value of the register

The value is only writable is the property’s writability is not restricted. See is_locked, is_readonly, is_available.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropCategory(h: c_void_p)

Bases: Property

Category properties define a tree-relationship between all properties in a property map.

The root of the tree is always the category property with the name Root.

To find which properties are linked from a category, use features.

Categories can contain other categories recursively. A very simple category tree might look like this:

  • Root (category)
    • AcquisitionControl (category)

      • AcquisitionStart (command)

      • AcquisitionStop (command)

      • AcquisitionFrameRate (float)

    • ImageFormatControl (category)

      • Width (integer)

      • Height (integer)

property features: Sequence[Property]

Get contained properties.

Returns:

Collection of Property the category contains.

Return type:

Sequence[Property]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PropertyMap(h: c_void_p)

Bases: object

Represents the property interface of a component, usually a video capture device.

A property map offers quick access to known properties as well as functions to enumerate all features through the category tree.

There is a plethora of overloaded functions to access properties with a known name and type:

To find a property with a known name, but unknown type, use the untyped functions find().

Property values for known properties can also be set directly by calling set_value(). The function accepts int, float, bool or str arguments, and tries to set the value in a way matching the type of the property being manipulated.

Additionally, property values for known properties can be queried directly by calling

To get a flat list of all properties in the property map’s category tree, use all().

The current values of all properties in a property map can be saved to a file or a memory buffer using serialize(). To restore the settings at a later time, call deserialize(). The property values can also be directly written to and read from a file using serialize_to_file() or deserialize_from_file() respectively.

An image buffer containing chunk data can be connected to a property map using connect_chunkdata(). Doing so lets the property map uses the image buffer as the data source for chunk property read operations.

PropertyMap instances are created by their respective component when queried, for example by calling Grabber.device_property_map() or VideoWriter.property_map().

execute_command(command_name: str) → None

Executes a command with a known name.

Parameters:

command_name (str) – Name of a command property in this property map

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

try_set_value(property_name: str, value: int | float | bool | str) → bool

Tries to set the value of a property with a known name to the passed value.

In contrast to set_value(), this method does not raise an exception in case the property does not exist, or could not be set. Please note that a TypeError exception is still raised when the value argument has an unexpected type.

Parameters:

  • property_name (str) – Name of a property in this property map

  • value (Union[int, float, bool, str]) – New value to be set

Raises:

TypeError – value is neither int, float, bool nor str.

Returns:

True if the value was set successfully, False if the value could not be set.

Return type:

bool

Note

The behavior of this function depends on both the type of the property and the type of the passed value argument:

  • If the argument type is int:

    • For integer properties, the passed value is set directly.

    • For float properties, the passed value is set directly.

    • For boolean properties, if the value is 1 or 0, it is set to True or False respectively. Other values result in an error.

    • For enumeration properties, the value is set if the property is PixelFormat.

    • For command properties, the command is executed if the passed value is 1.

    • For all other property types, the call results in an error.

  • If the argument type is float:

    • For integer properties, the passed value is rounded to the nearest integer.

    • For float properties, the passed value is set directly.

    • For all other property types, the call results in an error.

  • If the argument type is bool:

    • For boolean properties, the passed value is set directly.

    • For enumeration properties, it selects the entry with a name that unambiguously suggests to represent True or False, if available.

    • For command properties, the command is executed if the passed value is True.

    • For all other property types, the call results in an error.

  • If the argument type is str:

    • For integer properties, the string is parsed, and the found integer value is set.

    • For float properties, the string is parsed, and the found floating-point value is set.

    • For boolean properties, a value is set if the string can be unambiguously identified to represent True or False.

    • For enumeration properties, the entry with a naming matching the value is selected.

    • For string properties, the value is set directly.

    • For command properties, the command is executed if the passed value is “1”, “True” or “execute”.

    • For all other property types, the call results in an error.

set_value(property_name: str, value: int | float | bool | str) → None

Set the value of a property with a known name to the passed value.

Parameters:

  • property_name (str) – Name of a property in this property map

  • value (Union[int, float, bool, str]) – New value to be set

Raises:

Note

The behavior of this function depends on both the type of the property and the type of the passed value argument:

  • If the argument type is int:

    • For integer properties, the passed value is set directly.

    • For float properties, the passed value is set directly.

    • For boolean properties, if the value is 1 or 0, it is set to True or False respectively. Other values result in an error.

    • For enumeration properties, the value is set if the property is PixelFormat.

    • For command properties, the command is executed if the passed value is 1.

    • For all other property types, the call results in an error.

  • If the argument type is float:

    • For integer properties, the passed value is rounded to the nearest integer.

    • For float properties, the passed value is set directly.

    • For all other property types, the call results in an error.

  • If the argument type is bool:

    • For boolean properties, the passed value is set directly.

    • For enumeration properties, it selects the entry with a name that unambiguously suggests to represent True or False, if available.

    • For command properties, the command is executed if the passed value is True.

    • For all other property types, the call results in an error.

  • If the argument type is str:

    • For integer properties, the string is parsed, and the found integer value is set.

    • For float properties, the string is parsed, and the found floating-point value is set.

    • For boolean properties, a value is set if the string can be unambiguously identified to represent True or False.

    • For enumeration properties, the entry with a naming matching the value is selected.

    • For string properties, the value is set directly.

    • For command properties, the command is executed if the passed value is “1”, “True” or “execute”.

    • For all other property types, the call results in an error.

Remarks:

When setting properties that are not necessarily required for program operation, use try_set_value() to not raise an exception in case of a property error.

get_value_int(property_name: str) → int

Get the value of a property with a known name interpreted as an int.

Parameters:

property_name (str) – Name of a property in in this property map

Returns:

If successful, the value of the property is returned.

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

The behavior of this function depends on the type of the property:

  • For integer properties, the value is returned directly.

  • For boolean properties, the value returned is 1 or 0.

  • For all other property types, the call results in an error.

get_value_float(property_name: str) → float

Get the value of a property with a known name interpreted as a float.

Parameters:

property_name (str) – Name of a property in in this property map

Returns:

If successful, the value of the property is returned.

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

The behavior of this function depends on the type of the property:

  • For integer properties, the value is converted to float.

  • For float properties, the value is returned directly.

  • For all other property types, the call results in an error.

get_value_bool(property_name: str) → bool

Get the value of a property with a known name interpreted as a bool.

Parameters:

property_name (str) – Name of a property in in this property map

Returns:

If successful, the value of the property is returned.

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

The behavior of this function depends on the type of the property:

  • For boolean properties, the value is returned directly.

  • For enumeration properties, a value is returned if the name of the currently selected entry unambiguously suggests to represent @c true or @c false.

  • For all other property types, the call results in an error.

get_value_str(property_name: str) → str

Get the value of a property with a known name interpreted as a str.

Parameters:

property_name (str) – Name of a property in in this property map

Returns:

If successful, a string representation of the value of the property is returned.

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

The behavior of this function depends on the type of the property:

  • For integer properties, the value is converted to a string.

  • For float properties, the value is converted to a string.

  • For boolean properties, the value is converted to the string True or False.

  • For enumeration properties, the name of the currently selected entry is returned.

  • For string properties, the value is returned directly.

  • For all other property types, the call results in an error.

find(prop_name: str) → Property

Finds the property with a specified name in the property map.

Parameters:

prop_name (str) – The name of the property to find

Returns:

The requested property object

Return type:

Property

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_integer(integer_name: str) → PropInteger

Finds the integer property with a specified name in the property map.

Parameters:

integer_name (str) – The name of the integer property to find

Returns:

The requested integer property object

Return type:

PropInteger

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_float(float_name: str) → PropFloat

Finds the float property with a specified name in the property map.

Parameters:

integer_name (str) – The name of the float property to find

Returns:

The requested float property object

Return type:

PropFloat

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_command(command_name: str) → PropCommand

Finds the command property with a specified name in the property map.

Parameters:

command_name (str) – The name of the command property to find

Returns:

The requested command property object

Return type:

PropCommand

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_boolean(boolean_name: str) → PropBoolean

Finds the boolean property with a specified name in the property map.

Parameters:

boolean_name (str) – The name of the boolean property to find

Returns:

The requested boolean property object

Return type:

PropBoolean

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_enumeration(enumeration_name: str) → PropEnumeration

Finds the enumeration property with a specified name in the property map.

Parameters:

enumeration_name (str) – The name of the enumeration property to find

Returns:

The requested enumeration property object

Return type:

PropEnumeration

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_string(string_name: str) → PropString

Finds the string property with a specified name in the property map.

Parameters:

string_name (str) – The name of the string property to find

Returns:

The requested string property object

Return type:

PropString

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_register(register_name: str) → PropRegister

Finds the register property with a specified name in the property map.

Parameters:

register_name (str) – The name of the register property to find

Returns:

The requested register property object

Return type:

PropRegister

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

find_category(category_name: str) → PropCategory

Finds the category property with a specified name in the property map.

Parameters:

category_name (str) – The name of the category property to find

Returns:

The requested category property object

Return type:

PropCategory

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property all: Sequence[Property]

Get all properties.

Does not include PropCategory properties.

Returns:

Collection of all properties.

Return type:

Sequence[Property]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property root_category: PropCategory

Gets the Root category.

Returns:

The Root category of this property map

Return type:

PropCategory

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

serialize() → bytearray

Saves the state of the properties in this property map in a memory buffer.

Returns:

A bytearray containing the serialized property values

Return type:

bytearray

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

Use deserialize() to restore the property values at a later time.

deserialize(arr: bytearray) → None

Restores the state of the properties in this property map from a memory buffer containing data that was previously written by serialize().

Parameters:

arr (bytearray) – A bytearray containing the serialized property data

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

serialize_to_file(path: Path | str) → None

Write properties to JSON file.

Parameters:

path (Path|str) – File path where file shall be written.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

deserialize_from_file(path: Path | str) → None

Read properties from JSON file.

Parameters:

path (Path|str) – File path that shall be read.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

connect_chunkdata(image_buffer: ImageBuffer | None) → None

Enables the use of the chunk data in the passed ImageBuffer as a backend for chunk properties in the property map.

Parameters:

image_buffer (Optional[ImageBuffer]) – An image buffer with chunk data. This parameter may be None to disconnect the previously connected buffer.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

The property map takes a reference to the passed image buffer, extending its lifetime and preventing automatic reuse. The reference is released when a new image buffer is connected to the property map, or None is passed in the image_buffer argument.

Image Buffers

class BufferPool(cache_buffers_max: int = 1, cache_bytes_max: int = 0)

Bases: object

The buffer pool allows allocating additional buffers for use by the program.

Most programs will only use buffers provided by one of the sink types. However, some programs require additional buffers, for example to use as destination for image processing.

To create additional buffers, first create a buffer pool. Then, use BufferPool.get_buffer() to request a new buffer with a specified image type.

When an image buffer is no longer required, call ImageBuffer.release() on it, or let it go out of scope. The image buffer will then be returned to the buffer pool.

The buffer pool has configurable caching behavior. By default, the buffer pool will cache one image buffer and return it the next time a matching image buffer is requested.

Image buffers objects created by the buffer pool are still valid after the buffer pool itself has been disposed.

Parameters:

  • cache_buffers_max (int) – Maximum number of frames to keep in the buffer pool’s cache

  • cache_bytes_max (int) – Maximum size of the buffer pool cache in bytes, or 0 to not limit by size

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

get_buffer(image_type: ImageType, alignment: int = 0, pitch: int = 0, buffer_size: int = 0) → ImageBuffer

Requests a buffer from the buffer pool.

The buffer is either newly allocated, or retrieved from the buffer pool’s buffer cache.

Parameters:

  • image_type (ImageType) – Image type of the requested buffer.

  • alignment (int, optional) – Specifies the alignment of the address of the buffer’s memory. Setting this to 0 lets the buffer pool select an alignment automatically. The alignment must be a power of 2. Defaults to 0.

  • pitch (int, optional) – Specifies the pitch to use when allocating the buffer. A value of 0 lets the buffer pool select a pitch automatically. Setting a pitch that is smaller than the amount of memory required to store one line of image data will lead to an error. Defaults to 0.

  • buffer_size (int, optional) – Overrides the automatic buffer size calculation. A value of 0 lets the buffer pool calculate the required buffer size automatically. Setting a size that is smaller than the amount of memory required to store an image of a known format will lead to an error. Defaults to 0.

Returns:

The new image buffer

Return type:

ImageBuffer

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class ImageBuffer(h: c_void_p)

Bases: object

Class representing an image buffer accessible by the program.

Image buffers are created by a sink (SnapSink or QueueSink) or obtained from a BufferPool.

When all references to an ImageBuffer are deleted, or release() is called, the image buffer is returned to its source for possible reuse.

release() → None

Returns the image buffer represented by this object to its source for reuse.

This function can be useful when working with a list of image buffers returned from SnapSink.snap_sequence(), allowing specific image buffers to be requeued before the complete list is destroyed.

class MetaData(device_frame_number: int, device_timestamp_ns: int)

Bases: object

Class containing meta information for the associated ImageBuffer.

To query the frame metadata of an ImageBuffer, use the ImageBuffer.meta_data() property.

device_frame_number: int

Device frame number

Returns:

The frame number assigned to the image by the video capture device.

Return type:

int

Note

The behavior of this value, including starting value and possible rollover is device-specific.

device_timestamp_ns: int

Device timestamp

Returns:

The time stamp assigned to the image by the video capture device.

Return type:

int

Note

The behavior of this value, including possible resets, its starting value or actual resolution is device-specific.

property meta_data: MetaData

Get MetaData object associated with this image buffer.

Returns:

Metadata for this buffer

Return type:

MetaData

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property pointer: c_void_p

Return the pointer to this image buffer’s data.

The memory pointed to by the returned pointer is valid as long as the image buffer object exists.

Returns:

The pointer to the image data

Return type:

ctypes.c_void_p

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property buffer_size: int

Get the size of the image buffer.

Returns:

The size of the image buffer in bytes

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property pitch: int

Get the pitch of the image buffer.

The pitch is the distance between the starting memory location of two consecutive lines.

Returns:

The pitch of the image buffer in bytes

Return type:

int

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property image_type: ImageType

Get the image type of the image buffer.

Returns:

Describes the pixel format and dimensions of the image in this buffer.

Return type:

ImageType

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

copy_from(source: ImageBuffer, skip_image: bool = False, skip_chunkdata: bool = False) → None

Copies the contents of one image buffer to another image buffer.

Parameters:

  • source (ImageBuffer) – Source buffer to copy from

  • skip_image (bool, optional) – If set, only copies the non-image parts of the buffer. Defaults to False.

  • skip_chunkdata (bool, optional) – If set, the chunk data is not copied. Defaults to False.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Remarks:

If the pixel format of the images in source and self is not equal, the image is converted. For example, if the pixel format of source is PixelFormat.BayerRG8 and the pixel format of self is PixelFormat.BGR8, a demosaicing operation creates a color image.

If skip_image is setthe function does not copy the image data. The function then only copies the meta data and chunk data, and a program-defined algorithm can handle the image copy operation.

If skip_chunkdata is set, the function does not copy the chunk data contained in source. This can be useful if the chunk data is large and not required.

Note

If the width or height of source and self are not equal, the function fails and the error value is set to ErrorCode.ConversionNotSupported.

If there is no algorithm available for the requested conversion, the function fails and the error value is set to ErrorCode.ConversionNotSupported.

If self is not writable (is_writable), the function fails and the error value is set to ErrorCode.InvalidOperation.

property is_writable: bool

Checks whether an image buffer object is (safely) writable.

In some situations, image buffer objects are shared between the application holding a handle to the image buffer object and the library. For example, the image buffer might be shared with a display or a video writer.

A shared buffer is not safely writable. Writing to a buffer that is shared can lead to unexpected behavior, for example a modification may partially appear in the result of an operation that is happening in parallel.

Passing the image buffer into a function such as Display.display_buffer() or or VideoWriter.add_frame() can lead to a buffer becoming shared.

Returns:

True, if the image buffer not shared with any part of the library, and is therefore safely writable, otherwise False.

Return type:

bool

numpy_wrap() → ndarray[Any, dtype[Any]]

Create a numpy array using the contents of this image buffer.

The numpy array can only be accessed while references to the image buffer exist. Trying to access the numpy array after the final reference to the image buffer can lead to unexpected behavior.

The element type and shape of the NDArray depend on the pixel format of the image buffer:

Pixel Format

Element Type

Shape

Mono8, BayerBG8, BayerRG8, BayerRG8, BayerGR8

c_ubyte

(Height, Width, 1)

Mono16, BayerBG16, BayerRG16, BayerRG16, BayerGR16

c_ushort

(Height, Width, 1)

BGR8

c_ubyte

(Height, Width, 3)

BGRa8

c_ubyte

(Height, Width, 4)

BGRa16

c_ushort

(Height, Width, 4)
Returns:

A numpy array using the contents of this image buffer.

Return type:

NDArray[Any]

Raises:

RuntimeError – The pixel format of the image buffer is not supported.

numpy_copy() → ndarray[Any, dtype[Any]]

Create a numpy array containing a copy of the contents of this image buffer.

Returns:

A new numpy array containing the contents of this image buffer.

Return type:

NDArray[Any]

Raises:

RuntimeError – The pixel format of the image buffer is not supported.

class PngCompressionLevel(value)

Bases: IntEnum

Defines the possible PNG compression levels passed to ImageBuffer.save_as_png().

Higher compression levels can generate smaller files, but the compression can take more time.

AUTO = 0

Automatically select a compression level

LOW = 1

Low compression

MEDIUM = 2

Medium compression

HIGH = 3

High compression

HIGHEST = 4

Highest compression

save_as_bmp(path: Path | str, store_bayer_raw_data_as_monochrome: bool = False) → None

Save ImageBuffer contents as a bmp file.

Depending on the pixel format of the image buffer, a transformation is applied before saving the image.

  • Monochrome pixel formats are converted to Mono8 and stored as a 8-bit monochrome bitmap file

  • Bayer, RGB and YUV pixel formats are converted to BGR8 and stored as a 24-bit color bitmap file

Parameters:

  • path (Path|str) – Filename that shall be used. Directory must exist.

  • store_bayer_raw_data_as_monochrome (bool) – optional, If the image buffer’s pixel format is a bayer format, interpret the pixel data as monochrome and store the raw data as a monochrome image. (Default: False)

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

save_as_jpeg(path: Path | str, quality_pct: int = 75) → None

Save ImageBuffer contents as a jpeg file.

Depending on the pixel format of the image buffer, a transformation is applied before saving the image.

  • Monochrome pixel formats are converted to Mono8 and stored as a monochrome jpeg file

  • Bayer, RGB and YUV pixel formats are converted to BGR8 stored as a color jpeg file

Parameters:

  • path (Path|str) – Filename that shall be used. Directory must exist.

  • quality_pct (int) – optional, jpeg image quality in percent. (Default: 75)

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

save_as_png(path: Path | str, store_bayer_raw_data_as_monochrome: bool = False, compression_level: PngCompressionLevel = PngCompressionLevel.AUTO) → None

Save ImageBuffer contents as a png file.

Depending on the pixel format of the image buffer, a transformation is applied before saving the image.

  • Monochrome pixel formats with a bit depth higher than 8bpp are converted to Mono16 and stored as a monochrome PNG file with 16 bits per channel

  • Mono8 image buffers are stored as a monochrome PNG file with 8 bits per channel

  • Bayer format with a bit depth higher than 8bpp are converted to BGRa16 and stored as a 4-channel PNG with 16 bits per channel

  • 16-bit RGB pixel formats are stored as a 4-channel PNG with 16 bits per channel

  • 8-bit Bayer, RGB and YUV pixel formats are converted to BGR8 stored as a 3-channel PNG file with 8 bits per channel

Parameters:

  • path (Path|str) – Filename that shall be used. Directory must exist.

  • store_bayer_raw_data_as_monochrome (bool) – optional, If the image buffer’s pixel format is a bayer format, interpret the pixel data as monochrome and store the raw data as a monochrome image. (Default: False)

  • compression_level (PngCompressionLevel) – optional, Amount png compression will be applied. (Default: AUTO)

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

save_as_tiff(path: Path | str, store_bayer_raw_data_as_monochrome: bool = False) → None

Save ImageBuffer contents as tiff file.

Depending on the pixel format of the image buffer, a transformation is applied before saving the image.

  • Monochrome pixel formats with a bit depth higher than 8bpp are converted to Mono16 and stored as a monochrome Tiff file with 16 bits per channel

  • Mono8 image buffers are stored as a monochrome Tiff file with 8 bits per channel

  • Bayer format with a bit depth higher than 8bpp are converted to BGRa16 and stored as a 4-channel Tiff with 16 bits per channel

  • 16-bit RGB pixel formats are stored as a 4-channel Tiff with 16 bits per channel

  • 8-bit Bayer, RGB and YUV pixel formats are converted to BGR8 stored as a 3-channel Tiff file with 8 bits per channel

Parameters:

  • path (Path|str) – Filename that shall be used. Directory must exist.

  • store_bayer_raw_data_as_monochrome (bool) – optional, If the image buffer’s pixel format is a bayer format, interpret the pixel data as monochrome and store the raw data as a monochrome image. (Default: False)

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class PixelFormat(value)

Bases: IntEnum

Defines the possible representations of pixels in an image.

The pixel format is part of the ImageType.

Unspecified = 0

Unspecified pixel format, used to partially define a image type.

Mono8 = 17301505

Monochrome 8-bit

Mono10p = 17432646

Monochrome 10-bit packed

Mono12p = 17563719

Monochrome 12-bit packed

Mono16 = 17825799

Monochrome 16-bit

BayerBG8 = 17301515

Bayer Blue-Green 8-bit

BayerBG10p = 17432658

Bayer Blue-Green 10-bit packed

BayerBG12p = 17563731

Bayer Blue-Green 12-bit packed

BayerBG16 = 17825841

Bayer Blue-Green 16-bit

BayerGB8 = 17301514

Bayer Green-Blue 8-bit

BayerGB10p = 17432660

Bayer Green-Blue 10-bit packed

BayerGB12p = 17563733

Bayer Green-Blue 12-bit packed

BayerGB16 = 17825840

Bayer Green-Blue 16-bit

BayerGR8 = 17301512

Bayer Green-Red 8-bit

BayerGR10p = 17432662

Bayer Green-Red 10-bit packed

BayerGR12p = 17563735

Bayer Green-Red 12-bit packed

BayerGR16 = 17825838

Bayer Green-Red 16-bit

BayerRG8 = 17301513

Bayer Red-Green 8-bit

BayerRG10p = 17432664

Bayer Red-Green 10-bit packed

BayerRG12p = 17563737

Bayer Red-Green 12-bit packed

BayerRG16 = 17825839

Bayer Red-Green 16-bit

BGRa8 = 35651607

Blue-Green-Red-alpha 8-bit

BGRa16 = 37748817

Blue-Green-Red-alpha 16-bit

BGR8 = 35127317

Blue-Green-Red 8-bit

Mono12Packed = 17563654

GigE Vision specific format, Monochrome 12-bit packed

BayerBG12Packed = 17563693

GigE Vision specific format, Bayer Blue-Green 12-bit packed

BayerGB12Packed = 17563692

GigE Vision specific format, Bayer Green-Blue 12-bit packed

BayerGR12Packed = 17563690

GigE Vision specific format, Bayer Green-Red 12-bit packed

BayerRG12Packed = 17563691

GigE Vision specific format, Bayer Red-Green 12-bit packed

YUV422_8 = 34603058

2 8-bit

Type:

YUV 4

Type:

2

YCbCr422_8 = 34603067

2 8-bit

Type:

YCbCr 4

Type:

2

YCbCr411_8 = 34340954

1 8-bit (CbYYCrYY)

Type:

YCbCr 4

Type:

1

YCbCr411_8_CbYYCrYY = 34340924

1 8-bit (YYCbYYCr)

Type:

YCbCr 4

Type:

1

Invalid = -1

Invalid pixel format

class ImageType(pixel_format: PixelFormat | int = PixelFormat.Unspecified, width: int = 0, height: int = 0)

Bases: object

Represents an image type, including pixel format and image dimensions.

property pixel_format: PixelFormat | int

The pixel format of the image

Returns:

The pixel format of an image. This may be of type int, if the actual pixel format is not a member of the PixelFormat enumeration.

Return type:

Union[PixelFormat, int]

property width: int

The width of the image

Returns:

The width of the image

Return type:

int

property height: int

The height of the image

Returns:

The height of the image

Return type:

int

Sinks

class QueueSinkListener

Bases: ABC

Abstract base class for QueueSink listener.

abstract sink_connected(sink: QueueSink, image_type: ImageType, min_buffers_required: int) → bool

Called when the data stream to the sink is created.

Parameters:

  • sink (QueueSink) – The sink that is being connected

  • image_type (ImageType) – The image type the sink is going to receive

  • min_buffers_required (int) – Indicates the minimum number of buffers required for the data stream to operate. If the event handler does not allocate any buffers, the sink will automatically allocate the minimum number of buffers required.

Returns:

True to proceed, False to abort the creation of the data stream.

Note

The function is executed on the thread that calls Grabber.stream_setup().

sink_disconnected(sink: QueueSink)

Called when the data stream to the sink is stopped.

Parameters:

sink (QueueSink) – The sink that is being disconnected

Note

The function is executed on the thread that calls Grabber.stream_stop().

abstract frames_queued(sink: QueueSink)

Called when new images were added to the sink’s queue of filled buffers.

The event handler usually calls QueueSink.pop_output_buffer() to get access to the filled image buffers.

If the callback function performs a lengthy operation, it is recommended to regularly check QueueSink.is_cancel_requested to determine whether the data stream is being stopped.

Parameters:

sink (QueueSink) – The sink that received a frame

Note

The function is executed on dedicated thread managed by the sink.

When the data stream to the sink is stopped, the Grabber.stream_stop() call will wait until this event handler returns. This can quickly lead to a deadlock, if code in the event handler performs an operation that unconditionally requires activity on the thread that called Grabber.stream_stop().

class QueueSink(listener: QueueSinkListener, accepted_pixel_formats: List[PixelFormat] = [], max_output_buffers: int = 0)

Bases: Sink

A sink implementation that allows a program to process all images received from a video capture device

A queue sink manages a number of buffers that are organized in two queues:

  • A free queue that buffers are pulled from to fill with data from the device

  • An output queue that contains the filled buffers ready to be picked up by the program

Pass the sink to Grabber.stream_setup() to feed images into the sink.

The sink is interacted with by implementing the abstract methods in the QueueSinkListener passed to the queue sink during creation. The methods are called at different significant points in the lifetime of a queue sink:

To retrieve the oldest available image from the output queue, call QueueSink.pop_output_buffer(). The returned image buffer is owned by the program. If the program no longer needs the image buffer, the image buffer object must be deleted, or ImageBuffer.release() must be called it to return the image buffer to the sink’s free queue.

A program does not necessarily have to requeue all image buffers immediately; it can choose keep references to a number of them in its own data structures. However, please note that if there are no buffers in the free queue when the device tries to deliver a frame, the frame will be dropped. Use Grabber.stream_statistics to find out whether a buffer underrun occurred.

Parameters:

  • listener (QueueSinkListener) – An object implementing the QueueSinkListener abstract base class controlling the sink’s behavior.

  • accepted_pixel_formats (List[PixelFormat]) – An optional list of pixel formats that restrict the input to this sink. This can be used to force an automatic conversion from the device’s pixel format to a pixel format usable by the sink.

  • max_output_buffers (int) – Defines the maximum number of buffers that are stored in the sink’s output queue. If set to 0, the number of buffers is unlimited. If a new frame arrives at the sink, and the output queue size would exceed this number, the oldest image is discarded and its buffer is added to the free queue.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property type: SinkType

The type of the sink.

For a queue sink, this returns SinkType.QUEUESINK.

property output_image_type: ImageType

The image type of the images the sink is configured to receive

Return type:

ImageType

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

alloc_and_queue_buffers(count: int) → None

Allocates a number of buffers matching the sink’s image type and puts them into the free queue.

Parameters:

count (int) – Number of buffers to allocate

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

property is_cancel_requested: bool

Indicates whether the data stream this sink is connected to is in the process of being stopped.

Return type:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

pop_output_buffer() → ImageBuffer

Retrieves a buffer that was filled with image data from the sink’s output queue.

This operation is only valid while the sink is connected to a device in a data stream.

The buffers are retrieved in order they were received from the video capture device; the oldest image is returned first.

After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer object must be deleted, or ImageBuffer.release() must be called to put the image buffer into the sink’s free queue for later reuse.

Returns:

A filled image buffer

Return type:

ImageBuffer

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

try_pop_output_buffer() → ImageBuffer | None

Tries to retrieve a buffer that was filled with image data from the sink’s output queue.

In contrast to pop_output_buffer(), this function does not raise an exception in case of an error.

This operation is only valid while the sink is connected to a device in a data stream.

The buffers are retrieved in order they were received from the video capture device; the oldest image is returned first.

After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer object must be deleted, or ImageBuffer.release() must be called to put the image buffer into the sink’s free queue for later reuse.

Returns:

A filled image buffer, or None if no image was available.

Return type:

Optional[ImageBuffer]

class QueueSizes(free_queue_length: int, output_queue_length: int)

Bases: object

Contains information about the current queue lengths inside the queue sink

free_queue_length: int

Number of image buffers in the free queue

output_queue_length: int

Number of filled image buffers in the output queue

queue_sizes() → QueueSizes

The lengths of the queues in the sink

Return type:

QueueSizes

class SinkType(value)

Bases: IntEnum

Defines the possible sink types.

To determine the type of a sink object, use Sink.type.

SNAPSINK = 5

The sink is a SnapSink

QUEUESINK = 4

The sink is a QueueSink

class Sink(h: c_void_p)

Bases: ABC

Abstract base class for sinks.

Sink objects provide programmatic access to the image data acquired from video capture devices.

There are multiple sink types available:

  • A QueueSink is recommended when a program needs to process all or most images received from the device.

  • A SnapSink can be used to capture images or short image sequences on demand.

A sink is connected to a video capture device using Grabber.stream_setup().

property is_attached: bool

Indicates whether a sink is currently attached to a Grabber as part of a data stream.

Return type:

bool

class Mode(value)

Bases: IntEnum

Defines the possible sink modes.

RUN = 0

Normal operation

PAUSE = 1

Pause operation. The sink will ignore all incoming frames.

property mode: Mode

The current sink mode.

The sink mode can be used to temporarily suspend sink operation.

Sinks are set to Mode.RUN by default.

Return type:

Mode

abstract property type: SinkType

The type of the sink

Return type:

SinkType

class SnapSink(strategy: AllocationStrategy | None = None, accepted_pixel_formats: List[PixelFormat] = [])

Bases: Sink

The snap sink is a sink implementation that allows a program to capture single images or sequences of images on demand, while still having a display showing all images.

Pass the sink to Grabber.stream_setup() to feed images into the sink.

To grab a single image out of the stream, call snap_single(). To grab a sequence of images, call snap_sequence().

The snap sink manages the buffers used for background image aquisition as well as for the grabbed images. During stream setup, a number of buffers is allocated depending on the configured allocation strategy. Additional buffers can be automatically created on demand, if the allocation strategy allows. Likewise, if there is a surplus of unused image buffers, unused buffers are reclaimed and released automatically.

Image buffers that were returned by one of the snap functions are owned by their respective caller through the reference to the ImageBuffer. To return the image buffer to the sink for reuse, let the variable go out of scope, or call ImageBuffer.release() on the image buffer.

Please note that if there are no buffers available in the sink when the device tries to deliver a frame, the frame will be dropped. Use Grabber.StreamStatistics to find out whether a buffer underrun occurred.

Parameters:

  • strategy (Optional[AllocationStrategy]) – An optional buffer allocation strategy for the sink. If this is None, a default allocation strategy is used.

  • accepted_pixel_formats (List[PixelFormat]) – An optional list of pixel formats that restrict the input to this sink. This can be used to force an automatic conversion from the device’s pixel format to a pixel format usable by the sink.

class AllocationStrategy(num_buffers_alloc_on_connect: int = 0, num_buffers_allocation_threshold: int = 0, num_buffers_free_threshold: int = 0, num_buffers_max: int = 0)

Bases: object

The SnapSink buffer allocation strategy defines how many buffers are pre-allocated, whe additional buffers are created, and when excess buffers are reclaimed.

Parameters:

  • num_buffers_alloc_on_connect (int) – Defines the number of buffers to auto-allocate when the stream is set up.

  • num_buffers_allocation_threshold (int) – Defines the minimum number of required free buffers. If the number of free buffers falls below this, new buffers are allocated.

  • num_buffers_free_threshold (int) – Defines the maximum number of free buffers. If the number of free buffers grows above this, buffers are freed. If set to 0, buffers are not freed automatically.

  • num_buffers_max (int) – Defines the maximum total number of buffers this sink will allocate. This includes both free buffers managed by the sink and filled buffers owned by the program. If set to 0, there is no limit to the total number of buffers.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

If NumBuffersFreeThreshold is not 0, it must be larger than NumBuffersAllocationThreshold + 2.

num_buffers_alloc_on_connect: int
num_buffers_allocation_threshold: int
num_buffers_free_threshold: int
num_buffers_max: int
property type: SinkType

The type of the sink.

For a snap sink, this returns SinkType.SNAPSINK.

property output_image_type: ImageType

The image type of the images the sink is configured to receive

Return type:

ImageType

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

snap_single(timeout_ms: int) → ImageBuffer

Grabs a single image out of the video stream received from the video capture device.

This operation is only valid while the sink is connected to a device in a data stream.

After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer object must be released to put the image buffer into the sink’s free queue for later reuse.

Parameters:

timeout_ms (int) – Time to wait (in milliseconds) for a new image to arrive

Returns:

A filled image buffer

Return type:

ImageBuffer

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

snap_sequence(count: int, timeout_ms: int) → Sequence[ImageBuffer]

Grabs a sequence of images out of the video stream received from the video capture device.

This operation is only valid while the sink is connected to a device in a data stream.

After a successfull call, the program owns the image buffer through the ImageBuffer reference. The image buffer objects must be released to put the image buffer into the sink’s free queue for later reuse.

Parameters:

  • count (int) – Number of images to grab

  • timeout_ms (int) – Time to wait (in milliseconds) for the number of images to arrive

Returns:

The list of grabbed images. If the timeout expires, the returned list contains the images grabbed until then.

Return type:

Tuple[ImageBuffer]

Video Writer

class VideoWriterType(value)

Bases: IntEnum

Defines the available video writer types.

MP4_H264 = 0

Create MP4 files with H.264 encoding.

MP4_H265 = 1

Create MP4 files with H.265/HEVC encoding

class VideoWriter(type: VideoWriterType)

Bases: object

Represents a video writer

Parameters:

type (VideoWriterType) – The type of video file to create a writer for

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

begin_file(path: Path | str, image_type: ImageType, frame_rate: float)

Open a new video file ready to write images into.

Parameters:

  • path (Path|str) – File path to where the video shall be stored.

  • image_type (ImageType) – Description of frames that will be received.

  • frame_rate (float) – ImageBuffer rate at which playback shall happen, usually equal to used AcquisitionFrameRate

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

finish_file()

Finish writing video file.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

add_frame(buffer: ImageBuffer)

Add an image to the currently open video file.

Parameters:

buffer (ImageBuffer) – Image that shall be added to the file.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Remarks:

The image buffer’s image type must be equal to the image_type parameter passed to begin_file() when starting the file.

The video writer can retain a reference to the image buffer. This can delay the release and possible reuse of the image buffer. In this case, the buffer becomes shared, and is no longer safely writable (see ImageBuffer.is_writable). Use add_frame_copy() to always let the video writer immediately copy the data out of the image buffer.

add_frame_copy(buffer: ImageBuffer)

Adds an image to the currently open video file, copying its contents in the process.

Parameters:

buffer (ImageBuffer) – Image that shall be added to the file.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Remarks:

The image buffer’s image type must be equal to the image_type parameter passed to begin_file() when starting the file.

The image buffer’s contents will be copied, so that the buffer’s reference count is not increased and it can be reused immedietely if the final reference is released. Use add_frame() to avoid the copy operation if it is not necessary.

property property_map: PropertyMap

Return the property map for the video writer.

The property map returned from this function allows configuring codec options.

Returns:

A property map to control the video writer.

Raises:

IC4Exception – In case of an error. Check IC4Exception.code and IC4Exception.message for details.

Display

class DisplayType(value)

Bases: IntEnum

Enumerating containt the available display types

DEFAULT = 0

Use the default display for the current platform

WIN32_OPENGL = 1

Optimized OpenGL display for Windows platform

LINUX_GSTREAMER = 2

Simple GStreamer-based display for Linux platform

class DisplayRenderPosition(value)

Bases: IntEnum

Enumeration containing the possible display content alignment modes

TOPLEFT = 0

The video is not scaled and displayed in the top left corner of the window.

CENTER = 1

The video is not scaled and displayed centered inside the window.

STRETCH_TOPLEFT = 2

The video is maximized to fit the size of the window and displayed in the top left corner.

STRETCH_CENTER = 3

The video maximized to fit the size of the window, and displayed centered.

CUSTOM = 4

Specify a custom rectangle

class Display(h: c_void_p)

Bases: object

Base class for all displays.

Displays can be used to show images from video capture devices.

To display a live stream from a camera, set up the stream to a display using Grabber.stream_setup.

To display single images, use the Display.display_buffer method.

class WindowClosedNotificationToken(func: Callable[[c_void_p, c_void_p], None], deleter: Callable[[c_void_p], None])

Bases: object

Represents a registered callback.

When a callback function is registered using event_add_window_closed(), a token is returned.

The token can then be used to remove the callback using event_remove_window_closed() at a later time.

set_render_position(pos: DisplayRenderPosition, left: int = 0, top: int = 0, right: int = 0, bottom: int = 0)

Configure the position of the video image inside the display.

Parameters:

  • mode (DisplayRenderPosition) – A pre-defined position

  • left (int, optional) – The x coordinate of the left edge of the image inside the display window. Defaults to 0. Can be negative to only show parts of the image. This value is ignored unless pos is set to DisplayRenderPosition.CUSTOM.

  • top (int, optional) – The y coordinate of the top edge of the image inside the display window. Defaults to 0. Can be negative to only show parts of the image. This value is ignored unless pos is set to DisplayRenderPosition.CUSTOM.

  • right (int, optional) – The x coordinate of the right edge of the image inside the display window. Defaults to 0. Can be greater than the size of the display to only show parts of the image. This value is ignored unless pos is set to DisplayRenderPosition.CUSTOM.

  • bottom (int, optional) – The y coordinate of the bottom edge of the image inside the display window. Defaults to 0. Can be greater than the size of the display to only show parts of the image. This value is ignored unless pos is set to DisplayRenderPosition.CUSTOM.

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

display_buffer(buffer: ImageBuffer | None)

Display an image in the display.

If the display is selecteded as the destination of a Grabber’s stream using Grabber.stream_setup(), the image might be immediately replaced by a new image.

Parameters:

buffer (ImageBuffer) – The image to be displayed

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

Note

When buffer is None, the display is cleared and will no longer display the previous buffer.

class Statistics(num_displayed: int, num_dropped: int)

Bases: object

Contains statistics about a display.

num_displayed: int

The number of frames displayed by the display

num_dropped: int

The number of frames that were delivered to the display, but not displayed.

Display frame drops are usually caused by frames arriving at the display in an interval shorter than the screen’s refresh rate.

property statistics: Statistics

Query statistics for this display.

Returns:

An objects containing display statistics.

Return type:

Statistics

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_add_window_closed(handler: Callable[[Display], None]) → WindowClosedNotificationToken

Register a callback function to be called in the event that the currently opened video capture device becomes unavailable.

Parameters:

handler (Callable[[Display], None]) – The callback function to be called if the display window is closed

Returns:

A token that can be used to unregister the callback using event_remove_window_closed().

Return type:

WindowClosedNotificationToken

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

event_remove_window_closed(token: WindowClosedNotificationToken)

Unregister a window-closed handler that was previously registered using event_add_window_closed().

Parameters:

token (WindowClosedNotificationToken) – The token that was returned from the registration function

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

class FloatingDisplay

Bases: Display

A display with a floating top-level window.

class EmbeddedDisplay(parent: int)

Bases: Display

A display embedded inside an existing window.

GUI

class PropertyDialogFlags(value)

Bases: IntFlag

Defines options to customize the behavior of dialogs displaying property maps.

DEFAULT = 0

Default behavior

ALLOW_STREAM_RESTART = 1

Allows the user to change the value of device properties that would require a stream restart to do so.

The dialog will automatically restart the stream when one of those properties is changed.

RESTORE_STATE_ON_CANCEL = 2

Instructs the dialog to initially save the state of all properties, and restore them to their original value if the dialog is closed using the Cancel button.

SHOW_TOP_CATEGORY = 4

If set, the top-level category is displayed in the property tree view of the property dialog.

HIDE_FILTER = 8

If set, the dialog does not display the visibility dropdown and filter text box.

class Dialogs

Bases: object

Provides a set of functions showing various builtin dialogs.

classmethod grabber_select_device(grabber: Grabber, parent: int) → bool

Displays a dialog allowing the user to select a video capture device to be opened by a grabber object.

Parameters:

  • grabber (Grabber) – A grabber object

  • parent (int) – Handle to a parent window for the dialog

Returns:

True, if the user selected a device. False, if the user pressed Cancel or closed the dialog.

Return type:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

classmethod grabber_device_properties(grabber: Grabber, parent: int, flags: PropertyDialogFlags = PropertyDialogFlags.DEFAULT, category: str | None = 'Root', title: str | None = None, initial_visibility: PropertyVisibility = PropertyVisibility.BEGINNER, initial_filter: str | None = None) → bool

Displays a dialog allowing the user to view and edit the features in the property map of the video capture device opened by a grabber object.

Parameters:

  • grabber (Grabber) – A grabber object with an opened device

  • parent (int) – Handle to a parent window for the dialog

  • flags (PropertyDialogFlags, optional) – Configures the dialog’s behavior. Defaults to PropertyDialogFlags.DEFAULT.

  • category (str, optional) – Category in the property map to display. Defaults to “Root”.

  • title (str, optional) – The title of the dialog. If set to None, a default title is set. Defaults to None.

  • initial_visibility (PropertyVisibility, optional) – Pre-selects a property visibility in the property dialog’s visibility selector. Defaults to PropertyVisibility.BEGINNER.

  • initial_filter (str, optional) – Insert a text into the property dialog’s filter textbox. Defaults to None.

Returns:

True, if the user closed the dialog using the OK button. False, if the user pressed Cancel or closed the dialog.

Return type:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

classmethod show_property_map(map: PropertyMap, parent: int, flags: PropertyDialogFlags = PropertyDialogFlags.DEFAULT, category: str | None = 'Root', title: str | None = None, initial_visibility: PropertyVisibility = PropertyVisibility.BEGINNER, initial_filter: str | None = None) → bool

Displays a dialog allowing the user to view and edit the features in a property map.

The view can be limited by specifying a category in the property map.

Parameters:

  • map (PropertyMap) – A property map

  • parent (int) – Handle to a parent window for the dialog

  • flags (PropertyDialogFlags) – Configures the dialog’s behavior. Defaults to PropertyDialogFlags.DEFAULT.

  • category (str, optional) – Category in the property map to display. Defaults to “Root”.

  • title (str, optional) – The title of the dialog. If set to None, a default title is set. Defaults to None.

  • initial_visibility (PropertyVisibility, optional) – Pre-selects a property visibility in the property dialog’s visibility selector. Defaults to PropertyVisibility.BEGINNER.

  • initial_filter (str, optional) – Insert a text into the property dialog’s filter textbox. Defaults to None.

Returns:

True, if the user closed the dialog using the OK button. False, if the user pressed Cancel or closed the dialog.

Return type:

bool

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.

classmethod select_device(parent: int) → DeviceInfo | None

Displays a dialog allowing the user to select a video capture device.

Parameters:

parent (int) – Handle to a parent window for the dialog

Returns:

The selected video capture device, or None if the dialog was closed without selecting a device.

Return type:

Optional[DeviceInfo]

Raises:

IC4Exception – An error occurred. Check IC4Exception.code and IC4Exception.message for details.