Topics
	Skip frames

	Auto target

	Auto tolerance

	Auto percentile

	Limit

	Region of interest

	Callbacks

	Algorithm

	Component

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

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. With mean the average value is found by adding all pixel values and dividing by the number of pixel. With median the middle number is found by ordering all pixel and picking the middle.

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. This parameter strongly influences the control speed. Choosing small values can destabilize the automatic control.

Note: For higher frame rates, a larger value should be used for the Skip frames parameter. This reduces the number of automatic adjustments done by the camera.

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.

Note: If a ROI does not fit into the processed image dimension 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 all values must be set to 0.

Callback

It is possible to be informed for specific events via callbacks. The following callbacks are available:

Finished will be called when the controller has reached the target value.
Processing will be called when the controller has processed an image.

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_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.

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