IC Imaging Control 4 Python Library

https://www.theimagingsource.com/en-us/documentation/ic4python/
Admin
This documentation guides users on installing and using the IC Imaging Control 4 Python Library,...
Tokens:48,820
Snippets:474
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Setup Data Stream with SnapSink

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-grabbing-an-image.html

Creates a SnapSink for grabbing single images and sets up the data stream from the device to the sink, starting image acquisition immediately. The SnapSink is suitable for on-demand image grabbing.

```python
# Create a SnapSink. A SnapSink allows grabbing single images (or image sequences) out of a data stream.
sink = ic4.SnapSink()
# Setup data stream from the video capture device to the sink and start image acquisition.
grabber.stream_setup(sink, setup_option=ic4.StreamSetupOption.ACQUISITION_START)

```

--------------------------------

### Install IC Imaging Control 4 from PyPI

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-getting-started.html

Install the library using pip. This command installs the core library.

```bash
$ python3 -m pip install imagingcontrol4

```

--------------------------------

### Install IC Imaging Control 4 from Local Wheel File

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-getting-started.html

Install the library from a local .whl file. Ensure the path and version are correct for your system.

```bash
$ python3 -m pip install imagingcontrol4-1.0.0-py36-none-win_amd64.whl

```

--------------------------------

### Install IC Imaging Control 4 with PySide6 Support

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-getting-started.html

Install the library along with PySide6 dialog support. This is for using pre-built dialogs.

```bash
$ python3 -m pip install imagingcontrol4pyside6

```

--------------------------------

### Clone ic4-examples Repository

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/example-programs.html

Use this command to download the example programs from GitHub using the Git command-line tool.

```bash
$ git clone https://github.com/TheImagingSource/ic4-examples.git

```

--------------------------------

### Quick Test: Initialize and List Devices

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-getting-started.html

Verify the installation by initializing the library and listing connected video capture devices within the Python interpreter.

```python
Python 3.10.11 (tags/v3.10.11:7d4cc5a, Apr  5 2023, 00:38:17) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import imagingcontrol4 as ic4
>>> ic4.Library.init()
>>> ic4.DeviceEnum.devices()
[DeviceInfo(model_name='DFK 33GX546', serial='12229933', version='Rev 3013, FPGA GigE3LM-IMX:126')]

```

--------------------------------

### StreamSetupOption

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Enumerates options for configuring image stream setup.

```APIDOC
## StreamSetupOption

### Description
Enumerates options for configuring image stream setup.

### Enum Members
* **`ACQUISITION_START`**: Option to start acquisition immediately after stream setup.
* **`DEFER_ACQUISITION_START`**: Option to defer acquisition start until explicitly requested.
```

--------------------------------

### stream_setup

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Sets up the data stream from the device. This function requires the device to be opened first. It configures whether to immediately start acquisition after the data stream is set up.

```APIDOC
## stream_setup

### Description
Sets up the data stream from the device, with an option to immediately start acquisition.

### 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 data stream was set up successfully. Defaults to 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.
```

--------------------------------

### acquisition_start

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Starts the acquisition of images from the video capture device. A data stream must be established before calling this function.

```APIDOC
## acquisition_start

### Description
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.
```

--------------------------------

### is_acquisition_active

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Checks if image acquisition has been started.

```APIDOC
## is_acquisition_active

### Description
True if image acquisition was started, otherwise False.
```

--------------------------------

### Get All Properties

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Retrieves a collection of all properties, excluding PropCategory properties.

```APIDOC
## property_all

### Description
Get all properties. Does not include PropCategory properties.

### Method
Not Applicable (Python method)

### Endpoint
Not Applicable (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **Sequence[Property]** (Sequence[Property]) - Collection of all properties.

#### Response Example
None

### Raises
**IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### Grabber

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Manages the connection to an imaging device, stream setup, acquisition control, and retrieval of image data and statistics.

```APIDOC
## Grabber

### Description
Manages the connection to an imaging device, stream setup, acquisition control, and retrieval of image data and statistics.

### Properties
* **`sink`** (object): The sink object for receiving image data.
* **`display`** (object): The display object for visualizing image data.
* **`is_device_open`** (boolean): True if the device is currently open.
* **`is_device_valid`** (boolean): True if the device is valid.
* **`device_info`** (DeviceInfo): Information about the connected device.
* **`is_streaming`** (boolean): True if the image stream is active.
* **`is_acquisition_active`** (boolean): True if acquisition is currently active.
* **`device_property_map`** (dict): A dictionary of the device's properties.
* **`driver_property_map`** (dict): A dictionary of the driver's properties.
* **`stream_statistics`** (Grabber.StreamStatistics): Statistics related to the image stream.

### Methods
* **`device_open()`**: Opens the connection to the imaging device.
* **`device_close()`**: Closes the connection to the imaging device.
* **`stream_setup(options)`**: Configures the image stream with the specified options.
* **`stream_stop()`**: Stops the image stream.
* **`acquisition_start()`**: Starts the image acquisition process.
* **`acquisition_stop()`**: Stops the image acquisition process.
* **`event_add_device_lost()`**: Registers a callback function to be notified when the device is lost.
* **`event_remove_device_lost()`**: Unregisters a callback function for device lost notifications.
* **`device_save_state()`**: Saves the current state of the device.
* **`device_open_from_state()`**: Opens the device using a previously saved state.
* **`device_save_state_to_file(filepath)`**: Saves the current state of the device to a file.
* **`device_open_from_state_file(filepath)`**: Opens the device from a state file.

### Events
* **`DeviceLostNotificationToken`** (object): A token used to manage device lost notifications.
```

--------------------------------

### Device Properties Constants

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

This section lists the constants used to access various device properties. These constants are used to get or set specific device parameters.

```APIDOC
## Device Properties Constants

This document outlines the constants available for interacting with device properties. These are used to configure and retrieve settings for various device functionalities.

### Property Constants

- **ACQUISITION_BURST_FRAME_COUNT**: Number of frames to acquire for each trigger.
- **ACQUISITION_BURST_INTERVAL**: Minimum interval between frames in an acquisition burst.
- **ACQUISITION_FRAME_RATE**: Controls the acquisition rate at which frames are captured.
- **ACQUISITION_MODE**: Sets the acquisition mode, defining the number of frames and acquisition stop conditions.
- **ACQUISITION_START**: Starts the acquisition of the device.
- **ACQUISITION_STOP**: Stops the acquisition of the device at the end of the current frame.
- **ACTION_DEVICE_KEY**: Provides the device key for validating action commands.
- **ACTION_GROUP_KEY**: Provides the key for validating actions upon reception of the action protocol message.
- **ACTION_GROUP_MASK**: Provides the mask for validating actions upon reception of the action protocol message.
- **ACTION_QUEUE_SIZE**: Indicates the size of the scheduled action commands queue.
- **ACTION_SCHEDULER_CANCEL**: Cancels all scheduled actions.
- **ACTION_SCHEDULER_COMMIT**: Schedules an action to be executed at a specified time.
- **ACTION_SCHEDULER_INTERVAL**: Action repetition interval. A value of 0 schedules the action to be executed only once.
- **ACTION_SCHEDULER_STATUS**: Indicates whether there are actions scheduled.
- **ACTION_SCHEDULER_TIME**: Camera time for when the action is to be scheduled.
- **ACTION_SELECTOR**: Selects to which Action Signal further Action settings apply.
- **AUTO_FOCUS_ROI_ENABLE**: Enable the region of interest for auto focus.
- **AUTO_FOCUS_ROI_HEIGHT**: Vertical size of the auto focus region of interest.
- **AUTO_FOCUS_ROI_LEFT**: Horizontal offset of the auto focus region of interest.
- **AUTO_FOCUS_ROI_TOP**: Vertical offset of the auto focus region of interest.
- **AUTO_FOCUS_ROI_WIDTH**: Horizontal size of the auto focus region of interest.
- **AUTO_FUNCTIONS_ROI_ENABLE**: Enable the region of interest for auto functions.
- **AUTO_FUNCTIONS_ROI_HEIGHT**: Vertical size of the auto functions region of interest.
- **AUTO_FUNCTIONS_ROI_LEFT**: Horizontal offset of the auto functions region of interest.
- **AUTO_FUNCTIONS_ROI_PRESET**: Select a predefined region of interest for auto functions.
- **AUTO_FUNCTIONS_ROI_TOP**: Vertical offset of the auto functions region of interest.
- **AUTO_FUNCTIONS_ROI_WIDTH**: Horizontal size of the auto functions region of interest.
- **BALANCE_RATIO**: Controls the ratio of a selected color component to a reference color component for white balancing.
- **BALANCE_RATIO_SELECTOR**: Selects a balance ratio control for configuration.
- **BALANCE_WHITE_AUTO**: Controls the mode for automatic white balancing between color channels.
- **BALANCE_WHITE_AUTO_PRESET**: Selects a specific preset for automatic white balance.
- **BALANCE_WHITE_MODE**: Configures the way auto white balance works.
- **BALANCE_WHITE_TEMPERATURE**: Adjusts white balance controls to match ambient light temperature.
- **BALANCE_WHITE_TEMPERATURE_PRESET**: Selects a specific white balance preset.
```

--------------------------------

### Get Root Category

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Retrieves the Root category of this property map.

```APIDOC
## property_root_category

### Description
Gets the Root category.

### Method
Not Applicable (Python method)

### Endpoint
Not Applicable (Python method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response
- **PropCategory** (PropCategory) - The Root category of this property map

#### Response Example
None

### Raises
**IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### Grabber.stream_setup

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Establishes the data stream from the device, which is required for image acquisition. A sink, a display, or both must be included.

```APIDOC
## Grabber.stream_setup

### Description
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.

### Method
`stream_setup`

### Parameters
#### Path Parameters
- **sink** (Sink | None) - Optional - The sink for the data stream.
- **display** (Display | None) - Optional - The display for the data stream.
- **setup_option** (StreamSetupOption) - Optional - Options to customize the stream setup behavior. Defaults to `StreamSetupOption.ACQUISITION_START`.
```

--------------------------------

### Library.init

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Initializes the IC Imaging Control 4 Python library with specified logging configurations.

```APIDOC
## Library.init

### Description
Initializes the IC Imaging Control 4 Python library. Allows configuration of API and internal log levels, log targets, and an optional log file.

### Method
classmethod

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### 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.
```

--------------------------------

### acquisition_stop

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Stops the acquisition of images from the video capture device. Acquisition must have been started previously.

```APIDOC
## acquisition_stop

### Description
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.
```

--------------------------------

### Initialize Library and Open Device

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-grabbing-an-image.html

Initializes the ImagingControl4 library and opens the first available video capture device. Ensure the library is initialized before proceeding.

```python
import imagingcontrol4 as ic4
ic4.Library.init()

# Create a Grabber object
grabber = ic4.Grabber()

# Open the first available video capture device
first_device_info = ic4.DeviceEnum.devices()[0]
grabber.device_open(first_device_info)

```

--------------------------------

### Library.init_context

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Initializes the IC Imaging Control 4 Python library and returns a context manager for use in 'with' statements.

```APIDOC
## Library.init_context

### Description
Initializes the IC Imaging Control 4 Python library, returning a context manager to be used in with statements. Ensures proper cleanup upon exiting the context.

### Method
classmethod

### 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.

### Request Example
```python
with ic4.Library.init_context():
    grabber = ic4.Grabber()
    # ...
# ic4.Library.exit() is called automatically here
```

### Raises
* **RuntimeError** - Failed to initialize the library.
* **FileNotFoundError** - Internal error.
```

--------------------------------

### Get Image Pixel Format

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Retrieves the pixel format of an image. The format may be an integer if it's not a member of the PixelFormat enumeration.

```python
image_type._pixel_format: PixelFormat | int
```

--------------------------------

### Open First Available Video Capture Device

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-configuring-device.html

Initializes the library and opens the first available video capture device. Ensure the imagingcontrol4 library is initialized before creating a Grabber object.

```python
import imagingcontrol4 as ic4

# Initialize library
ic4.Library.init()

# Create a Grabber object
grabber = ic4.Grabber()

# Open the first available video capture device
first_device_info = ic4.DeviceEnum.devices()[0]
grabber.device_open(first_device_info)
```

--------------------------------

### _DisplayWindow.as_display

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Returns a Display object to connect this display window to a data stream. This Display can be passed to Grabber.stream_setup() to display live video.

```APIDOC
## _DisplayWindow.as_display()

### Description
Returns a `Display` to connect this display window to a data stream.

### Returns
- **Display** - A `Display` for this display window.

### Usage
Pass the return value of this function to `Grabber.stream_setup()` to display live video on this display window.
```

--------------------------------

### Initialize Library with Context Manager

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Use the init_context method to initialize the library within a 'with' statement. This ensures that Library.exit() is called automatically upon exiting the block.

```python
with ic4.Library.init_context():
    grabber = ic4.Grabber()
    # ...
# ic4.Library.exit() is called automatically here
```

--------------------------------

### _DisplayWidget.as_display

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Returns a Display object to connect this display widget to a data stream. This Display can be passed to Grabber.stream_setup() to display live video.

```APIDOC
## _DisplayWidget.as_display()

### Description
Returns a `Display` to connect this display widget to a data stream.

### Returns
- **Display** - A `Display` for this display widget.

### Usage
Pass the return value of this function to `Grabber.stream_setup()` to display live video on this display widget.
```

--------------------------------

### _ExternalOpenGLDisplay.initialize

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Initializes the external OpenGL display. This method must be called with the OpenGL context activated for the executing thread.

```APIDOC
## _ExternalOpenGLDisplay.initialize

### Description
Initialize the external OpenGL display.
Note
This function must be called with the OpenGL context activated for the executing thread (e.g. makeCurrent).

### Method
POST

### Endpoint
/_ExternalOpenGLDisplay/initialize
```

--------------------------------

### Print Video Capture Devices by Interface and Topology

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-device-enumeration.html

Enumerates video capture devices organized by their physical interfaces (e.g., USB controllers). It prints interface details and the devices connected to each. Requires the `ic4` library.

```python
def print_interface_device_tree():
    print("Enumerating video capture devices by interface...")

    interface_list = ic4.DeviceEnum.interfaces()

    if len(interface_list) == 0:
        print("No interfaces found")
        return

    for itf in interface_list:
        print(f"Interface: {itf.display_name}")
        print(f"\tProvided by {itf.transport_layer_name} [TLType: {str(itf.transport_layer_type)}]")

        device_list = itf.devices

        if len(device_list) == 0:
            print("\tNo devices found")
            continue

        print(f"\tFound {len(device_list)} devices:")

        for device_info in device_list:
            print(f"\t\t{format_device_info(device_info)})
```

--------------------------------

### _DeviceSelectionDialog

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Displays a device selection dialog. If the user selects a device, the device is opened in the passed grabber.

```APIDOC
## _DeviceSelectionDialog(_grabber : Grabber_, _parent : QWidget | None = None_)

### Description
Displays a device selection dialog. If the user selects a device, the device is opened in the passed grabber.

### Parameters
- **grabber** (_imagingcontrol4.Grabber_) – A grabber object in which the selected device is opened
- **parent** (_PySide6.QtWidgets.QWidget_) – Parent widget for the dialog
```

--------------------------------

### QueueSink Initialization

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Initializes a QueueSink with a listener and optional pixel format restrictions and maximum output buffer count.

```APIDOC
## QueueSink Constructor

### Description
Initializes a new instance of the QueueSink class.

### Parameters
* **listener** (`QueueSinkListener`) – An object implementing the `QueueSinkListener` abstract base class to control the sink's behavior.
* **accepted_pixel_formats** (`List[PixelFormat]`) – Optional. A list of pixel formats to restrict input to this sink. This can enforce automatic conversion.
* **max_output_buffers** (`int`) – Defines the maximum number of buffers stored in the sink's output queue. If 0, the number is unlimited. Exceeding this limit discards the oldest image.
```

--------------------------------

### DisplayWindow

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

A PySide6 window class that integrates display capabilities, allowing image data to be rendered within a window.

```APIDOC
## DisplayWindow

### Description
A PySide6 window class that integrates display capabilities, allowing image data to be rendered within a window.

### Methods
* `DisplayWindow.as_display()`
```

--------------------------------

### Library.exit

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Un-initializes the IC Imaging Control 4 Python library.

```APIDOC
## Library.exit

### Description
Un-initializes the IC Imaging Control 4 Python library, releasing any resources it holds.

### Method
classmethod

### Parameters
None

### Request Example
None

### Response
None

### Raises
None
```

--------------------------------

### _select_device

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Displays a dialog for selecting a video capture device. Returns DeviceInfo if a device is selected, or None if Cancel is pressed.

```APIDOC
## _select_device

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

### Method
classmethod

### Parameters
#### Path Parameters
- **parent** (int) - Required - Handle to a parent window for the dialog

### Response
#### Success Response
- **return** (DeviceInfo | None) - Device information if a device is selected, otherwise None.
```

--------------------------------

### Display Class Methods

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Methods for configuring and managing display properties and content.

```APIDOC
## Display Class Methods

### set_render_position

#### Description
Configure the position of the video image inside the display.

#### Parameters
- **mode** (DisplayRenderPosition) - Required - A pre-defined position.
- **left** (int) - Optional - The x coordinate of the left edge of the image inside the display window. Defaults to 0. 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. This value is ignored unless _pos_ is set to `DisplayRenderPosition.CUSTOM`.
- **width** (int) - Optional - The width the image inside the display window. Defaults to 0. This value is ignored unless _pos_ is set to `DisplayRenderPosition.CUSTOM`.
- **height** (int) - Optional - The height of the image inside the display window. Defaults to 0. This value is ignored unless _pos_ is set to `DisplayRenderPosition.CUSTOM`.

#### Raises
- **IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.

### can_render

#### Description
Checks whether the display can render images of a specified image type.

#### Parameters
- **image_type** (ImageType) - Required - The image type to check.

#### Returns
- bool - True if the display can render the specified image type, otherwise False.

### raise_if_cannot_render

#### Description
Checks whether the display can render images of a specified image type.

#### Parameters
- **image_type** (ImageType) - Required - The image type to check.

#### Remarks
The function raises an error if the specified image type can not be rendered by the display.

### display_buffer

#### Description
Display an image in the display. If the display is selected 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 | None) - The image to be displayed. When buffer is None, the display is cleared and will no longer display the previous buffer.

#### Raises
- **IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.

### statistics

#### Description
Query statistics for this display.

#### Returns
- Statistics - An object containing display statistics.

#### Raises
- **IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### Enumerate Possible Image Transformations

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Queries the possible destination formats into which the library can convert image buffers of a given source format. This is useful for understanding conversion capabilities.

```python
ImageBuffer._enum_transforms(src: PixelFormat) -> Collection[PixelFormat | int]
```

--------------------------------

### Library.get_version_info

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Retrieves version information about the IC Imaging Control 4 library and its components.

```APIDOC
## Library.get_version_info

### Description
Retrieves version information about the IC Imaging Control 4 library and its components based on the provided flags.

### Method
classmethod

### Parameters
* **flags** (VersionInfoFlags, optional) - Defines which version information to retrieve. Defaults to `VersionInfoFlags.DEFAULT`.

### Response
#### Success Response (200)
* **version_info** (str) - A string containing the requested version information.

### Raises
None
```

--------------------------------

### Print List of All Attached Video Capture Devices

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-device-enumeration.html

Retrieves a flat list of all available video capture devices and prints their model and serial information. Ensure the `ic4` library is imported.

```python
def print_device_list():
    print("Enumerating all attached video capture devices...")

    device_list = ic4.DeviceEnum.devices()

    if len(device_list) == 0:
        print("No devices found")
        return

    print(f"Found {len(device_list)} devices:")

    for device_info in device_list:
        print(format_device_info(device_info))
```

```python
def format_device_info(device_info: ic4.DeviceInfo) -> str:
    return f"Model: {device_info.model_name} Serial: {device_info.serial}"
```

--------------------------------

### device_open_from_state_file

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Restores the opened device and its settings from a file previously created by `device_save_state_to_file()`. The grabber must not have a device opened when calling this function.

```APIDOC
## device_open_from_state_file

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

### Parameters
#### Path Parameters
- **path** (Path | str) - Required - 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.
```

--------------------------------

### _grabber_select_device

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Displays a dialog for selecting a video capture device to be opened by a grabber object. Returns true if a device is selected, false otherwise.

```APIDOC
## _grabber_select_device

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

### Method
classmethod

### Parameters
#### Path Parameters
- **grabber** (Grabber) - Required - A grabber object
- **parent** (int) - Required - Handle to a parent window for the dialog

### Response
#### Success Response
- **return** (bool) - True, if the user selected a device. False, if the user pressed Cancel or closed the dialog.

#### Raises
- **IC4Exception** - An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### Device Properties Documentation

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

This section lists and describes various device properties available for configuration and retrieval. These properties control aspects of image acquisition, device behavior, and synchronization.

```APIDOC
## Device Properties

This page details device properties that can be configured or read, covering aspects like image offsets, pixel formats, PTP clock settings, image transformations, strobe controls, and trigger configurations.

### Property List

- **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.
```

--------------------------------

### Configure Device Resolution

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-grabbing-an-image.html

Sets the resolution of the video capture device using PropId.WIDTH and PropId.HEIGHT. This ensures the camera is in a defined state before operation.

```python
# Set the resolution to 640x480
grabber.device_property_map.set_value(ic4.PropId.WIDTH, 640)
grabber.device_property_map.set_value(ic4.PropId.HEIGHT, 480)

```

--------------------------------

### Configure Device Resolution and Pixel Format

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-configuring-device.html

Sets the device to output Mono8 data and configures the resolution to 640x480. This snippet assumes a device has already been opened.

```python
# Configure the device to output images in the Mono8 pixel format
grabber.device_property_map.set_value(ic4.PropId.PIXEL_FORMAT, ic4.PixelFormat.Mono8)

# Set the resolution to 640x480
grabber.device_property_map.set_value(ic4.PropId.WIDTH, 640)
grabber.device_property_map.set_value(ic4.PropId.HEIGHT, 480)
```

--------------------------------

### Set Fixed Exposure Time and Enable Auto Gain

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/guide-configuring-device.html

Configures the device to a fixed exposure time of 5ms and enables continuous automatic gain control. This snippet is useful for consistent image capture under varying lighting conditions.

```python
# Configure the exposure time to 5ms (5000µs)
grabber.device_property_map.set_value(ic4.PropId.EXPOSURE_AUTO, "Off")
grabber.device_property_map.set_value(ic4.PropId.EXPOSURE_TIME, 5000.0)

# Enable GainAuto
grabber.device_property_map.set_value(ic4.PropId.GAIN_AUTO, "Continuous")
```

--------------------------------

### QueueSinkListener Abstract Methods

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Abstract methods for QueueSink listeners to handle sink connection, disconnection, and frame queuing events.

```APIDOC
## Sinks

### _class _QueueSinkListener

Abstract base class for `QueueSink` listener.

### _abstract _sink_connected

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

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

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

#### 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()`.
```

--------------------------------

### DeviceEnum.interfaces

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Retrieves a list of all device interfaces available on the system, such as network adapters or USB controllers.

```APIDOC
## DeviceEnum.interfaces

### Description
Returns a list of Interface objects representing the device interfaces of the system.

### Method
Class Method

### Parameters
None

### Response
#### Success Response
- Sequence[Interface]: The device interfaces of this system.

### Raises
- IC4Exception: An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### Device Properties Reference

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Reference for device properties, including their names, descriptions, and types.

```APIDOC
## Device Properties

### TRIGGER_OVERLAP

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

### TRIGGER_SELECTOR

*   **Description**: Selects the type of trigger to configure.
*   **Type**: Constant

### TRIGGER_SOFTWARE

*   **Description**: Generates an internal trigger. TriggerSource must be set to Software or Any.
*   **Type**: Constant

### TRIGGER_SOURCE

*   **Description**: Specifies the internal signal or physical input Line to use as the trigger source.
*   **Type**: Constant

### USER_OUTPUT_SELECTOR

*   **Description**: Selects which bit of the User Output register will be set by UserOutputValue.
*   **Type**: Constant

### USER_OUTPUT_VALUE

*   **Description**: Sets the value of the bit selected by UserOutputSelector.
*   **Type**: Constant

### USER_SET_DEFAULT

*   **Description**: Selects the feature User Set to load and make active by default when the device is reset.
*   **Type**: Constant

### USER_SET_LOAD

*   **Description**: Loads the User Set specified by UserSetSelector to the device and makes it active.
*   **Type**: Constant

### USER_SET_SAVE

*   **Description**: Save the User Set specified by UserSetSelector to the non-volatile memory of the device.
*   **Type**: Constant

### USER_SET_SELECTOR

*   **Description**: Selects the feature User Set to load, save or configure.
*   **Type**: Constant

### WIDTH

*   **Description**: Width of the image provided by the device (in pixels).
*   **Type**: Constant

### WIDTH_MAX

*   **Description**: 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.
*   **Type**: Constant

### ZOOM

*   **Description**: Changes the zoom setting of the lens.
*   **Type**: Constant

## PropertyType Enum

Enum describing available property types.

*   **INVALID**: Not a valid property type, indicates an error.
*   **INTEGER**: Integer property.
*   **FLOAT**: Float property.
*   **ENUMERATION**: Enumeration property.
*   **BOOLEAN**: Boolean property.
*   **STRING**: String property.
*   **COMMAND**: Command property.
*   **CATEGORY**: Category property.
*   **REGISTER**: Register property.
*   **PORT**: Port property.
*   **ENUMENTRY**: Enumeration entry property.

## PropertyVisibility Enum

Enum describing possible property visibilities.

*   **BEGINNER**: Beginner visibility.
*   **EXPERT**: Expert visibility.
*   **GURU**: Guru visibility.
*   **INVISIBLE**: Should not be displayed per default.

## PropertyIncrementMode Enum

An enumeration.

*   **INCREMENT**: The property used a fixed step between valid values. Use `PropInteger.increment` or `PropFloat.increment` to get the property’s step size.
*   **VALUE_SET**: 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**: 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.

## Property Class

Base class for IC4 properties. Implements basic functionality that is common for all properties.

### `_property _type`

*   **Description**: 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`

*   **Description**: Get the recommended visibility of the property.
*   **Returns**: PropertyVisibility

### `_property _name`

*   **Description**: Get the name of the property.
*   **Returns**: str
*   **Raises**: IC4Exception – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.

### `_property _description`

*   **Description**: 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`

*   **Description**: 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`

*   **Description**: Get human readable display name.
*   **Returns**: str
*   **Raises**: IC4Exception – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.

```

--------------------------------

### Grabber.device_open

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Opens a video capture device specified by an identifier or device information object. This method is essential for initiating communication with a camera.

```APIDOC
## Grabber.device_open

### Description
Opens the video capture device specified by the passed identifier or device information object.

### Method
`device_open`

### Parameters
#### Path Parameters
- **dev** (DeviceInfo | str) - Required - A identifier or device information object representing the video capture device to be opened.

### Raises
- **TypeError** – dev is neither `DeviceInfo` nor str.
- **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, user-defined name, IPV4 address or MAC address, the function fails with `ErrorCode.Ambiguous`.
```

--------------------------------

### device_open_from_state

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Restores the opened device and its settings from a memory buffer previously created by `device_save_state()`. The grabber must not have a device opened when calling this function.

```APIDOC
## device_open_from_state

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

### Parameters
#### Path Parameters
- **arr** (bytearray) - Required - 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.
```

--------------------------------

### Execute Command

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Executes a command with a known name on the device property map. If the command is an enumeration property with an entry named 'Once', that entry will be selected.

```APIDOC
## execute_command

### Description
Executes a command with a known name.

### Method
`execute_command(command_name: str) -> None`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
property_map.execute_command("AcquisitionStart")
```

### Response
#### Success Response (200)
None

#### Response Example
None

### Error Handling
Raises:
    **IC4Exception** – An error occurred. Check `IC4Exception.code` and `IC4Exception.message` for details.
```

--------------------------------

### connect_chunkdata(_image_buffer : ImageBuffer | None_)

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

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

```APIDOC
## connect_chunkdata(_image_buffer : ImageBuffer | None_)

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

### Method
connect_chunkdata

### Parameters
#### Path Parameters
- **image_buffer** (ImageBuffer | None) - Required - 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.
```

--------------------------------

### PropertyDialog

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

A dialog for managing and updating properties, with support for updating grabber information and property visibility.

```APIDOC
## PropertyDialog

### Description
A dialog for managing and updating properties, with support for updating grabber information and property visibility.

### Methods
* `PropertyDialog.update_grabber()`
* `PropertyDialog.update_property_map()`
* `PropertyDialog.set_prop_visibility()`
* `PropertyDialog.set_filter_text()`
```

--------------------------------

### DEVICE_RESET

Source: https://www.theimagingsource.com/en-us/documentation/ic4python/api-reference.html

Resets the device to its power-up state. The device must be rediscovered after reset.

```APIDOC
## DEVICE_RESET

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

### Property Type
Property
```
Tokens:
Raw