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.

There are two main concepts:

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++ API. Instead of calling e.g., RegisterFinishedCallback directly, there are base classes available that need to be inherited from, these include e.g.:

FinishedCallback
ProcessDataCallback
ComponentExposureFinishedCallback
ComponentGainFinishedCallback

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
 
 
# NOTE: Not available for all controller types e.g.,
#       not for `PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS`
class ProcessDataCallback(
        ids_peak_afl.ProcessDataCallback):
    def callback(self, focus_value: int, sharpness_value: int) -> None:
        print("ControllerProcessDataCallback: "
              f"focus({focus_value}) sharpness({sharpness_value})")
 
 
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 = ProcessDataCallback(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
        manager.Process(mono_img)
 
    # ... Cleanup etc. omitted ...

Output:

ControllerProcessDataCallback: focus(157) sharpness(132450)
ControllerProcessDataCallback: focus(97) sharpness(129569)
ControllerProcessDataCallback: focus(194) sharpness(140610)
...
FinishedCallback!

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!")
 
 
# NOTE: Not available for all controller types e.g.,
#       not for `PEAK_AFL_CONTROLLER_TYPE_AUTOFOCUS`
class ComponentExposureFinishedCallback(
        ids_peak_afl.ComponentExposureFinishedCallback):
    def callback(self) -> None:
        print("ExposureFinishedCallback!")
 
 
class ComponentGainFinishedCallback(
        ids_peak_afl.ComponentGainFinishedCallback):
    def callback(self) -> None:
        print("GainFinishedCallback!")
 
 
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 in two 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_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 = ComponentGainFinishedCallback(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
        manager.Process(mono_img)
 
    # ... Cleanup etc. omitted ...

Output:

ExposureFinishedCallback!
GainFinishedCallback!
ControllerFinishedCallback!

Note: The ProcessDataCallback is not supported for some controller types, including the brightness controller used in the example above!