C#

Prerequisites

To use IDS peak AFL in dotnet, the IDSImaging.Peak.AFL package can be installed directly from NuGet via dotnet:

dotnet add package IDSImaging.Peak.AFL

The package targets .NET Standard 2.0, making it compatible with:

• .NET Framework 4.6.1 and later
• .NET 5 and later

Note

A separate installation of the runtime setup is required. This provides the necessary Transport Layer (TL) components for communicating with the camera.

Build Instructions

The IDSImaging.Peak.AFL relies on native (unmanaged) DLLs that are distributed inside the referenced NuGet packages.

Because native binaries are involved, you must specify the target architecture via -p:Platform=<arch> when building. This ensures that your application is built for an architecture that can correctly load the required native libraries.

If no RuntimeIdentifier (-r) is specified, all available native runtimes from the packages will be copied to your build output. This would normally maximize compatibility but increase the application size. However, when the Platform parameter is specified, other architectures are not supported (except for x86 on x64).

You may optionally specify -r <rid> to reduce the size of the build output by including only the native libraries for a single runtime.

.NET (modern, SDK-style)

Required (correct architecture selection):

dotnet build -p:Platform=x64 exampleProject.csproj
dotnet run  -p:Platform=x64 --project exampleProject.csproj

Optional (smaller output):

dotnet build -r win-x64 -p:Platform=x64 exampleProject.csproj
dotnet run  -r win-x64 -p:Platform=x64 --project exampleProject.csproj

You can substitute another architecture/runtime pair if needed, e.g.:

-p:Platform=x86 (optionally with -r win-x86)
-p:Platform=x64 with -r linux-x64

.NET Framework (classic)

Use Visual Studio or build from the command line:

Restore packages first

msbuild exampleProjectFramework.csproj /t:Restore

Build for a specific platform (required for native DLLs)

msbuild exampleProjectFramework.csproj /p:Platform=x64

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.

IDSImaging.Peak.AFL.Library.Init();
// ... Use library here ...
IDSImaging.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 IDSImaging.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 IDSImaging.Peak.AFL;
 
class ProcessingWhitebalanceCallback : IDSImaging.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 : IDSImaging.Peak.AFL.FinishedCallback
{
    public FinishedCallback(Controller controller) : base(controller)
    {
        m_controller = controller;
    }
 
    public override void callback()
    {
        Console.WriteLine($"ControllerFinishedCallback for {m_controller.Type()}!");
    }
 
    private IDSImaging.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 IDSImaging.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 = IPLExtension.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 IDSImaging.Peak.AFL;
 
class ComponentExposureFinishedCallback : IDSImaging.Peak.AFL.ComponentExposureFinishedCallback
{
    public ComponentExposureFinishedCallback(Controller controller) : base(controller)
    {
    }
 
    public override void callback()
    {
        Console.WriteLine("ControllerComponentExposureFinishedCallback!");
    }
}
 
class ComponentHostGainFinishedCallback : IDSImaging.Peak.AFL.ComponentHostGainFinishedCallback
{
    public ComponentHostGainFinishedCallback(Controller controller) : base(controller)
    {
    }
 
    public override void callback()
    {
        Console.WriteLine("ControllerComponentHostGainFinishedCallback!");
    }
}
 
class FinishedCallback : IDSImaging.Peak.AFL.FinishedCallback
{
    public FinishedCallback(Controller controller) : base(controller)
    {
        m_controller = controller;
    }
 
    public override void callback()
    {
        Console.WriteLine($"ControllerFinishedCallback for {m_controller.Type()}!");
    }
 
    private IDSImaging.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 IDSImaging.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 = IPLExtension.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!