Basic automatic focus controller implementation. More...

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

Inheritance diagram for BasicAutoFocus:

Public Member Functions
	BasicAutoFocus (peak::afl::Manager &manager)
	Constructs a BasicAutoFocus controller.
	~BasicAutoFocus () override=default
	Destructor.
void	SetMode (ControllerMode mode) override
	Sets the operating mode of the auto-focus controller.
ControllerMode	GetMode () const override
	Gets the current operating mode of the auto-focus controller.
bool	IsRunning () const override
	Checks if the auto-focus controller is currently running.
void	ResetToDefault () override
	Resets all controller parameters to their default values.
void	SetSkipFrames (uint32_t value)
	Sets the number of frames to skip during auto-focus operations.
uint32_t	GetSkipFrames () const
	Gets the current number of frames being skipped.
peak::common::RangeU	GetSkipFramesRange () const
	Gets the valid range for the skip frames parameter.
void	SetHysteresis (uint8_t value)
	Sets the hysteresis value for focus operations.
uint8_t	GetHysteresis () const
	Gets the current hysteresis value.
peak::common::RangeU8	GetHysteresisRange () const
	Gets the valid range for the hysteresis parameter.
void	SetSharpnessAlgorithm (FocusSharpnessAlgorithm algorithm)
	Sets the sharpness algorithm used for focus quality evaluation.
FocusSharpnessAlgorithm	GetSharpnessAlgorithm () const
	Gets the current sharpness algorithm.
void	SetSearchAlgorithm (FocusSearchAlgorithm algorithm)
	Sets the search algorithm used for finding the optimal focus position.
FocusSearchAlgorithm	GetSearchAlgorithm () const
	Gets the current search algorithm.
void	SetFocusLimit (const peak::common::Interval &limit)
	Sets the focus limit range for auto-focus operations.
peak::common::Interval	GetFocusLimit () const
	Gets the current focus limit range.
void	SetWeightedROIs (const std::vector< WeightedROI > &rois)
	Sets the weighted regions of interest (ROIs) for focus evaluation.
std::vector< WeightedROI >	GetWeightedROIs () const
	Gets the current weighted regions of interest.
void	ResetWeightedROIs () const
	Resets the weighted roi to a single center ROI.
IController::FinishedCallbackHandle	RegisterFinishedCallback (const IController::FinishedCallback &callback)
	Registers a callback function to be called when focus operations complete.
void	UnregisterFinishedCallback (IController::FinishedCallbackHandle callbackHandle)
	Unregisters a previously registered finished 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

Basic automatic focus controller implementation.

The BasicAutoFocus class provides a streamlined interface for automatic focus control. This controller offers essential focus adjustment capabilities with simplified configuration options suitable for most standard focusing requirements.

Key Features:

Multiple search algorithms: Golden ratio, hill climbing, global search, and full scan
Sharpness analysis: Configurable algorithms for focus quality measurement
ROI-based focusing: Weighted regions of interest for targeted focus areas
Focus limits: Configurable range restrictions for focus motor movement
Hysteresis control: Prevents focus hunting and oscillation
Skip frames: Performance optimization through selective frame processing
Callback notifications: Asynchronous operation completion events
Serialization support: Configuration persistence and restoration

Focus Algorithms:

Auto: Automatic algorithm selection based on scene conditions
Golden Ratio: Efficient binary search for smooth focus curves
Hill Climbing: Fast local optimization for quick focusing
Global Search: Comprehensive search for maximum accuracy
Full Scan: Complete range scan for challenging focus conditions

Sharpness Measurement:

Tenengrad: Gradient-based sharpness for high-contrast scenes
Sobel: Edge detection based measurement for general use
Mean Score: Statistical approach for textured surfaces
Histogram Variance: Variance-based measurement for uniform lighting

Note: This controller requires a valid manager instance for camera communication; Focus motor availability depends on underlying device capabilities

See also: AdvancedAutoFocus; FocusSearchAlgorithm; FocusSharpnessAlgorithm; detail::IController

Since: 1.8

Constructor & Destructor Documentation

◆ BasicAutoFocus()

BasicAutoFocus ( peak::afl::Manager & manager )

inlineexplicit

Constructs a BasicAutoFocus controller.

Parameters

manager Reference to the API manager instance that will manage this controller. The manager must remain valid for the lifetime of this controller.

Since: 1.8

◆ ~BasicAutoFocus()

~BasicAutoFocus ( )

overridedefault

Destructor.

Cleans up resources and ensures proper shutdown of the auto-focus controller.

Since: 1.8

Member Function Documentation

◆ GetFocusLimit()

peak::common::Interval GetFocusLimit ( ) const

inline

Gets the current focus limit range.

Returns: Interval representing the current focus position limits.

Since: 1.8

◆ GetHysteresis()

uint8_t GetHysteresis ( ) const

inline

Gets the current hysteresis value.

Returns: The current hysteresis value used for focus stability.

Since: 1.8

◆ GetHysteresisRange()

peak::common::RangeU8 GetHysteresisRange ( ) const

inline

Gets the valid range for the hysteresis parameter.

Returns: Range object containing the minimum and maximum allowed values for the hysteresis setting.

Since: 1.8

◆ GetMode()

ControllerMode GetMode ( ) const

inlineoverridevirtual

Gets the current operating mode of the auto-focus controller.

Returns: The current controller mode.

Since: 1.8

Implements IController.

◆ GetSearchAlgorithm()

FocusSearchAlgorithm GetSearchAlgorithm ( ) const

inline

Gets the current search algorithm.

Returns: The search algorithm currently being used for focus positioning.

Since: 1.8

◆ GetSharpnessAlgorithm()

FocusSharpnessAlgorithm GetSharpnessAlgorithm ( ) const

inline

Gets the current sharpness algorithm.

Returns: The sharpness algorithm currently being used for focus evaluation.

Since: 1.8

◆ GetSkipFrames()

uint32_t GetSkipFrames ( ) const

inline

Gets the current number of frames being skipped.

Returns: The number of frames currently being skipped between focus evaluations.

Since: 1.8

◆ GetSkipFramesRange()

peak::common::RangeU GetSkipFramesRange ( ) const

inline

Gets the valid range for the skip frames parameter.

Returns: Range object containing the minimum and maximum allowed values for the skip frames setting.

Since: 1.8

◆ GetWeightedROIs()

std::vector< WeightedROI > GetWeightedROIs ( ) const

inline

Gets the current weighted regions of interest.

Returns: Vector of WeightedROI objects representing the current focus regions.

Since: 1.8

◆ IsRunning()

bool IsRunning ( ) const

inlineoverridevirtual

Checks if the auto-focus controller is currently running.

Returns: true if the controller is running (mode is not Off), false otherwise.

Since: 1.8

Implements IController.

◆ RegisterFinishedCallback()

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

inline

Registers a callback function to be called when focus operations complete.

The callback will be invoked when the auto-focus operation finishes, whether it succeeds or fails. This allows for asynchronous monitoring of focus operations.

Parameters

callback Function object to be called upon focus operation completion. The callback should accept parameters indicating the operation result.

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

Since: 1.8

◆ ResetToDefault()

void ResetToDefault ( )

inlineoverridevirtual

Resets all controller parameters to their default values.

This method restores the controller to its initial configuration, resetting all settings including skip frames, hysteresis, algorithms, focus limits, and ROIs to their default values.

Since: 1.8

Implements IController.

◆ ResetWeightedROIs()

void ResetWeightedROIs ( ) const

inline

Resets the weighted roi to a single center ROI.

This effectively calls SetPreset with Center

Since: 2.0

◆ SetFocusLimit()

void SetFocusLimit ( const peak::common::Interval & limit )

inline

Sets the focus limit range for auto-focus operations.

The focus limit constrains the auto-focus system to operate within a specified range of focus positions, preventing it from searching across the entire focus range.

Parameters

limit Interval defining the minimum and maximum focus positions that the auto-focus system is allowed to use.

Since: 1.8

◆ SetHysteresis()

void SetHysteresis ( uint8_t value )

inline

Sets the hysteresis value for focus operations.

Hysteresis prevents oscillation around the focus point by requiring a minimum change in focus quality before triggering a focus adjustment. Higher values provide more stability but may reduce responsiveness.

Parameters

value Hysteresis value (0-255). Higher values increase stability but may reduce focus sensitivity.

Since: 1.8

◆ SetMode()

void SetMode ( ControllerMode mode )

inlineoverridevirtual

Sets the operating mode of the auto-focus controller.

Parameters

mode	The desired controller mode (e.g., Off, On, Auto, Manual). See ControllerMode enumeration for available options.

Since: 1.8

Implements IController.

◆ SetSearchAlgorithm()

void SetSearchAlgorithm ( FocusSearchAlgorithm algorithm )

inline

Sets the search algorithm used for finding the optimal focus position.

The search algorithm determines the strategy used to find the best focus position, such as hill climbing, binary search, or full sweep approaches.

Parameters

algorithm The search algorithm to use for focus positioning. See FocusSearchAlgorithm enumeration for available options.

Since: 1.8

◆ SetSharpnessAlgorithm()

void SetSharpnessAlgorithm ( FocusSharpnessAlgorithm algorithm )

inline

Sets the sharpness algorithm used for focus quality evaluation.

The sharpness algorithm determines how focus quality is measured from the image data. Different algorithms may perform better under different lighting conditions or with different scene content.

Parameters

algorithm The sharpness algorithm to use for focus evaluation. See FocusSharpnessAlgorithm enumeration for available options.

Since: 1.8

◆ SetSkipFrames()

void SetSkipFrames ( uint32_t value )

inline

Sets the number of frames to skip during auto-focus operations.

Frame skipping can be used to reduce computational load by processing only every nth frame during focus operations.

Parameters

value Number of frames to skip between focus evaluations. Must be within the valid range returned by GetSkipFramesRange().

Since: 1.8

◆ SetWeightedROIs()

void SetWeightedROIs ( const std::vector< WeightedROI > & rois )

inline

Sets the weighted regions of interest (ROIs) for focus evaluation.

Weighted ROIs allow the auto-focus system to prioritize certain areas of the image when determining focus quality. Each ROI has an associated weight that influences its contribution to the overall focus metric.

Parameters

rois	Vector of weighted ROI objects defining the regions and their relative importance for focus evaluation. An empty vector will use the entire image for focus evaluation.

Since: 1.8

◆ UnregisterFinishedCallback()

void UnregisterFinishedCallback ( IController::FinishedCallbackHandle callbackHandle )

inline

Unregisters a previously registered finished callback.

Parameters

callbackHandle Handle returned by RegisterFinishedCallback() that identifies the callback to be removed.

Since: 1.8

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

peak_afl/pipeline/modules/controllers/peak_afl_basic_auto_focus.hpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BasicAutoFocus()

◆ ~BasicAutoFocus()

Member Function Documentation

◆ GetFocusLimit()

◆ GetHysteresis()

◆ GetHysteresisRange()

◆ GetMode()

◆ GetSearchAlgorithm()

◆ GetSharpnessAlgorithm()

◆ GetSkipFrames()

◆ GetSkipFramesRange()

◆ GetWeightedROIs()

◆ IsRunning()

◆ RegisterFinishedCallback()

◆ ResetToDefault()

◆ ResetWeightedROIs()

◆ SetFocusLimit()

◆ SetHysteresis()

◆ SetMode()

◆ SetSearchAlgorithm()

◆ SetSharpnessAlgorithm()

◆ SetSkipFrames()

◆ SetWeightedROIs()

◆ UnregisterFinishedCallback()