Basic automatic brightness controller implementation. More...

#include <peak_afl/pipeline/modules/controllers/peak_afl_basic_auto_brightness.hpp>

Inheritance diagram for BasicAutoBrightness:

Public Member Functions
	BasicAutoBrightness (peak::afl::Manager &manager, ProcessingCallback callback)
	Constructs a BasicAutoBrightness controller with the specified manager and callback.
	~BasicAutoBrightness () override=default
	Destructor for BasicAutoBrightness.
void	SetMode (ControllerMode mode) override
	Sets the operation mode for the brightness controller.
ControllerMode	GetMode () const override
	Gets the current operation mode of the brightness controller.
bool	IsRunning () const override
	Checks if the brightness controller is currently running.
void	SetAnalysisAlgorithm (BrightnessAnalysisAlgorithm algorithm)
	Sets the brightness analysis algorithm.
BrightnessAnalysisAlgorithm	GetAnalysisAlgorithm () const
	Gets the current brightness analysis algorithm.
void	SetAutoPercentile (double value)
	Sets the percentile value for brightness calculation.
double	GetAutoPercentile () const
	Gets the current percentile value for brightness calculation.
RangeD	GetAutoPercentileRange () const
	Gets the valid range for percentile values.
void	SetAutoTarget (uint32_t value)
	Sets the target brightness value.
uint32_t	GetAutoTarget () const
	Gets the current target brightness value.
peak::common::RangeU	GetAutoTargetRange () const
	Gets the valid range for target brightness values.
void	SetAutoTolerance (uint32_t value)
	Sets the tolerance value for brightness stability control.
uint32_t	GetAutoTolerance () const
	Gets the current tolerance value for brightness stability control.
peak::common::RangeU	GetAutoToleranceRange () const
	Gets the valid range for tolerance values.
void	SetSkipFrames (uint32_t value)
	Sets the number of frames to skip for performance optimization.
uint32_t	GetSkipFrames () const
	Gets the current number of frames to skip.
peak::common::RangeU	GetSkipFramesRange () const
	Gets the valid range for skip frames values.
void	SetRoi (const peak::common::Rectangle &roi)
	Sets the region of interest (ROI) for selective brightness analysis.
peak::common::Rectangle	GetRoi ()
	Gets the current region of interest (ROI) for brightness analysis.
void	SetPolicy (AutoBrightnessPolicy policy)
	Sets the brightness adjustment policy.
AutoBrightnessPolicy	GetPolicy () const
	Gets the current brightness adjustment policy.
void	ResetToDefault () override
	Resets all controller settings to their default values.
IController::FinishedCallbackHandle	RegisterFinishedCallback (const IController::FinishedCallback &callback)
	Registers a callback function to be invoked when brightness adjustment completes.
void	UnregisterFinishedCallback (IController::FinishedCallbackHandle callbackHandle)
	Unregisters a previously registered completion callback.
void	SetExposureLimit (const IntervalD &interval)
	Sets the exposure time limits for the exposure component.
IntervalD	GetExposureLimit () const
	Gets the current exposure time limits for the exposure component.
void	SetGainLimit (const IntervalD &interval)
	Sets the gain limits for the gain component.
IntervalD	GetGainLimit () const
	Gets the current gain limits for the gain component.
Public Member Functions inherited from IController
virtual	~IController ()=default
	Virtual destructor for proper cleanup of derived classes.
	IController (const IController &)=delete
	Copy constructor deleted to prevent copying.
IController &	operator= (const IController &)=delete
	Copy assignment deleted to prevent copying.
	IController (IController &&)=delete
	Move constructor deleted to prevent moving.
IController &	operator= (IController &&)=delete
	Move assignment deleted to prevent moving.

Additional Inherited Members
Public Types inherited from IController
using	FinishedCallback
	Callback function type for operation completion notifications.
using	FinishedCallbackHandle
	Handle type for managing callback registrations.
Protected Member Functions inherited from IController
peak::afl::Manager &	GetManager ()
	Gets a reference to the API manager.

Detailed Description

Basic automatic brightness controller implementation.

The BasicAutoBrightness class provides a streamlined interface for automatic brightness control. This controller offers essential brightness adjustment capabilities through exposure and gain control with simplified configuration options suitable for most standard use cases.

Key Features:

Dual adjustment mechanisms: Exposure time and gain control
Policy-based control: Configurable parameter adjustment strategies
Component architecture: Individual control over exposure and gain components
ROI support: Region-of-interest based brightness analysis
Target-based control: Automatic adjustment to achieve target brightness levels
Tolerance management: Configurable acceptable deviation from target
Callback notifications: Asynchronous operation completion events
Serialization support: Configuration persistence and restoration

Control Policies:

ExposureAndGain: Optimal brightness using both exposure and gain (recommended)
ExposureOnly: Brightness control via exposure time only (constant gain)
GainOnly: Brightness control via gain only (constant exposure)

Note: This controller requires a valid manager instance for camera communication; Component availability depends on underlying device capabilities; For advanced features like custom components use AdvancedAutoBrightness

See also: AdvancedAutoBrightness; AutoBrightnessPolicy; detail::IController; BrightnessComponent

Since: 1.8

Constructor & Destructor Documentation

◆ BasicAutoBrightness()

BasicAutoBrightness	(	peak::afl::Manager &	manager,
		ProcessingCallback	callback )

inlineexplicit

Constructs a BasicAutoBrightness controller with the specified manager and callback.

Initializes the brightness controller with exposure and gain components. The controller will automatically detect which components are supported by the device.

Parameters

manager	Reference to the API manager for device communication
callback	Processing callback function that will be invoked when brightness adjustment completes

Note: The callback will be called asynchronously when processing finishes; Only exposure and gain components are supported in this basic implementation; The callback function should be thread-safe as it may be called from different threads

See also: BrightnessComponentType

Since: 1.8

◆ ~BasicAutoBrightness()

~BasicAutoBrightness ( )

overridedefault

Destructor for BasicAutoBrightness.

Cleans up resources and ensures proper shutdown of the controller.

Since: 1.8

Member Function Documentation

◆ GetAnalysisAlgorithm()

BrightnessAnalysisAlgorithm GetAnalysisAlgorithm ( ) const

inline

Gets the current brightness analysis algorithm.

Returns: The currently configured brightness analysis algorithm

Note: This returns the algorithm setting, not the actual algorithm being used

See also: SetAnalysisAlgorithm(); BrightnessAnalysisAlgorithm

Since: 1.8

◆ GetAutoPercentile()

double GetAutoPercentile ( ) const

inline

Gets the current percentile value for brightness calculation.

Returns: The currently configured percentile value

Note: The percentile determines which part of the histogram is used for brightness analysis

See also: SetAutoPercentile(); GetAutoPercentileRange()

Since: 1.8

◆ GetAutoPercentileRange()

RangeD GetAutoPercentileRange ( ) const

inline

Gets the valid range for percentile values.

Returns: Range of valid percentile values supported by the device

Note: Use this to validate percentile values before setting them

See also: SetAutoPercentile(); RangeD

Since: 1.8

◆ GetAutoTarget()

uint32_t GetAutoTarget ( ) const

inline

Gets the current target brightness value.

Returns: The currently configured target brightness value

Note: This represents the desired brightness level for the analyzed region

See also: SetAutoTarget(); GetAutoTargetRange()

Since: 1.8

◆ GetAutoTargetRange()

peak::common::RangeU GetAutoTargetRange ( ) const

inline

Gets the valid range for target brightness values.

Returns: Range of valid target brightness values supported by the device

Note: Use this to validate target values before setting them

See also: SetAutoTarget(); peak::common::RangeU

Since: 1.8

◆ GetAutoTolerance()

uint32_t GetAutoTolerance ( ) const

inline

Gets the current tolerance value for brightness stability control.

Returns: The currently configured tolerance value

Note: This represents the acceptable deviation from the target brightness

See also: SetAutoTolerance(); GetAutoToleranceRange()

Since: 1.8

◆ GetAutoToleranceRange()

peak::common::RangeU GetAutoToleranceRange ( ) const

inline

Gets the valid range for tolerance values.

Returns: Range of valid tolerance values supported by the device

Note: Use this to validate tolerance values before setting them

See also: SetAutoTolerance(); peak::common::RangeU

Since: 1.8

◆ GetExposureLimit()

IntervalD GetExposureLimit ( ) const

inline

Gets the current exposure time limits for the exposure component.

Returns: The currently configured exposure time limits

Exceptions

peak::afl::error::NotSupportedException if exposure component is not available

Note: Returns the interval defining the minimum and maximum exposure limits

See also: SetExposureLimit(); peak::common::detail::IntervalT

Since: 1.8

◆ GetGainLimit()

IntervalD GetGainLimit ( ) const

inline

Gets the current gain limits for the gain component.

Returns: The currently configured gain limits

Exceptions

peak::afl::error::NotSupportedException if gain component is not available

Note: Returns the interval defining the minimum and maximum gain limits

See also: SetGainLimit(); peak::common::detail::IntervalT

Since: 1.8

◆ GetMode()

ControllerMode GetMode ( ) const

inlineoverridevirtual

Gets the current operation mode of the brightness controller.

The returned mode reflects the actual state of the active components:

Returns Continuous if exposure component is in Continuous mode
Otherwise returns the gain component mode
Returns Off if no components are active

Returns: Current ControllerMode based on active component states

Note: The mode reflects the actual component states, not the cached mode; Exposure component mode takes precedence over gain component mode

See also: SetMode(); ControllerMode

Since: 1.8

Implements IController.

◆ GetPolicy()

AutoBrightnessPolicy GetPolicy ( ) const

inline

Gets the current brightness adjustment policy.

Returns: The currently configured brightness adjustment policy

Note: This determines which components are used for brightness adjustment

See also: SetPolicy(); AutoBrightnessPolicy

Since: 1.8

◆ GetRoi()

peak::common::Rectangle GetRoi ( )

inline

Gets the current region of interest (ROI) for brightness analysis.

Returns: The currently configured rectangular region of interest

Note: The ROI defines the area used for brightness calculations

See also: SetRoi(); peak::common::Rectangle

Since: 1.8

◆ GetSkipFrames()

uint32_t GetSkipFrames ( ) const

inline

Gets the current number of frames to skip.

Returns: The currently configured skip frames value

Note: This affects the processing frequency and system performance

See also: SetSkipFrames(); GetSkipFramesRange()

Since: 1.8

◆ GetSkipFramesRange()

peak::common::RangeU GetSkipFramesRange ( ) const

inline

Gets the valid range for skip frames values.

Returns: Range of valid skip frames values supported by the device

Note: Use this to validate skip frames values before setting them

See also: SetSkipFrames(); peak::common::RangeU

Since: 1.8

◆ IsRunning()

bool IsRunning ( ) const

inlineoverridevirtual

Checks if the brightness controller is currently running.

Returns: True if the controller is in any active mode (not Off), false otherwise

Note: A running controller will actively adjust brightness based on scene analysis; This is equivalent to checking if GetMode() != ControllerMode::Off

See also: GetMode()

Since: 1.8

Implements IController.

◆ RegisterFinishedCallback()

IController::FinishedCallbackHandle RegisterFinishedCallback ( const IController::FinishedCallback & callback )

inline

Registers a callback function to be invoked when brightness adjustment completes.

The callback will be called asynchronously when the brightness controller finishes processing a frame and applying adjustments.

Parameters

callback The callback function to register for completion notification

Returns: Handle that can be used to unregister the callback later

Note: Multiple callbacks can be registered simultaneously; Callbacks are invoked asynchronously and should be thread-safe; The callback will be called for each processed frame

See also: UnregisterFinishedCallback(); IController::FinishedCallback

Since: 1.8

◆ ResetToDefault()

void ResetToDefault ( )

inlineoverridevirtual

Resets all controller settings to their default values.

This will restore:

Default policy (ExposureAndGain)
Default operation mode (Off)
Default algorithm settings
Default target brightness and tolerance
Default component configurations

Note: This operation cannot be undone; Default values are device-specific and may vary between implementations

See also: SetPolicy(); SetMode()

Since: 1.8

Implements IController.

◆ SetAnalysisAlgorithm()

void SetAnalysisAlgorithm ( BrightnessAnalysisAlgorithm algorithm )

inline

Sets the brightness analysis algorithm.

Determines the computational method used for brightness analysis and adjustment decisions.

Parameters

algorithm The brightness analysis algorithm to use

Note: Different algorithms may be optimized for different scene types or performance requirements; Algorithm availability depends on the device and implementation capabilities

See also: GetAnalysisAlgorithm(); BrightnessAnalysisAlgorithm

Since: 1.8

◆ SetAutoPercentile()

void SetAutoPercentile ( double value )

inline

Sets the percentile value for brightness calculation.

Determines which portion of the image histogram is used for brightness calculations, allowing for robust brightness estimation in various lighting conditions.

Parameters

value The percentile value to use (typically 0.0 to 1.0)

Note: Common percentile values: 0.5 (median), 0.9 (avoiding shadows), 0.1 (avoiding highlights); Higher percentiles focus on brighter areas, lower percentiles on darker areas

See also: GetAutoPercentile(); GetAutoPercentileRange()

Since: 1.8

◆ SetAutoTarget()

void SetAutoTarget ( uint32_t value )

inline

Sets the target brightness value.

Defines the desired brightness level that the controller will attempt to achieve through automatic adjustments.

Parameters

value The target brightness value in device-specific units

Note: Target values are typically in device-specific units (e.g., 0-255 for 8-bit); Optimal target values depend on the specific application and scene conditions

See also: GetAutoTarget(); GetAutoTargetRange()

Since: 1.8

◆ SetAutoTolerance()

void SetAutoTolerance ( uint32_t value )

inline

Sets the tolerance value for brightness stability control.

Defines the acceptable deviation from the target brightness before the controller triggers adjustment actions.

Parameters

value The tolerance value in device-specific units

Note: Smaller tolerance values provide more stable brightness but may cause oscillations; Larger tolerance values reduce adjustment frequency but may allow more brightness variation; The tolerance creates a deadband around the target to prevent continuous adjustments

See also: GetAutoTolerance(); GetAutoToleranceRange()

Since: 1.8

◆ SetExposureLimit()

void SetExposureLimit ( const IntervalD & interval )

inline

Sets the exposure time limits for the exposure component.

Defines the minimum and maximum exposure time values that the controller is allowed to use during automatic brightness adjustment.

Parameters

interval The interval defining the minimum and maximum exposure limits

Exceptions

peak::afl::error::NotSupportedException if exposure component is not available

Note: Exposure limits prevent the controller from using extreme values; Limits help maintain acceptable motion blur characteristics

See also: GetExposureLimit(); peak::common::detail::IntervalT

Since: 1.8

◆ SetGainLimit()

void SetGainLimit ( const IntervalD & interval )

inline

Sets the gain limits for the gain component.

Defines the minimum and maximum gain values that the controller is allowed to use during automatic brightness adjustment.

Parameters

interval The interval defining the minimum and maximum gain limits

Exceptions

peak::afl::error::NotSupportedException if gain component is not available

Note: Gain limits prevent the controller from using extreme values; Limits help maintain acceptable noise characteristics

See also: GetGainLimit(); peak::common::detail::IntervalT

Since: 1.8

◆ SetMode()

void SetMode ( ControllerMode mode )

inlineoverridevirtual

Sets the operation mode for the brightness controller.

The mode is applied to individual components based on the current policy:

ExposureOnly: Mode is applied to exposure component only
GainOnly: Mode is applied to gain component only
ExposureAndGain: Mode is applied to both components

Parameters

mode	The controller mode to set (Off, Auto, Manual, etc.)

Note: Setting mode to Off will disable automatic brightness adjustment; Mode changes are filtered through the current policy settings; The mode is cached and reapplied when the policy changes

See also: GetMode(); SetPolicy(); ControllerMode

Since: 1.8

Implements IController.

◆ SetPolicy()

void SetPolicy ( AutoBrightnessPolicy policy )

inline

Sets the brightness adjustment policy.

Determines which components are used for brightness adjustment:

ExposureOnly: Uses only exposure time adjustment
GainOnly: Uses only gain adjustment
ExposureAndGain: Uses both exposure and gain adjustment

Parameters

policy The brightness adjustment policy to use

Note: Policy changes immediately affect which components are active; The cached mode is reapplied when the policy changes

See also: GetPolicy(); AutoBrightnessPolicy

Since: 1.8

◆ SetRoi()

void SetRoi ( const peak::common::Rectangle & roi )

inline

Sets the region of interest (ROI) for selective brightness analysis.

Allows the controller to focus brightness analysis on specific areas of the image rather than the entire frame, providing more precise control for specific applications.

Parameters

roi	The rectangular region of interest to analyze

Note: ROI coordinates are typically normalized or in pixel coordinates; ROI can be used to focus on subject areas while ignoring background variations

See also: GetRoi(); peak::common::Rectangle

Since: 1.8

◆ SetSkipFrames()

void SetSkipFrames ( uint32_t value )

inline

Sets the number of frames to skip for performance optimization.

Skip frames allows the controller to process only every Nth frame instead of every frame, reducing computational load while maintaining brightness control.

Parameters

value The number of frames to skip (0 means process every frame)

Note: Higher skip frame values reduce CPU usage but may decrease responsiveness; A value of 0 means process every frame (maximum responsiveness); A value of 1 means process every other frame

See also: GetSkipFrames(); GetSkipFramesRange()

Since: 1.8

◆ UnregisterFinishedCallback()

void UnregisterFinishedCallback ( IController::FinishedCallbackHandle callbackHandle )

inline

Unregisters a previously registered completion callback.

Parameters

callbackHandle Handle returned from RegisterFinishedCallback() for the callback to remove

Note: Invalid handles are ignored safely; Unregistering a callback that's currently executing is safe; After unregistering, the callback will no longer be invoked

See also: RegisterFinishedCallback()

Since: 1.8

The documentation for this class was generated from the following file:

peak_afl/pipeline/modules/controllers/peak_afl_basic_auto_brightness.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BasicAutoBrightness()

◆ ~BasicAutoBrightness()

Member Function Documentation

◆ GetAnalysisAlgorithm()

◆ GetAutoPercentile()

◆ GetAutoPercentileRange()

◆ GetAutoTarget()

◆ GetAutoTargetRange()

◆ GetAutoTolerance()

◆ GetAutoToleranceRange()

◆ GetExposureLimit()

◆ GetGainLimit()

◆ GetMode()

◆ GetPolicy()

◆ GetRoi()

◆ GetSkipFrames()

◆ GetSkipFramesRange()

◆ IsRunning()

◆ RegisterFinishedCallback()

◆ ResetToDefault()

◆ SetAnalysisAlgorithm()

◆ SetAutoPercentile()

◆ SetAutoTarget()

◆ SetAutoTolerance()

◆ SetExposureLimit()

◆ SetGainLimit()

◆ SetMode()

◆ SetPolicy()

◆ SetRoi()

◆ SetSkipFrames()

◆ UnregisterFinishedCallback()