IDS peak AFL v2.0.2
Loading...
Searching...
No Matches
AutoManager

Auto manager that can apply multiple auto features to an image by registering one or more controllers. More...

Functions

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Create (peak_afl_manager_handle *handle, PEAK_NODE_MAP_HANDLE nodeMapHandle)
 Create an automanager instance.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Destroy (peak_afl_manager_handle handle)
 Destroy an automanager instance.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_AddController (peak_afl_manager_handle handle, peak_afl_controller_handle controller)
 Add a controller to an auto manager instance.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_RemoveController (peak_afl_manager_handle handle, peak_afl_controller_handle controller)
 Remove a controller from an auto feature manager instance.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Process (peak_afl_manager_handle handle, PEAK_IPL_IMAGE_HANDLE imageHandle)
 Process an image through the auto feature pipeline.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_CreateController (peak_afl_manager_handle handle, peak_afl_controller_handle *controller, peak_afl_controllerType controllerType)
 Create a controller and append it to Manager.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_DestroyAllController (peak_afl_manager_handle handle)
 Destroy all controllers associated with a manager.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_DestroyController (peak_afl_manager_handle handle, peak_afl_controller_handle controller)
 Destroy a controller from a manager.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_SetGainIPL (peak_afl_manager_handle handle, PEAK_IPL_GAIN_HANDLE gainHandle)
 Set the IPL Gain for image processing.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_SetCCM (peak_afl_manager_handle handle, float *ccm, size_t ccmSize)
 Set the Color Correction Matrix (CCM)
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Status (peak_afl_manager_handle handle, peak_afl_BOOL8 *running)
 Get the processing status of an auto feature manager.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Controller_IsSupported (peak_afl_manager_handle handle, peak_afl_controllerType controllerType, peak_afl_BOOL8 *supported)
 Check if a controller type is supported by the manager.

Detailed Description

Auto manager that can apply multiple auto features to an image by registering one or more controllers.

Auto manager

An Auto manager can apply multiple auto features to an image, which is achieved by registering one or more Controllers for the manager.

The following controllers are available:

An auto manager is always related to a single camera with its Nodemap.

Processing images

For the automatic control to work, images must be transferred to the manager, which will pass them to all registered controllers.

Note
The auto feature manager process function handles the images asynchronously.

With the status function the manager can be checked if an image is currently processed.

Note
If an image is passed to the process function while the manager is processing a image it will be rejected.

Setup the auto feature manager with controllers

Example

// create auto manager
peak_afl_AutoFeatureManager_Create(&hManager, nodemapHandle);
// create a brightness controller within our manager
peak_afl_controller_handle hBrightnessController = 0;
hManager, &hBrightnessController, PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS);
// run the auto exposure and auto gain component in continuous mode
// create a whitebalance controller within our manager
peak_afl_controller_handle hWhitebalanceController = 0;
hManager, &hWhitebalanceController, PEAK_AFL_CONTROLLER_TYPE_WHITE_BALANCE);
while (acquisitionRunning)
{
// submit the images
peak_afl_AutoFeatureManager_Process(hManager, imageHandle);
}
// remove && destroy the white balance controller
peak_afl_AutoFeatureManager_RemoveController(hManager, hWhitebalanceController);
peak_afl_AutoController_Destroy(hWhitebalanceController);
// destroy all left controllers
// destroy the auto manager

Function Documentation

◆ peak_afl_AutoFeatureManager_AddController()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_AddController ( peak_afl_manager_handle handle,
peak_afl_controller_handle controller )

Add a controller to an auto manager instance.

Adds an existing automatic feature controller to the specified auto feature manager. This allows the controller to participate in coordinated image processing operations managed by the auto feature manager. Each controller can only be associated with one manager at a time, and each manager can only contain one controller of each type.

Controllers must be created separately using peak_afl_AutoController_Create() before being added to a manager. Alternatively, use the convenience function peak_afl_AutoFeatureManager_CreateController() to create and add in one operation.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[in]controllerController handle from peak_afl_AutoController_Create() that is not currently associated with any manager
Returns
PEAK_AFL_STATUS_SUCCESS Controller added successfully to the manager
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager or controller handle
PEAK_AFL_STATUS_ACCESS_DENIED Controller is already associated with another manager
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
Controllers can only be added to one manager at a time
Each manager can only contain one controller of each type
The controller becomes available for image processing once added
Remove controllers with peak_afl_AutoFeatureManager_RemoveController() before adding to another manager
See also
peak_afl_AutoController_Create()
peak_afl_AutoFeatureManager_CreateController()
peak_afl_AutoFeatureManager_RemoveController()
Since
1.0

◆ peak_afl_AutoFeatureManager_Controller_IsSupported()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Controller_IsSupported ( peak_afl_manager_handle handle,
peak_afl_controllerType controllerType,
peak_afl_BOOL8 * supported )

Check if a controller type is supported by the manager.

Determines whether the specified controller type can be created and used with this manager instance. Support may depend on the camera capabilities and the current configuration.

Parameters
[in]handleManager handle from peak_afl_AutoFeatureManager_Create()
[in]controllerTypeController type to check for support
[out]supportedPointer to receive support status:
  • PEAK_AFL_TRUE: Controller type is supported
  • PEAK_AFL_FALSE: Controller type is not supported
Returns
PEAK_AFL_STATUS_SUCCESS Operation was successful; no error occurred.
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized.
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid handle, controller type, or NULL supported pointer
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred.
Note
Check support before attempting to create controllers
Support may vary between different camera models and configurations
See also
peak_afl_AutoFeatureManager_CreateController()
peak_afl_controllerType
Since
1.11

◆ peak_afl_AutoFeatureManager_Create()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Create ( peak_afl_manager_handle * handle,
PEAK_NODE_MAP_HANDLE nodeMapHandle )

Create an automanager instance.

Creates a new auto feature manager instance that coordinates multiple automatic feature controllers for image processing and camera parameter adjustment. The manager serves as a central hub for processing images through various controllers like brightness, white balance, and autofocus.

The auto feature manager requires a valid device node map to access camera parameters and settings. The PEAK_NODE_MAP_HANDLE can be acquired by calling Handle() from std::shared_ptr<peak::core::NodeMap>. This node map provides the interface to the camera's GenICam-compliant parameter structure.

Parameters
[out]handlePointer to receive the new auto feature manager handle. Must not be NULL. The handle will be set to a valid manager instance on success.
[in]nodeMapHandleHandle to the device node map from the vision API. This provides access to camera parameters and must remain valid for the lifetime of the manager.
Returns
PEAK_AFL_STATUS_SUCCESS Manager created successfully and handle is valid
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized - call peak_afl_Init() first
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid handle pointer or node map handle
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred during creation
Note
The created manager must be destroyed with peak_afl_AutoFeatureManager_Destroy()
The node map handle must remain valid for the lifetime of the manager
Multiple managers can be created for different devices or configurations
Controllers must be added to the manager before image processing can begin
See also
peak_afl_AutoFeatureManager_Destroy()
peak_afl_AutoFeatureManager_CreateController()
peak_afl_AutoFeatureManager_AddController()
Since
1.0

◆ peak_afl_AutoFeatureManager_CreateController()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_CreateController ( peak_afl_manager_handle handle,
peak_afl_controller_handle * controller,
peak_afl_controllerType controllerType )

Create a controller and append it to Manager.

Convenience function that creates a new automatic feature controller of the specified type and immediately adds it to the manager. This combines the functionality of peak_afl_AutoController_Create() and peak_afl_AutoFeatureManager_AddController() into a single operation for simplified workflow.

Each manager can only contain one controller of each type. Attempting to add a second controller of the same type will result in an error. The created controller is automatically configured with default settings and can be further customized using the controller-specific configuration functions.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[out]controllerPointer to receive the new controller handle. Must not be NULL. The handle will be set to a valid controller instance on success.
[in]controllerTypeType of controller to create and add:
  • PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS: Automatic brightness/exposure control
  • PEAK_AFL_CONTROLLER_TYPE_WHITE_BALANCE: Automatic white balance control
  • PEAK_AFL_CONTROLLER_TYPE_AUTOFOCUS: Automatic focus control
Returns
PEAK_AFL_STATUS_SUCCESS Controller created and added successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle, controller pointer, or controller type
PEAK_AFL_STATUS_NOT_SUPPORTED The specified controller type is not supported
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
The created controller is automatically added to the manager and ready for use
Controllers are created with default configuration settings
Use controller-specific functions to customize behavior after creation
The controller will be destroyed automatically when the manager is destroyed
Check controller support with peak_afl_AutoFeatureManager_Controller_IsSupported() first
See also
peak_afl_AutoController_Create()
peak_afl_AutoFeatureManager_AddController()
peak_afl_AutoFeatureManager_Controller_IsSupported()
peak_afl_controllerType
Since
1.0

◆ peak_afl_AutoFeatureManager_Destroy()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Destroy ( peak_afl_manager_handle handle)

Destroy an automanager instance.

Destroys an auto feature manager instance and releases all associated resources. This function will automatically remove and destroy all controllers that have been added to the manager. After successful destruction, the manager handle becomes invalid and must not be used in any subsequent function calls.

Parameters
[in]handleAuto feature manager handle to destroy. Must be a valid handle obtained from peak_afl_AutoFeatureManager_Create().
Returns
PEAK_AFL_STATUS_SUCCESS Manager destroyed successfully; handle is now invalid
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle or handle is NULL
PEAK_AFL_STATUS_BUSY Manager is currently processing an image
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Warning
After this operation, the manager handle becomes invalid and must not be used
All controller handles associated with this manager also become invalid
Ensure no image processing is in progress before calling this function
Note
This function automatically destroys all controllers added to the manager
To preserve controllers for use with other managers, remove them first with peak_afl_AutoFeatureManager_RemoveController()
Check manager status with peak_afl_AutoFeatureManager_Status() before destruction
See also
peak_afl_AutoFeatureManager_Create()
peak_afl_AutoFeatureManager_Status()
peak_afl_AutoFeatureManager_RemoveController()
Since
1.0

◆ peak_afl_AutoFeatureManager_DestroyAllController()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_DestroyAllController ( peak_afl_manager_handle handle)

Destroy all controllers associated with a manager.

Removes and destroys all controllers that have been added to the specified manager. This is a convenience function for cleanup when shutting down the manager.

Parameters
[in]handleManager handle
Returns
PEAK_AFL_STATUS_SUCCESS All controllers destroyed successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Warning
After this operation, all controller handles associated with the manager become invalid
Do not use any controller handles after calling this function
Note
This function is typically called before destroying the manager
Individual controllers can be destroyed with peak_afl_AutoFeatureManager_DestroyController()
See also
peak_afl_AutoFeatureManager_DestroyController()
peak_afl_AutoFeatureManager_Destroy()
Since
1.0

◆ peak_afl_AutoFeatureManager_DestroyController()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_DestroyController ( peak_afl_manager_handle handle,
peak_afl_controller_handle controller )

Destroy a controller from a manager.

Removes and destroys a specific controller from the auto feature manager. This function combines the removal and destruction operations, making it a convenient way to permanently remove a controller from the manager. After successful destruction, the controller handle becomes invalid and must not be used in any subsequent function calls.

Parameters
[in]handleAuto feature manager handle containing the controller
[in]controllerController handle to remove and destroy. Must be a controller that was previously added to this specific manager.
Returns
PEAK_AFL_STATUS_SUCCESS Controller removed and destroyed successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager or controller handle
PEAK_AFL_STATUS_BUSY Manager is currently processing an image
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Warning
After this operation, the controller handle becomes invalid and must not be used
Ensure the manager is not processing images before destroying controllers
Note
This function both removes the controller from the manager and destroys it
To remove without destroying, use peak_afl_AutoFeatureManager_RemoveController()
Check manager status with peak_afl_AutoFeatureManager_Status() before calling
Controllers can be recreated later if needed using peak_afl_AutoFeatureManager_CreateController()
See also
peak_afl_AutoFeatureManager_RemoveController()
peak_afl_AutoFeatureManager_CreateController()
peak_afl_AutoFeatureManager_Status()
peak_afl_AutoController_Destroy()
Since
1.0

◆ peak_afl_AutoFeatureManager_Process()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Process ( peak_afl_manager_handle handle,
PEAK_IPL_IMAGE_HANDLE imageHandle )

Process an image through the auto feature pipeline.

Processes an image through all registered controllers in the auto feature manager. The image is analyzed by each controller according to their configuration and mode settings. Controllers may adjust camera parameters based on the analysis results.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[in]imageHandleImage handle from the imaging library. Obtain this handle by calling ImageBackendAccessor::BackendHandle(img) where img is a peak::ipl::Image. The image must be in a supported pixel format.
Returns
PEAK_AFL_STATUS_SUCCESS Image processed successfully
PEAK_AFL_STATUS_NOT_INITIALIZED Library not initialized - call peak_afl_Init() first
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager or image handle
PEAK_AFL_STATUS_INVALID_IMAGE_FORMAT Unsupported image pixel format
PEAK_AFL_STATUS_BUSY Manager is currently processing another image
PEAK_AFL_STATUS_ERROR Internal processing error occurred
Note
Check manager status with peak_afl_AutoFeatureManager_Status() before calling
Processing is asynchronous - use callbacks to detect completion
Only one image can be processed at a time per manager
Image must remain valid until processing completes
Controllers in OFF mode will not process the image
Example:
// Check if manager is ready for processing
if (status == PEAK_AFL_STATUS_SUCCESS && !isRunning) {
// Manager is idle, safe to process new image
status = peak_afl_AutoFeatureManager_Process(manager, imageHandle);
if (status == PEAK_AFL_STATUS_SUCCESS) {
printf("Image processing started\n");
} else if (status == PEAK_AFL_STATUS_BUSY) {
printf("Manager is busy, try again later\n");
}
}
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Process(peak_afl_manager_handle handle, PEAK_IPL_IMAGE_HANDLE imageHandle)
Process an image through the auto feature pipeline.
PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Status(peak_afl_manager_handle handle, peak_afl_BOOL8 *running)
Get the processing status of an auto feature manager.
peak_afl_status
Auto feature library status codes.
Definition peak_afl.h:383
@ PEAK_AFL_STATUS_SUCCESS
Operation completed successfully.
Definition peak_afl.h:389
@ PEAK_AFL_STATUS_BUSY
Resource is busy.
Definition peak_afl.h:437
#define PEAK_AFL_FALSE
Boolean false value.
Definition peak_afl.h:1646
uint8_t peak_afl_BOOL8
Custom 8-bit boolean type.
Definition peak_afl.h:1628
See also
peak_afl_AutoFeatureManager_Status()
peak_afl_AutoFeatureManager_CreateController()
peak_afl_AutoController_Mode_Set()
Since
1.0

◆ peak_afl_AutoFeatureManager_RemoveController()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_RemoveController ( peak_afl_manager_handle handle,
peak_afl_controller_handle controller )

Remove a controller from an auto feature manager instance.

Removes a controller from the manager without destroying the controller object. The controller can be added to another manager or destroyed separately. For a function that removes and destroys the controller in one call, see peak_afl_AutoFeatureManager_DestroyController().

Parameters
[in]handleAuto feature manager handle
[in]controllerController handle to remove from the manager
Returns
PEAK_AFL_STATUS_SUCCESS Controller removed successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager or controller handle
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
The controller object remains valid after removal
To destroy the controller, call peak_afl_AutoController_Destroy() afterward
To add to another manager, call peak_afl_AutoFeatureManager_AddController()
See also
peak_afl_AutoFeatureManager_AddController()
peak_afl_AutoFeatureManager_DestroyController()
peak_afl_AutoController_Destroy()
Since
1.0

◆ peak_afl_AutoFeatureManager_SetCCM()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_SetCCM ( peak_afl_manager_handle handle,
float * ccm,
size_t ccmSize )

Set the Color Correction Matrix (CCM)

Configures a 3x3 Color Correction Matrix (CCM) for the auto feature manager. The CCM is currently used exclusively by the Auto White Balance (AWB) controller.

Internally, the inverse of the configured CCM is computed and used by the AWB regulation algorithm so that the control loop operates on the original, uncorrected image data. Therefore, the CCM must be configured if the input image has already been processed using a Color Correction Matrix prior to Auto White Balance.

If no CCM is configured, an identity matrix is used as default.

The matrix must be invertible. If the inverse matrix cannot be computed, processing the image fails and an error is returned within the processing callback.

The matrix must be provided as a flat array of 9 float values in row-major order: [R->R, R->G, R->B, G->R, G->G, G->B, B->R, B->G, B->B], where each element represents the contribution of the input color channel to the output color channel.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[in]ccmPointer to an array of exactly 9 float values representing the 3x3 CCM. Must not be NULL.
[in]ccmSizeSize of the CCM array. Must be exactly 9 for a valid 3x3 matrix.
Returns
PEAK_AFL_STATUS_SUCCESS CCM configured successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle, NULL CCM pointer, ccmSize not equal to 9
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
The CCM is used only by the Auto White Balance controller
The inverse CCM is applied internally for AWB regulation
Changes take effect for subsequent image processing operations
Use the identity matrix [1,0,0,0,1,0,0,0,1] if no prior color correction has been applied to the input image
See also
peak_afl_AutoFeatureManager_Process()
peak_afl_AutoFeatureManager_SetGainIPL()
Since
1.8

◆ peak_afl_AutoFeatureManager_SetGainIPL()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_SetGainIPL ( peak_afl_manager_handle handle,
PEAK_IPL_GAIN_HANDLE gainHandle )

Set the IPL Gain for image processing.

Configures the Image Processing Library (IPL) gain settings for the auto feature manager. The IPL gain is applied during image processing operations and affects how controllers analyze and process images. This gain setting is separate from camera hardware gain and is used for software-based image enhancement during automatic feature processing.

The gain handle must be obtained from the imaging library using the appropriate backend accessor. To get the handle for the gain, call GainBackendAccessor::BackendHandle(gain) with gain being a peak::ipl::Gain object from the imaging library.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[in]gainHandleHandle to the IPL gain object from the imaging library. Must be a valid gain handle obtained through GainBackendAccessor.
Returns
PEAK_AFL_STATUS_SUCCESS IPL gain configured successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle or gain handle
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
The IPL gain affects software-based image processing, not camera hardware gain
The gain handle must remain valid while the manager is in use
This setting applies to all controllers within the manager
Changes take effect for subsequent image processing operations
IPL gain is applied before controllers analyze the image
See also
peak_afl_AutoFeatureManager_Process()
peak_afl_AutoFeatureManager_SetCCM()
Since
1.2

◆ peak_afl_AutoFeatureManager_Status()

PEAK_AFL_API_STATUS peak_afl_AutoFeatureManager_Status ( peak_afl_manager_handle handle,
peak_afl_BOOL8 * running )

Get the processing status of an auto feature manager.

Retrieves the current processing status of the auto feature manager to determine whether it is currently processing an image or is idle and ready to accept new image processing requests. This function is essential for coordinating image processing operations and avoiding conflicts when multiple threads or processes need to use the same manager.

Parameters
[in]handleAuto feature manager handle from peak_afl_AutoFeatureManager_Create()
[out]runningPointer to receive the manager status:
  • PEAK_AFL_TRUE: Manager is currently processing an image
  • PEAK_AFL_FALSE: Manager is idle and ready for new processing
Returns
PEAK_AFL_STATUS_SUCCESS Status retrieved successfully
PEAK_AFL_STATUS_NOT_INITIALIZED The library is not initialized
PEAK_AFL_STATUS_INVALID_PARAMETER Invalid manager handle or NULL running pointer
PEAK_AFL_STATUS_ERROR An unexpected internal error occurred
Note
Check this function before calling peak_afl_AutoFeatureManager_Process()
Only one image can be processed at a time per manager
This function is thread-safe and can be called from multiple threads
Use this for synchronization when sharing managers between threads
See also
peak_afl_AutoFeatureManager_Process()
peak_afl_AutoFeatureManager_Destroy()
Since
1.0