Python

Prerequisites

To use IDS peak AFL in Python, the ids_peak_afl package can be installed directly from PyPI via pip, Python's package manager:

pip install ids_peak_afl

Note

To be able to install the Python wheels on Linux, pip must be installed in version 20.3 or greater. Otherwise pip will detect the wheel as "not supported on this platform".

Offline Installation

In case of an offline installation, there is a separate Python wheel for each supported Python version and CPU architecture. A Python wheel is a package file (with .whl file ending) which can be installed via pip, Python's package manager. Just call pip install <Path-To-Python-Wheel> to install your chosen Python wheel. The respective .whl file can be obtained from the package's PyPI project page under Download files.

While pip will inform you about missing packages and their version requirements, contrary to the online installation, you need to manually resolve dependencies and respect the correct order of installation.

Import

To finally use IDS peak AFL in your Python script, just add import ids_peak_afl.ids_peak_afl or import ids_peak_afl.ids_peak_afl as some_alias at the top of your Python script. The latter should be preferred.

Usage

Using the Python binding is very similar to how you would use the C++ API of the IDS peak AFL.

Before using any library functions, ensure the library is initialized. Once you have finished working with the library, close the library. The init and exit functions maintain a reference count of their calls. For each init call, you must make a corresponding exit call to properly release resources.

ids_peak_afl.Library.Init()
# ... Use library here ...
ids_peak_afl.Library.Exit()

There are two main concepts:

1. Manager
2. Controller

A Manager can apply multiple auto features based on an image, which is achieved by registering one or more Controllers on the manager.

# Auto feature manager, which can have multiple controllers
manager = ids_peak_afl.Manager(remote_nodemap)
# Create autofocus controller on the manager directly
focus_controller = manager.CreateController(
    ids_peak_afl.PEAK_AFL_CONTROLLER_TYPE_AUTOFOCUS)
brightness_controller = manager.CreateController(
    ids_peak_afl.PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS)

The auto features of each individual controller get applied by passing an image to the Manager's Process function.

# Process the image in the autofeature manager, which will
# apply all the actions of associated controllers.
manager.Process(image)

Warning

Some controllers are dependent on the time stamp information that is available on the IDS peak IPL Image. If you're creating such an image yourself, instead of e.g., using the provided BufferToImage function, you have to take care to pass the time stamp to the image's constructor.

Callbacks

Registering Callbacks in the Python bindings works differently from the way of the C/C++ API (see Callbacks). Instead of calling e.g., RegisterFinishedCallback directly, there are base classes available that need to be inherited from, these include e.g.:

• Supported by all controller types:
  • ProcessingCallback
  • FinishedCallback
• Supported by the controller type brightness:
  • ComponentExposureFinishedCallback
  • ComponentAnalogGainFinishedCallback
  • ComponentDigitalGainFinishedCallback
  • ComponentCombinedGainFinishedCallback
  • ComponentHostGainFinishedCallback

Note

For general information on callbacks, refer to Callbacks.

To create a custom callback the callback method needs to be overridden. Attaching that callback to a Controller is done by passing the Controller instance to the constructor of the Callback class.

An example usage could look like as follows:

from ids_peak import ids_peak, ids_peak_ipl_extension
from ids_peak_ipl import ids_peak_ipl
from ids_peak_afl import ids_peak_afl
 
 
class ProcessingCallback(
        ids_peak_afl.ProcessingCallback):
    def callback(self, process_data) -> None:
        print("ProcessingCallback: "
              f"Controller Status {process_data.controller_status} "
              f"Controller Type {process_data.controller_type}")
        if isinstance(process_data,
                      ids_peak_afl.peak_afl_process_data_brightness):
            print("Brightness")
            print(f"\tMean: {process_data.mean}")
            print(f"\tController Component: {process_data.controller_component}")
        elif isinstance(process_data,
                        ids_peak_afl.peak_afl_process_data_whitebalance):
            print("Whitebalance")
            print("\tMean (R/G/B): "
                  f"{process_data.mean_r}/{process_data.mean_g}/"
                  f"{process_data.mean_b}")
            print("\tController Component: "
                  f"{process_data.controller_component}")
        elif isinstance(process_data,
                        ids_peak_afl.peak_afl_process_data_focus):
            print("Focus")
            print(f"\tFocus {process_data.focus_value} "
                  f"Sharpness {process_data.sharpness_value}")
        else:
            raise RuntimeError("Unknown process_data type!")
 
 
class FinishedCallback(
        ids_peak_afl.FinishedCallback):
    def callback(self) -> None:
        print("ControllerFinishedCallback!")
 
 
def main():
    # ... Library and camera setup omitted ...
 
    # Autofeature manager, which can have multiple controllers
    manager = ids_peak_afl.Manager(remote_nodemap)
    # Create autofocus controller
    controller = manager.CreateController(
        ids_peak_afl.PEAK_AFL_CONTROLLER_TYPE_AUTOFOCUS)
 
    # Register callbacks
    # NOTE: these have to be assigned, otherwise they get destructed
    # and the callback gets removed
    finished = FinishedCallback(controller)
    processing = ProcessingCallback(controller)
 
    for _ in range(100):
        # Wait for finished/filled buffer event
        buffer = data_stream.WaitForFinishedBuffer(1000)
        img = ids_peak_ipl_extension.BufferToImage(buffer)
 
        # NOTE: If performance is a concern, then `ids_peak_ipl.ImageConverter`
        #       should be preferred.
        mono_img = img.ConvertTo(ids_peak_ipl.PixelFormatName_Mono8)
        # Put the buffer back in the pool, so it can be filled again
        # NOTE: `ConvertTo` will make a copy, so it is fine to queue
        #       the buffer immediately after.
        data_stream.QueueBuffer(buffer)
 
        # Process the image in the autofeature manager, which will
        # apply all the actions of associated controllers.
        # Skip processing if another image is still being processed.
        isProcessing = manager.Status()
        if not isProcessing:
            manager.Process(mono_img)
 
    # ... Cleanup etc. omitted ...

Output:

ProcessingCallback: Controller Status 7 Controller Type 5
Focus
        Focus 0 Sharpness 0
ProcessingCallback: Controller Status 2 Controller Type 5
Focus
        Focus 632 Sharpness 13502985
ProcessingCallback: Controller Status 7 Controller Type 5
Focus
        Focus 632 Sharpness 13502985
ProcessingCallback: Controller Status 7 Controller Type 5
Focus
        Focus 632 Sharpness 13502985
...
ControllerFinishedCallback!

Component callbacks

For Controllers of type e.g, brightness, there exist additional callbacks that can be registered for the individual components of the controller:

from ids_peak import ids_peak, ids_peak_ipl_extension
from ids_peak_ipl import ids_peak_ipl
from ids_peak_afl import ids_peak_afl
 
 
class FinishedCallback(
        ids_peak_afl.FinishedCallback):
    def callback(self) -> None:
        print("ControllerFinishedCallback!")
 
 
class ComponentExposureFinishedCallback(
        ids_peak_afl.ComponentExposureFinishedCallback):
    def callback(self) -> None:
        print("ExposureFinishedCallback!")
 
 
class ComponentHostGainFinishedCallback(
        ids_peak_afl.ComponentHostGainFinishedCallback):
    def callback(self) -> None:
        print("HostGainFinishedCallback!")
 
 
def main():
    # ... Library and camera setup omitted ...
 
    # Autofeature manager, which can have multiple controllers
    manager = ids_peak_afl.Manager(remote_nodemap)
    # Create autofocus controller
    controller = manager.CreateController(
        ids_peak_afl.PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS)
 
    # Auto brightness mode is split up into multiple components
    # so you can't use the regular controller.SetMode etc.
    # NOTE: mode is reset to off automatically after the operation finishes
    # when using PEAK_AFL_CONTROLLER_AUTOMODE_ONCE
    controller.BrightnessComponentSetMode(
        ids_peak_afl.PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_EXPOSURE,
        ids_peak_afl.PEAK_AFL_CONTROLLER_AUTOMODE_ONCE,
    )
    controller.BrightnessComponentSetMode(
        ids_peak_afl.PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_HOST_GAIN,
        ids_peak_afl.PEAK_AFL_CONTROLLER_AUTOMODE_ONCE,
    )
 
    # Register callbacks
    # NOTE: these have to be assigned, otherwise they get destructed
    # and the callback gets removed
    finished = FinishedCallback(controller)
    exposureFinished = ComponentExposureFinishedCallback(controller)
    gainFinished = ComponentHostGainFinishedCallback(controller)
 
    for _ in range(100):
        # Wait for finished/filled buffer event
        buffer = data_stream.WaitForFinishedBuffer(1000)
        img = ids_peak_ipl_extension.BufferToImage(buffer)
 
        # NOTE: If performance is a concern, then `ids_peak_ipl.ImageConverter`
        #       should be preferred.
        mono_img = img.ConvertTo(ids_peak_ipl.PixelFormatName_Mono8)
        # Put the buffer back in the pool, so it can be filled again
        # NOTE: `ConvertTo` will make a copy, so it is fine to queue
        #       the buffer immediately after.
        data_stream.QueueBuffer(buffer)
 
        # Process the image in the autofeature manager, which will
        # apply all the actions of associated controllers.
        # Skip processing if another image is still being processed.
        isProcessing = manager.Status()
        if not isProcessing:
            manager.Process(mono_img)
 
    # ... Cleanup etc. omitted ...

Output:

ExposureFinishedCallback!
HostGainFinishedCallback!
ControllerFinishedCallback!