Automatic white balance control for color correction and temperature adjustment. More...

Topics
	Skip frames
	Frame processing optimization by skipping frames to reduce computational load.
	Region of interest
	Analysis area configuration for automatic control operations.
	Mode
	Operation mode configuration for automatic control functionality.
	Callbacks
	Event notification callbacks for automatic control operations.

Enumerations
enum	peak_afl_controller_whitebalance_component { PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_INVALID , PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_ANALOG_GAIN , PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN , PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_COMBINED_GAIN , PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_HOST_GAIN }
	White balance control components. More...

Functions
PEAK_AFL_API_STATUS	peak_afl_AutoController_GetLastAutoAverages (peak_afl_controller_handle controller, uint8_t averageRed, uint8_t averageGreen, uint8_t *averageBlue)
	Get the last auto average for a controller.

Detailed Description

Automatic white balance control for color correction and temperature adjustment.

Auto white balance

Depending on the light source, light can have different color temperatures so that the images may have a color cast. At low color temperatures (e.g. light from incandescent lamps), the white content shifts towards a red hue. At high color temperatures (e.g. light from fluorescent lamps), the white content shifts a blue hue.

The white balance control feature uses the RGB gain settings of the camera to correct the white level. This is achieved by adjusting the gain controls until the red or blue channel matches the average brightness of the green channel.

Enabling and automatically disabling the control function

For ongoing adaptations the Continuous mode has to be used so that it responds to deviations from the target value. To disable the control functionality automatically once the target value has been reached, (approximately) use the Once mode.

Configuring the control functions

Skip frames

The Skip frames setting defines how many frames should be skipped between processing operations. This parameter strongly influences both control speed and system stability.

How Skip Frames Works

When skip frames is set to N, the controller will:

Process frame 1
Skip frames 2, 3, ..., N+1
Process frame N+2
Skip frames N+3, N+4, ..., 2N+2
And so on...

Example: Skip frames = 3 means process every 4th frame (process 1, skip 3, process 1, skip 3...)

Dynamic Adjustment

Skip frames can be adjusted dynamically based on conditions:

Note: For higher frame rates, a larger value should be used for the Skip frames parameter. This reduces the number of automatic adjustments and improves system stability.; Different controllers can have different skip frame settings optimized for their specific requirements.

Region of interest (ROI)

If a smaller part of the image should be processed, a region of interest (ROI) can be set. The ROI allows focusing the auto feature analysis on specific areas while ignoring irrelevant parts of the image.

Note: If a ROI does not fit into the processed image dimensions, the processing callback is called with corresponding error status.

Note: The ROI for automatic control is set to the full size of the processed image by default.

Note: To reset a ROI to full image, all values must be set to 0, which will automatically use the complete image area.

Callback

It is possible to be informed for specific events via callbacks. Callbacks provide real-time feedback about controller operations and enable responsive application behavior.

Available Callback Types

Finished Callback

Finished will be called when the controller has completed its operation and reached the target value.

When called:

Controller completes adjustment in Once mode
Target value is reached within tolerance
Operation is cancelled or encounters an error

Processing Callback

Processing will be called during image processing to provide real-time feedback.

When called:

Each time an image is processed
Provides intermediate calculation results
Available in all controller modes

Callback Threading Considerations

Important Threading Notes:

Callbacks may be invoked from worker threads
Avoid blocking operations in callbacks
Keep callback execution time minimal

Note: The Finished callback will only be called when the controller runs in Once mode.

Examples

Note: For the automatic host control to work, the frames must be transferred to the manager. To reduce and simplify the sample code, the examples do not check the return values.

    peak_afl_AutoFeatureManager_Create(&hManager, nodemapHandle);
 
    // create a whitebalance controller within our manager
    peak_afl_controller_handle hController = 0;
    peak_afl_AutoFeatureManager_CreateController(hManager, &hController, PEAK_AFL_CONTROLLER_TYPE_WHITE_BALANCE);
 
    // run in continuous mode
    peak_afl_AutoController_Mode_Set(hController, PEAK_AFL_CONTROLLER_AUTOMODE_CONTINUOUS);
 
    // submit the images
    while(acquisitionRunning)
    {
        peak_afl_AutoFeatureManager_Process(hManager, imageHandle);
    }

Enumeration Type Documentation

◆ peak_afl_controller_whitebalance_component

enum peak_afl_controller_whitebalance_component

White balance control components.

Defines the different camera parameters that can be adjusted by the white balance controller to achieve accurate color reproduction. Each component affects color balance differently and may have different performance characteristics.

Note: Component availability depends on camera capabilities

See also: peak_afl_AutoController_WhiteBalanceComponent_IsSupported()

Enumerator
PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_INVALID	Invalid or uninitialized component. This value indicates an invalid component type and should not be used for component operations.
PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_ANALOG_GAIN	Analog gain white balance control. Adjusts individual color channel analog gains before digitization. Provides the best signal-to-noise ratio for white balance correction but may have limited adjustment range. Note Best noise performance, preferred when available
PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_DIGITAL_GAIN	Digital gain white balance control. Adjusts individual color channel gains in the digital domain after sensor readout. Wider adjustment range than analog gain but may amplify noise, especially in darker regions. Note Wider range but may amplify noise
PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_COMBINED_GAIN	Combined analog and digital gain control (combined) Automatically manages both analog and digital gains for each color channel to achieve optimal white balance with best signal-to-noise ratio. Uses analog gain first, then digital gain for extended range. Note Recommended for best overall performance
PEAK_AFL_CONTROLLER_WHITEBALANCE_COMPONENT_HOST_GAIN	Host-based software white balance. Applies white balance correction in software on the host computer after image acquisition. Provides unlimited adjustment range but processes images after capture. Note Applied in software, may affect performance

Function Documentation

◆ peak_afl_AutoController_GetLastAutoAverages()

PEAK_AFL_API_STATUS peak_afl_AutoController_GetLastAutoAverages	(	peak_afl_controller_handle	controller,
		uint8_t *	averageRed,
		uint8_t *	averageGreen,
		uint8_t *	averageBlue )

Get the last auto average for a controller.

Used by Controllers processing a color image. This function retrieves the most recent calculated average values for each color channel (RGB) from the auto feature processing. These averages represent the calculated brightness levels for each color channel from the last processed frame.

Parameters

[in]	controller	controller handle
[out]	averageRed	autofeature average red channel
[out]	averageGreen	autofeature average green channel
[out]	averageBlue	autofeature average blue channel

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 The argument is invalid.; PEAK_AFL_STATUS_NOT_SUPPORTED The function is not supported.; PEAK_AFL_STATUS_ERROR An unexpected internal error occurred.

Since: 1.0

Topics

Enumerations

Functions