Advanced automatic brightness controller with comprehensive feature set. More...

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

Inheritance diagram for AdvancedAutoBrightness:

Public Member Functions
	AdvancedAutoBrightness (peak::afl::Manager &manager, ProcessingCallback callback)
	Constructs an AdvancedAutoBrightness controller with the specified manager and callback.
	~AdvancedAutoBrightness () override=default
	Destructor for AdvancedAutoBrightness.
std::string	GetName () const override
	Gets the name identifier for this controller.
void	Serialize (peak::common::serialization::IArchive &archive) const override
	Serializes the current controller state and configuration to an archive.
void	Deserialize (const peak::common::serialization::IArchive &archive) override
	Deserializes controller state and configuration from an archive.
ControllerType	GetType () const override
	Gets the controller type identifier.
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.
features::SkipFrames &	SkipFrames ()
	Gets access to the skip frames feature.
features::AutoTarget &	AutoTarget ()
	Gets access to the auto target feature for brightness target configuration.
features::AutoTolerance &	AutoTolerance ()
	Gets access to the auto tolerance feature for brightness stability control.
features::AutoPercentile &	AutoPercentile ()
	Gets access to the auto percentile feature used for automatic brightness adjustment.
features::Roi &	Roi ()
	Gets access to the region of interest (ROI) feature for selective brightness analysis.
features::BrightnessAlgorithm &	AnalysisAlgorithm ()
	Gets access to the brightness algorithm feature for algorithm selection.
BrightnessComponent &	Exposure () const
	Gets access to the exposure component for exposure time control.
bool	HasExposure () const
	Checks if the exposure component is available on the current device.
BrightnessComponent &	AnalogGain () const
	Gets access to the analog gain component for sensor-level gain control.
bool	HasAnalogGain () const
	Checks if the analog gain component is available on the current device.
BrightnessComponent &	DigitalGain () const
	Gets access to the digital gain component for post-processing gain control.
bool	HasDigitalGain () const
	Checks if the digital gain component is available on the current device.
BrightnessComponent &	CombinedGain () const
	Gets access to the combined gain component for unified gain control.
bool	HasCombinedGain () const
	Checks if the combined gain component is available on the current device.
BrightnessComponent &	HostGain () const
	Gets access to the host gain component for software-based gain control.
bool	HasHostGain () const
	Checks if the host gain component is available on the current device.
std::vector< BrightnessComponent * >	GetComponents () const
	Gets a vector of all available brightness components.
BrightnessComponent *	GetComponent (BrightnessComponentType componentType) const
	Gets a specific brightness component by type.
void	ResetToDefault () override
	Resets all controller settings and components 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.
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

Advanced automatic brightness controller with comprehensive feature set.

The AdvancedAutoBrightness class provides a sophisticated and highly configurable interface for automatic brightness control. This controller offers the complete feature set with granular control over all brightness adjustment mechanisms and algorithmic options.

Advanced Features:

Multiple gain types: Analog, digital, combined, and host gain control
Algorithmic flexibility: Configurable brightness analysis algorithms
ROI support: Region-of-interest configurations
Granular limits: Individual limit control for each brightness component
Component-level control: Fine-grained management of individual brightness components
Callback architecture: Comprehensive event notification system
Full serialization: Complete configuration state management

Brightness Components:

Exposure Component: Sensor integration time control
Analog Gain Component: Hardware amplification before digitization
Digital Gain Component: Post-digitization amplification
Combined Gain Component: Unified analog and digital gain management
Host Gain Component: Software-based gain processing

Algorithm Support:

Brightness Analysis: Mean, median
Percentile Calculation: Configurable histogram percentile analysis
Target Achievement: Sophisticated convergence algorithms
Tolerance Management: Advanced stability and hysteresis control

Note: This controller requires a valid manager instance for camera communication; Component availability depends on underlying device capabilities; For simplified usage, consider BasicAutoBrightness instead

See also: BasicAutoBrightness; BrightnessComponent; detail::GenericAutoBrightness; detail::IController

Since: 1.8

Constructor & Destructor Documentation

◆ AdvancedAutoBrightness()

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

inlineexplicit

Constructs an AdvancedAutoBrightness controller with the specified manager and callback.

Initializes the brightness controller with all available brightness components including exposure, analog gain, digital gain, combined gain, and host gain. 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 (host gain)

Note: The callback will be called asynchronously when processing finishes; Component initialization depends on device capabilities

See also: BrightnessComponentType

Since: 1.8

◆ ~AdvancedAutoBrightness()

~AdvancedAutoBrightness ( )

overridedefault

Destructor for AdvancedAutoBrightness.

Cleans up resources and ensures proper shutdown of the controller.

Member Function Documentation

◆ AnalogGain()

BrightnessComponent & AnalogGain ( ) const

inline

Gets access to the analog gain component for sensor-level gain control.

The analog gain component controls sensor-level amplification before digitization. This provides brightness increase with better noise characteristics than digital gain.

Returns: Reference to the analog gain BrightnessComponent

Exceptions

peak::afl::error::NotSupportedException if analog gain component is not supported by the device

Note: Check HasAnalogGain() before calling to avoid exceptions; Analog gain affects noise characteristics less than digital gain; Higher analog gain values may introduce some noise but less than digital gain

See also: HasAnalogGain(); BrightnessComponent

Since: 1.8

◆ AnalysisAlgorithm()

features::BrightnessAlgorithm & AnalysisAlgorithm ( )

inline

Gets access to the brightness algorithm feature for algorithm selection.

Brightness algorithm determines the computational method used for brightness analysis and adjustment decisions.

Returns: Reference to the BrightnessAlgorithm feature for configuration

Note: Different algorithms may be optimized for different scene types or performance requirements; Some algorithms may be better suited for specific lighting conditions or subject types

See also: features::BrightnessAlgorithm

Since: 1.8

◆ AutoPercentile()

features::AutoPercentile & AutoPercentile ( )

inline

Gets access to the auto percentile feature used for automatic brightness adjustment.

Determines the pixel intensity percentile to consider when adjusting exposure or gain. A higher percentile emphasizes brighter regions, while a lower percentile focuses on mid-tones or shadows.

Typical range: 0-100.

Returns: Reference to the AutoPercentile feature for configuration

See also: features::AutoPercentile

Since: 1.8

◆ AutoTarget()

features::AutoTarget & AutoTarget ( )

inline

Gets access to the auto target feature for brightness target configuration.

Auto target defines the desired brightness level that the controller will attempt to achieve through automatic adjustments.

Returns: Reference to the AutoTarget feature for configuration

Note: Target values are typically normalized (0 to 255) or in device-specific units; Optimal target values depend on the specific application and scene conditions; The target represents the desired brightness level of the analyzed region

See also: features::AutoTarget

Since: 1.8

◆ AutoTolerance()

features::AutoTolerance & AutoTolerance ( )

inline

Gets access to the auto tolerance feature for brightness stability control.

Auto tolerance defines the acceptable deviation from the target brightness before the controller triggers adjustment actions.

Returns: Reference to the AutoTolerance feature for configuration

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: features::AutoTolerance

Since: 1.8

◆ CombinedGain()

BrightnessComponent & CombinedGain ( ) const

inline

Gets access to the combined gain component for unified gain control.

The combined gain component provides a unified interface for both analog and digital gain control, automatically selecting the optimal combination.

Returns: Reference to the combined gain BrightnessComponent

Exceptions

peak::afl::error::NotSupportedException if combined gain component is not supported by the device

Note: Check HasCombinedGain() before calling to avoid exceptions; Combined gain automatically optimizes between analog and digital gain; The controller will prefer analog gain over digital gain when possible

See also: HasCombinedGain(); BrightnessComponent

Since: 1.8

◆ Deserialize()

void Deserialize ( const peak::common::serialization::IArchive & archive )

inlineoverridevirtual

Deserializes controller state and configuration from an archive.

Restores all controller settings and component configurations from previously serialized data.

Parameters

archive Reference to the archive containing the serialized data

Note: This will overwrite current controller settings; Component availability is validated during deserialization; If a component is not available, its settings will be ignored

See also: Serialize()

Since: 1.8

Implements ISerializable.

◆ DigitalGain()

BrightnessComponent & DigitalGain ( ) const

inline

Gets access to the digital gain component for post-processing gain control.

The digital gain component controls post-digitization amplification. This provides brightness increase but may introduce more noise than analog methods.

Returns: Reference to the digital gain BrightnessComponent

Exceptions

peak::afl::error::NotSupportedException if digital gain component is not supported by the device

Note: Check HasDigitalGain() before calling to avoid exceptions; Digital gain may introduce more noise than exposure or analog gain; Digital gain is applied after analog-to-digital conversion

See also: HasDigitalGain(); BrightnessComponent

Since: 1.8

◆ Exposure()

BrightnessComponent & Exposure ( ) const

inline

Gets access to the exposure component for exposure time control.

The exposure component controls camera exposure time to adjust image brightness. This is typically the primary method for brightness control as it doesn't introduce noise.

Returns: Reference to the exposure BrightnessComponent

Exceptions

peak::afl::error::NotSupportedException if exposure component is not supported by the device

Note: Check HasExposure() before calling to avoid exceptions

See also: HasExposure(); BrightnessComponent

Since: 1.8

◆ GetComponent()

BrightnessComponent * GetComponent ( BrightnessComponentType componentType ) const

inline

Gets a specific brightness component by type.

Parameters

componentType The type of brightness component to retrieve

Returns: Pointer to the requested BrightnessComponent, or nullptr if not available

Note: Check for nullptr return value before using the component; This provides type-safe access to specific component types; Null return indicates the component is not supported on this device

See also: GetComponents(); BrightnessComponentType; BrightnessComponent

Since: 1.8

◆ GetComponents()

std::vector< BrightnessComponent * > GetComponents ( ) const

inline

Gets a vector of all available brightness components.

Returns pointers to all brightness components that are supported and available on the current device configuration.

Returns: Vector of pointers to available BrightnessComponent instances

Note: The returned vector only contains components that are actually available; Use this for iterating over all available brightness adjustment methods; The order of components in the vector is not guaranteed

See also: GetComponent(); BrightnessComponent

Since: 1.8

◆ GetMode()

ControllerMode GetMode ( ) const

inlineoverridevirtual

Gets the current operation mode of the brightness controller.

Returns: Current ControllerMode of the brightness controller

Note: Use this to check if automatic brightness adjustment is active

See also: SetMode(); ControllerMode

Since: 1.8

Implements IController.

◆ GetName()

std::string GetName ( ) const

inlineoverridevirtual

Gets the name identifier for this controller.

Returns: String "AdvancedAutoBrightness" identifying this controller type

Note: This is used for type identification in serialization and factory patterns; Distinguishes this from the basic auto features implementation

Since: 1.8

Implements IController.

◆ GetType()

ControllerType GetType ( ) const

inlineoverridevirtual

Gets the controller type identifier.

Returns: ControllerType::Brightness identifying this as a brightness controller

Note: Used for type identification and controller management; This enables runtime type checking and proper controller categorization

Since: 1.8

Implements IController.

◆ HasAnalogGain()

bool HasAnalogGain ( ) const

inline

Checks if the analog gain component is available on the current device.

Returns: True if analog gain control is supported, false otherwise

Note: Use this before calling AnalogGain() to avoid exceptions; Availability depends on the underlying device capabilities

See also: AnalogGain()

Since: 1.8

◆ HasCombinedGain()

bool HasCombinedGain ( ) const

inline

Checks if the combined gain component is available on the current device.

Returns: True if combined gain control is supported, false otherwise

Note: Use this before calling CombinedGain() to avoid exceptions; Availability depends on the underlying device capabilities

See also: CombinedGain()

Since: 1.8

◆ HasDigitalGain()

bool HasDigitalGain ( ) const

inline

Checks if the digital gain component is available on the current device.

Returns: True if digital gain control is supported, false otherwise

Note: Use this before calling DigitalGain() to avoid exceptions; Availability depends on the underlying device capabilities

See also: DigitalGain()

Since: 1.8

◆ HasExposure()

bool HasExposure ( ) const

inline

Checks if the exposure component is available on the current device.

Returns: True if exposure control is supported, false otherwise

Note: Use this before calling Exposure() to avoid exceptions; Availability depends on the underlying device capabilities

See also: Exposure()

Since: 1.8

◆ HasHostGain()

bool HasHostGain ( ) const

inline

Checks if the host gain component is available on the current device.

Returns: True if host gain control is supported, false otherwise

Note: Use this before calling HostGain() to avoid exceptions; Availability depends on the underlying device capabilities

See also: HostGain()

Since: 1.8

◆ HostGain()

BrightnessComponent & HostGain ( ) const

inline

Gets access to the host gain component for software-based gain control.

The host gain component controls software-based gain adjustment performed on the host system after image acquisition.

Returns: Reference to the host gain BrightnessComponent

Exceptions

peak::afl::error::NotSupportedException if host gain component is not supported by the device

Note: Check HasHostGain() before calling to avoid exceptions; Host gain processing may impact performance and introduce processing delays; Host gain is applied in software after image transfer from the device

See also: HasHostGain(); BrightnessComponent

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

See also: UnregisterFinishedCallback(); IController::FinishedCallback

Since: 1.8

◆ ResetToDefault()

void ResetToDefault ( )

inlineoverridevirtual

Resets all controller settings and components to their default values.

This will restore:

Default operation mode (typically Off)
Default algorithm settings
Default target brightness and tolerance
Default component configurations
Default ROI and percentile settings
Default feature configurations

Note: This operation cannot be undone; Default values are device-specific and may vary between implementations; Component states are reset but availability is not changed

See also: SetMode()

Since: 1.8

Implements IController.

◆ Roi()

features::Roi & Roi ( )

inline

Gets access to the region of interest (ROI) feature for selective brightness analysis.

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

Returns: Reference to the Roi feature for configuration

Note: ROI can be used to focus on subject areas while ignoring background variations

See also: features::Roi

Since: 1.8

◆ Serialize()

void Serialize ( peak::common::serialization::IArchive & archive ) const

inlineoverridevirtual

Serializes the current controller state and configuration to an archive.

Saves all controller settings including:

Current mode and algorithm settings
Component configurations and states
Target brightness and tolerance values
ROI and percentile settings
Feature configurations

Parameters

archive Reference to the archive where the serialized data will be stored

Note: This method is const as it doesn't modify the controller state; The serialized data can be used to restore the controller state later; Component availability is not serialized as it depends on device capabilities

See also: Deserialize()

Since: 1.8

Implements ISerializable.

◆ SetMode()

void SetMode ( ControllerMode mode )

inlineoverridevirtual

Sets the operation mode for the brightness controller.

Parameters

mode	The controller mode to set (Off, Continuous, Once).

Note: Setting mode to Off will disable automatic brightness adjustment

See also: GetMode(); ControllerMode

Since: 1.8

Implements IController.

◆ SkipFrames()

features::SkipFrames & SkipFrames ( )

inline

Gets access to the skip frames feature.

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

Returns: Reference to the SkipFrames feature for configuration

Note: A value of 0 means process every frame (maximum responsiveness); A value of 1 means process every other frame; Optimal values depend on frame rate and scene dynamics

See also: features::SkipFrames

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_advanced_auto_brightness.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AdvancedAutoBrightness()

◆ ~AdvancedAutoBrightness()

Member Function Documentation

◆ AnalogGain()

◆ AnalysisAlgorithm()

◆ AutoPercentile()

◆ AutoTarget()

◆ AutoTolerance()

◆ CombinedGain()

◆ Deserialize()

◆ DigitalGain()

◆ Exposure()

◆ GetComponent()

◆ GetComponents()

◆ GetMode()

◆ GetName()

◆ GetType()

◆ HasAnalogGain()

◆ HasCombinedGain()

◆ HasDigitalGain()

◆ HasExposure()

◆ HasHostGain()

◆ HostGain()

◆ IsRunning()

◆ RegisterFinishedCallback()

◆ ResetToDefault()

◆ Roi()

◆ Serialize()

◆ SetMode()

◆ SkipFrames()

◆ UnregisterFinishedCallback()