C#

Prerequisites

For Windows, there also exists a .NET version of the library.

To use it in a C# project, add a reference to the ids_peak_afl_dotnet.dll to the project.

Before starting your application, make sure that the DLL-Loader can find all required libraries. This means that ids_peak_afl_dotnet.dll, ids_peak_afl_dotnet_interface.dll, ids_peak_afl.dll and all other libraries required by ids_peak_afl.dll are located next to your application binary or that the directory where they are located is added to the DLL-Loader's search directories.

The recommended way is to add a post-build step to the .csproj file, which copies the DLLs into the application's binary directory. An example of how to achieve this can be seen for the IDS peak genericAPI and IDS peak IPL in the provided C# samples.

Alternatively, you could add their directories to the DLL-Loader's search directories by appending each directory to the environment variable Path:

• PowerShell

  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_afl.dll>"
  $env:Path="$env:Path;<Installation-Directory-Of-ids_peak_afl_dotnet.dll>"
  # Then start your application

• CMD

  set Path=%Path%;<Installation-Directory-Of-ids_peak_afl.dll>
  set Path=%Path%;<Installation-Directory-Of-ids_peak_afl_dotnet.dll>
  REM Then start your application

Usage

Using the .NET 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.

peak.afl.Library.Init();
// ... Use library here ...
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
var manager = new peak.afl.Manager(remoteNodemap);
// Create autofocus controller on the manager directly
var focusController = manager.CreateController(
    peak_afl_controllerType.PEAK_AFL_CONTROLLER_TYPE_AUTOFOCUS)
var brightnessController = manager.CreateController(
    peak_afl_controllerType.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 .NET binding works differently from the way of the 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:
  • FinishedCallback
• Supported by the controller type focus:
  • ProcessingFocusCallback
• Supported by the controller type whitebalance:
  • ProcessingWhitebalanceCallback
• Supported by the controller type brightness:
  • ProcessingBrightnessCallback
  • 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:

using peak.afl;
 
class ProcessingWhitebalanceCallback : peak.afl.ProcessingWhitebalanceCallback
{
    public ProcessingWhitebalanceCallback(Controller controller) : base(controller)
    {
    }
 
    public override void callback(peak_afl_process_data_whitebalance data)
    {
        Console.WriteLine(
            $"ProcessingWhitebalanceCallback: " +
            $"Mean (R/G/B) {data.mean_r}/{data.mean_g}/{data.mean_b} " +
            $"Component: {data.controller_component}");
    }
}
 
class FinishedCallback : peak.afl.FinishedCallback
{
    public FinishedCallback(Controller controller) : base(controller)
    {
        m_controller = controller;
    }
 
    public override void callback()
    {
        Console.WriteLine($"ControllerFinishedCallback for {m_controller.Type()}!");
    }
 
    private peak.afl.Controller m_controller;
}
 
 
class App
{
    static void Main(string[] args)
    {
        // ... Library and camera setup omitted ...
 
        // Autofeature manager, which can have multiple controllers
        var manager = new peak.afl.Manager(remoteNodemap);
        // Create autofocus controller
        var controller = manager.CreateController(
            peak_afl_controllerType.PEAK_AFL_CONTROLLER_TYPE_WHITE_BALANCE);
 
        // Only adjust once
        controller.SetMode(
            peak_afl_controller_automode.PEAK_AFL_CONTROLLER_AUTOMODE_ONCE);
 
        // Register callbacks
        // NOTE: these have to be assigned, otherwise they get destructed
        // and the callback gets removed
        var processCallback = new ProcessingWhitebalanceCallback(controller);
        var whitebalanceFinishedCallback = new FinishedCallback(controller);
 
        for (var i = 0; i < 100; i++)
        {
            try
            {
                // Wait for finished/filled buffer event
                var buffer = dataStream.WaitForFinishedBuffer(1000);
 
                // NOTE: The resulting `image` still uses the underlying
                // memory of `buffer`, so we can't queue the buffer
                // until we're done processing the image.
                var img = ids_peak_ipl_extension.BufferToImage(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.
                var isProcessing = manager.Status();
                if (!isProcessing)
                {
                    manager.Process(img);
                }
 
                img.Dispose();
 
                // Put the buffer back in the pool, so it can be filled again
                dataStream.QueueBuffer(buffer);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
 
        // ... Cleanup etc. omitted ...
    }
}

Output:

...
ProcessingWhitebalanceCallback: Mean (R/G/B) 107/47/83 Component: PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN
ProcessingWhitebalanceCallback: Mean (R/G/B) 107/47/83 Component: PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN
ProcessingWhitebalanceCallback: Mean (R/G/B) 107/47/83 Component: PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN
ProcessingWhitebalanceCallback: Mean (R/G/B) 73/73/72 Component: PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN
ControllerFinishedCallback for PEAK_AFL_CONTROLLER_TYPE_WHITE_BALANCE!

Component callbacks

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

using peak.afl;
 
class ComponentExposureFinishedCallback : peak.afl.ComponentExposureFinishedCallback
{
    public ComponentExposureFinishedCallback(Controller controller) : base(controller)
    {
    }
 
    public override void callback()
    {
        Console.WriteLine("ControllerComponentExposureFinishedCallback!");
    }
}
 
class ComponentHostGainFinishedCallback : peak.afl.ComponentHostGainFinishedCallback
{
    public ComponentHostGainFinishedCallback(Controller controller) : base(controller)
    {
    }
 
    public override void callback()
    {
        Console.WriteLine("ControllerComponentHostGainFinishedCallback!");
    }
}
 
class FinishedCallback : peak.afl.FinishedCallback
{
    public FinishedCallback(Controller controller) : base(controller)
    {
        m_controller = controller;
    }
 
    public override void callback()
    {
        Console.WriteLine($"ControllerFinishedCallback for {m_controller.Type()}!");
    }
 
    private peak.afl.Controller m_controller;
}
 
 
class App
{
    static void Main(string[] args)
    {
        // ... Library and camera setup omitted ...
 
        // Autofeature manager, which can have multiple controllers
        var manager = new peak.afl.Manager(remoteNodemap);
        // Create autofocus controller
        var controller = manager.CreateController(
            peak_afl_controllerType.PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS);
 
        controller.BrightnessComponentSetMode(
            peak_afl_controller_brightness_component.PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_EXPOSURE,
            peak_afl_controller_automode.PEAK_AFL_CONTROLLER_AUTOMODE_ONCE
        );
        controller.BrightnessComponentSetMode(
            peak_afl_controller_brightness_component.PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_HOST_GAIN,
            peak_afl_controller_automode.PEAK_AFL_CONTROLLER_AUTOMODE_ONCE
        );
 
        // Register callbacks
        // NOTE: these have to be assigned, otherwise they get destructed
        // and the callback gets removed
        var brightnessFinishedCallback = new FinishedCallback(controller);
        var exposureFinishedCallback = new ComponentExposureFinishedCallback(controller);
        var gainFinishedCallback = new ComponentHostGainFinishedCallback(controller);
 
        for (var i = 0; i < 100; i++)
        {
            try
            {
                // Wait for finished/filled buffer event
                var buffer = dataStream.WaitForFinishedBuffer(1000);
 
                // NOTE: The resulting `image` still uses the underlying
                // memory of `buffer`, so we can't queue the buffer
                // until we're done processing the image.
                var img = ids_peak_ipl_extension.BufferToImage(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.
                var isProcessing = manager.Status();
                if (!isProcessing)
                {
                    manager.Process(img);
                }
 
                img.Dispose();
 
                // Put the buffer back in the pool, so it can be filled again
                dataStream.QueueBuffer(buffer);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.Message);
            }
        }
 
        // ... Cleanup etc. omitted ...
    }
}

Output:

ControllerComponentExposureFinishedCallback!
ControllerComponentHostGainFinishedCallback!
ControllerFinishedCallback for PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS!