Automatic brightness control through exposure and gain adjustment. More...

Topics
	Skip frames
	Frame processing optimization by skipping frames to reduce computational load.
	Auto target
	Target brightness value configuration for automatic adjustment.
	Auto tolerance
	Acceptable deviation from target brightness settings.
	Auto percentile
	Percentile-based brightness analysis configuration.
	Limit
	Brightness control range limits and boundaries.
	Region of interest
	Analysis area configuration for automatic control operations.
	Callbacks
	Event notification callbacks for automatic control operations.
	Algorithm
	Brightness analysis algorithms for automatic exposure and gain control.
	Component
	Individual brightness control components for granular parameter adjustment.

Functions
PEAK_AFL_API_STATUS	peak_afl_AutoController_GetLastAutoAverage (peak_afl_controller_handle controller, uint8_t *average)
	Get the last auto average for a controller.

Detailed Description

Automatic brightness control through exposure and gain adjustment.

Auto brightness

Auto exposure

The control of the average brightness is preferably achieved by adjusting the exposure, i.e. you set the highest possible exposure time before gain is controlled. The auto exposure feature always uses the current exposure range within the active frame time. You can set separate control range limits for exposure.

Auto gain

The auto gain feature controls the supported camera gains and host gain. In digital imaging, a voltage proportional to the amount of incident light is output by the sensor. To increase image brightness and contrast, this signal can be amplified by an analog gain and offset before the digitizing process. The results of analog signal processing are usually better than the results of digital post-processing. Digital gain is applied after the digitizing process. Analog, Digital, and Combined gain are applied by the camera while Host gain is applied by the host. You can set separate control range limits for every supported gain. There are two different possibilities to control the gains.

The Auto Gain component automatically selects the first available gain from a list of supported gains.

With the second mode, the supported gains can be enabled individually. Also it is possible to set limits for every individual gain.

The supported or activated gains will be chosen and controlled in the following order:

Analog

Digital

Host

or

Combined

Host

It is only possible to run one mode. Enabling a mode automatically disables the previous one.

Note: The ipl gain must be set within the manager for the host gain to work.

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

Brightness calculation algorithm

Sets the algorithm which will be used for the auto brightness calculation.

Available Algorithms

Mean Algorithm

With mean the average value is calculated by adding all pixel values and dividing by the number of pixels.

Median Algorithm

With median the middle value is found by ordering all pixel values and selecting the middle one.

The algorithm can be changed dynamically during operation without affecting other controller settings.

Target value

Sets the target value for auto brightness control. The percentage of pixels, that must be brighter than the target value, is defined in target Percentile. The value of target value does not relate to the pixel format for the process image and can be specified in the range from 0 to 255.

Note: Increasing the target value results in brighter images, decreasing its value results in darker images. If the target value is set to a high value and percentile is set to its minimum, it behaves similar to a peak white algorithm. It is not recommended to push target value to its limits. Keep distance from the limits, i.e. use "250" instead of "255", or "5" instead of "0".

Target tolerance

The automatic control feature uses a tolerance function for stabilization. Automatic control is stopped when the actual value is within a range between (setpoint - tolerance value) and (setpoint + tolerance value). The control algorithm continues if the actual brightness value drops below (setpoint - tolerance value) or exceeds the desired target value (setpoint + tolerance value). If the tolerance value is increased, the control function will stop sooner. This can be useful in some situations.

Percentile

Defines the percentage of pixels that must be brighter than the target value. The percentile value is only used for the Median brightness calculation algorithm.

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.

Restricting the control range

With this feature it is possible to define precisely the allowed range of the exposure time or gains for automatic adjustments, when auto brightness is enabled.

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.

Auto exposure with auto gain

    peak_afl_AutoFeatureManager_Create(&hManager, nodemapHandle);
 
    // create a brightness controller within our manager
    peak_afl_controller_handle hController = 0;
    peak_afl_AutoFeatureManager_CreateController(hManager, &hController, PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS);
 
    // run the auto exposure and auto gain component in continuous mode
    peak_afl_AutoController_BrightnessComponent_Mode_Set(hController,
        PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_EXPOSURE, PEAK_AFL_CONTROLLER_AUTOMODE_CONTINUOUS);
    peak_afl_AutoController_BrightnessComponent_Mode_Set(hController,
        PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_COMBINED_GAIN, PEAK_AFL_CONTROLLER_AUTOMODE_CONTINUOUS);
 
    // submit the images
    while (acquisitionRunning)
    {
        peak_afl_AutoFeatureManager_Process(hManager, imageHandle);
    }

Auto exposure and individual auto gain control

 
    // create a brightness controller within our manager
    peak_afl_controller_handle hController = 0;
    peak_afl_AutoFeatureManager_CreateController(hManager, &hController, PEAK_AFL_CONTROLLER_TYPE_BRIGHTNESS);
 
    peak_afl_AutoController_BrightnessComponent_Mode_Set(hController, PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_EXPOSURE, PEAK_AFL_CONTROLLER_AUTOMODE_CONTINUOUS);
 
    peak_afl_AutoController_BrightnessComponent_Mode_Set(hController, PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_ANALOG_GAIN, PEAK_AFL_CONTROLLER_AUTOMODE_CONTINUOUS);
    peak_afl_AutoController_BrightnessComponent_Mode_Set(hController, PEAK_AFL_CONTROLLER_BRIGHTNESS_COMPONENT_DIGITAL_GAIN, PEAK_AFL_CONTROLLER_AUTOMODE_ONCE);
 
    // allow full range for analog but limit the host auto gain

Function Documentation

◆ peak_afl_AutoController_GetLastAutoAverage()

PEAK_AFL_API_STATUS peak_afl_AutoController_GetLastAutoAverage	(	peak_afl_controller_handle	controller,
		uint8_t *	average )

Get the last auto average for a controller.

Used by Controllers processing a mono image. This function retrieves the most recent calculated average value from the auto feature processing. The average represents the calculated brightness level from the last processed frame.

Parameters

[in]	controller	controller handle
[out]	average	autofeature average

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

Functions