Pipeline Features

Configurable parameters and algorithms for automatic camera control within the pipeline framework. More...

Data Structures
class	AutoPercentile
	Auto percentile feature implementation for auto controllers. More...
class	AutoTarget
	Auto target feature implementation for auto controllers. More...
class	AutoTolerance
	Auto tolerance feature implementation for auto controllers. More...
class	BrightnessAlgorithm
	Brightness algorithm feature implementation for auto controllers. More...
class	BrightnessComponent
	Brightness component feature implementation for auto controllers. More...
class	BrightnessLimit
	Base class for brightness limit features. More...
class	BrightnessExposureLimit
	Exposure limit feature implementation for brightness controllers. More...
class	BrightnessGainLimit
	Gain limit feature implementation for brightness controllers. More...
class	BrightnessGainAnalogLimit
	Analog gain limit feature implementation for brightness controllers. More...
class	BrightnessGainDigitalLimit
	Digital gain limit feature implementation for brightness controllers. More...
class	BrightnessGainCombinedLimit
	Combined gain limit feature implementation for brightness controllers. More...
class	BrightnessGainHostLimit
	Host gain limit feature implementation for brightness controllers. More...
class	FocusLimit
	Focus limit feature implementation for auto focus controllers. More...
class	Hysteresis
	Hysteresis feature implementation for auto controllers. More...
class	IFeature< T >
	Base interface for auto feature implementations. More...
class	IRangeFeature< T >
	Interface for features that have a valid range of values. More...
class	IListFeature< T >
	Interface for features that have a list of valid values. More...
class	Roi
	Region of Interest (ROI) feature implementation for auto controllers. More...
class	SearchAlgorithm
	Search algorithm feature implementation for auto focus controllers. More...
class	SharpnessAlgorithm
	Sharpness algorithm feature implementation for auto focus controllers. More...
class	SkipFrames
	Skip frames feature implementation for auto controllers. More...
struct	WeightedROI
	Weighted region of interest structure. More...
class	WeightedRois
	Weighted regions of interest feature implementation for auto controllers. More...

Enumerations
enum class	BrightnessAnalysisAlgorithm { Median , Mean }
	Brightness analysis algorithm enumeration. More...
enum class	BrightnessComponentType {   Invalid , Exposure , AnalogGain , DigitalGain ,   CombinedGain , HostGain , Gain }
	Brightness component type enumeration. More...
enum class	FocusSearchAlgorithm {   Auto , GoldenRatio , HillClimbing , GlobalSearch ,   FullScan }
	Focus search algorithm enumeration. More...
enum class	FocusSharpnessAlgorithm {   Auto , Tenengrad , Sobel , MeanScore ,   HistogramVariance }
	Focus sharpness algorithm enumeration. More...
enum class	Weight { Weak , Medium , Strong }
	Weight enumeration for weighted regions of interest. More...
enum class	RoiPreset { Center }
	Preset enumeration for the Region of interest. More...
enum class	AutoBrightnessPolicy { ExposureAndGain , ExposureOnly , GainOnly }
	Auto brightness control policy enumeration. More...

Functions
std::string	ToString (BrightnessAnalysisAlgorithm algorithm)
	Converts BrightnessAnalysisAlgorithm enumeration to string representation.
std::ostream &	operator<< (std::ostream &os, BrightnessAnalysisAlgorithm algorithm)
	Stream insertion operator for BrightnessAnalysisAlgorithm enumeration.
std::string	ToString (BrightnessComponentType type)
	Converts BrightnessComponentType enumeration to string representation.
std::ostream &	operator<< (std::ostream &os, BrightnessComponentType type)
	Stream insertion operator for BrightnessComponentType enumeration.
std::string	ToString (FocusSearchAlgorithm algorithm)
	Converts FocusSearchAlgorithm enumeration to string representation.
std::ostream &	operator<< (std::ostream &os, FocusSearchAlgorithm algorithm)
	Stream insertion operator for FocusSearchAlgorithm enumeration.
std::string	ToString (FocusSharpnessAlgorithm algorithm)
	Converts FocusSharpnessAlgorithm enumeration to string representation.
std::ostream &	operator<< (std::ostream &os, FocusSharpnessAlgorithm algorithm)
	Stream insertion operator for FocusSharpnessAlgorithm enumeration.
std::string	ToString (Weight weight)
	Converts Weight enumeration to string representation.
std::ostream &	operator<< (std::ostream &os, Weight weight)
	Stream insertion operator for Weight enumeration.
std::string	ToString (AutoBrightnessPolicy policy)
	Converts AutoBrightnessPolicy enumeration to string representation.

Detailed Description

Configurable parameters and algorithms for automatic camera control within the pipeline framework.

Pipeline Features

The Pipeline Features provide configurable parameters and algorithms for automatic camera control within the pipeline framework. These features are building blocks used by pipeline controllers to implement sophisticated automatic control functionality.

The pipeline features are organized into several categories:

Core Feature Interfaces

• IFeature - Base interface for all features
• IListFeature - Interface for features with enumerated values
• IRangeFeature - Interface for features with numeric ranges

Brightness Control Features

• AutoTarget - Target brightness value configuration
• AutoTolerance - Brightness tolerance settings
• AutoPercentile - Percentile-based brightness analysis
• BrightnessAlgorithm - Brightness analysis algorithms
• BrightnessComponent - Individual brightness components
• BrightnessLimit - Brightness range limits

Focus Control Features

• FocusLimit - Focus position range limits
• Hysteresis - Focus stability control
• SearchAlgorithm - Focus search algorithms
• SharpnessAlgorithm - Sharpness measurement algorithms
• WeightedROIs - Multi-region focus evaluation

General Control Features

• ROI - Region of interest configuration
• SkipFrames - Frame processing optimization

Feature Architecture

Base Interfaces

IFeature

The base interface for all pipeline features providing common functionality:

• Serialization: Save and restore feature configurations
• Validation: Parameter range checking and validation
• Type Safety: Strongly typed parameter access

IListFeature

Specialized interface for features with enumerated values:

• Enumeration Support: Predefined value lists (e.g., algorithms)
• List Access: Get available options for UI population
• Validation: Automatic validation against supported values

IRangeFeature

Specialized interface for features with numeric ranges:

• Range Validation: Automatic min/max boundary checking
• Device Limits: Integration with device capability ranges
• Type Safety: Templated for different numeric types

Brightness Features Usage

AutoTarget

Configures the desired brightness level for automatic adjustment:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_auto_target.hpp>
 
    // Create auto target feature
    auto targetFeature = std::make_shared<peak::pipeline::modules::autofeature::features::AutoTarget>(
        controller);
 
    // Set target brightness value
    targetFeature->Set(128); // 0-255 range typically
 
    // Get current target
    uint32_t currentTarget = targetFeature->Get();
 
    // Get valid range
    auto range = targetFeature->GetRange();
    std::cout << "Valid range: " << range.GetMinimum() << " - " << range.GetMaximum() << std::endl;

AutoTolerance

Defines acceptable deviation from target brightness:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_auto_tolerance.hpp>
 
    // Create tolerance feature
    auto toleranceFeature = std::make_shared<peak::pipeline::modules::autofeature::features::AutoTolerance>(
        controller);
 
    // Set tolerance value
    toleranceFeature->Set(15); // Acceptable deviation
 
// Smaller tolerance = more stable brightness, larger = less frequent adjustments
 

BrightnessAlgorithm

Selects the algorithm for brightness analysis:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_brightness_algorithm.hpp>
 
    // Create algorithm feature
    auto algorithmFeature =
        std::make_shared<peak::pipeline::modules::autofeature::features::BrightnessAlgorithm>(controller);
 
    // Set analysis algorithm
    algorithmFeature->Set(peak::pipeline::modules::autofeature::BrightnessAnalysisAlgorithm::Median);

Focus Features Usage

SearchAlgorithm

Configures the focus search strategy:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_search_algorithm.hpp>
 
    // Create search algorithm feature
    auto searchFeature = std::make_shared<peak::pipeline::modules::autofeature::features::SearchAlgorithm>(
        controller);
 
    // Set search algorithm
    searchFeature->Set(peak::pipeline::modules::autofeature::FocusSearchAlgorithm::GoldenRatio);
 
// Available algorithms: Auto, GoldenRatio, HillClimbing, GlobalSearch, FullScan

SharpnessAlgorithm

Configures the sharpness measurement method:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_sharpness_algorithm.hpp>
 
    // Create sharpness algorithm feature
    auto sharpnessFeature =
        std::make_shared<peak::pipeline::modules::autofeature::features::SharpnessAlgorithm>(controller);
 
    // Set sharpness algorithm
    sharpnessFeature->Set(peak::pipeline::modules::autofeature::FocusSharpnessAlgorithm::Tenengrad);
 
// Available algorithms: Auto, Tenengrad, Sobel, MeanScore, HistogramVariance

WeightedROIs

Configures multiple regions for focus evaluation:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_weighted_rois.hpp>
 
    // Create weighted ROIs feature
    auto roisFeature = std::make_shared<peak::pipeline::modules::autofeature::features::WeightedRois>(
        controller);
 
    // Configure multiple focus regions
    std::vector<peak::pipeline::modules::autofeature::WeightedROI> rois = {
        { { { 200, 200 }, { 400, 300 } },
            peak::pipeline::modules::autofeature::Weight::Strong }, // Primary focus area
        { { { 100, 100 }, { 150, 150 } },
            peak::pipeline::modules::autofeature::Weight::Medium }, // Secondary area
        { { { 500, 400 }, { 100, 80 } },
            peak::pipeline::modules::autofeature::Weight::Weak } // Background area
    };
 
    roisFeature->Set(rois);

FocusLimit

Sets the allowable focus position range:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_focus_limit.hpp>
 
    // Create focus limit feature
    auto limitFeature = std::make_shared<peak::pipeline::modules::autofeature::features::FocusLimit>(
        controller);
 
    // Set focus range limits
    peak::common::Interval focusRange{ 100, 900 }; // Near to far limits
    limitFeature->Set(focusRange);

Hysteresis

Prevents focus hunting and oscillation:

 
#include <peak_afl/pipeline/modules/controllers/features/peak_afl_hysteresis.hpp>
 
    // Create hysteresis feature
    auto hysteresisFeature = std::make_shared<peak::pipeline::modules::autofeature::features::Hysteresis>(
        controller);
 
    // Set hysteresis value
    hysteresisFeature->Set(8); // Higher values = more stability, less responsiveness
 

General Features Usage

ROI (Region of Interest)

Defines the analysis area for white balance and other operations:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_roi.hpp>
 
    // Create ROI feature
    auto roiFeature = std::make_shared<peak::pipeline::modules::autofeature::features::Roi>(controller);
 
    // Set region of interest
    peak::common::Rectangle roi{ { 150, 150 }, { 300, 200 } };
    roiFeature->Set(roi);

SkipFrames

Optimizes performance by processing every Nth frame:

#include <peak_afl/pipeline/modules/controllers/features/peak_afl_skip_frames.hpp>
 
        // Create skip frames feature
        auto skipFeature = std::make_shared<peak::pipeline::modules::autofeature::features::SkipFrames>(
            controller);
 
        // Set frame skipping (0 = process every frame, 2 = process every 3rd frame)
        skipFeature->Set(2);
 
        // Get valid range
        auto range = skipFeature->GetRange();

Feature Serialization

All features support serialization for configuration persistence:

        // Serialize feature configuration
        peak::icv::Archive archive;
        feature->Serialize(archive);
 
        // Later, restore configuration
        feature->Deserialize(archive);

Feature Validation

Features automatically validate parameters against device capabilities:

        // Range validation example
        auto targetFeature = std::make_shared<peak::pipeline::modules::autofeature::features::AutoTarget>(
            controller);
        auto range = targetFeature->GetRange();
 
        uint32_t desiredValue = 200;
        if (desiredValue >= range.GetMinimum() && desiredValue <= range.GetMaximum())
        {
            targetFeature->Set(desiredValue); // Safe to set
        }
        else
        {
            // Handle invalid value
            std::cerr << "Value " << desiredValue << " outside valid range [" << range.GetMinimum() << ", "
                      << range.GetMaximum() << "]" << std::endl;
        }

Algorithm Features

Brightness Analysis Algorithms

Available brightness analysis methods:

• Mean: Average-based analysis for general use
• Median: Robust analysis for noisy conditions
• Percentile: Customizable percentile-based analysis

Focus Search Algorithms

Available focus search strategies:

• GoldenRatio: Efficient binary search
• HillClimbing: Fast local optimization
• GlobalSearch: Comprehensive search
• FullScan: Complete range scan

Focus Sharpness Algorithms

Available sharpness measurement methods:

• Tenengrad: Gradient-based measurement
• Sobel: Edge detection based
• MeanScore: Statistical approach
• HistogramVariance: Variance-based measurement

Best Practices

Feature Configuration

// Always check ranges before setting values
auto range = feature->GetRange();
if (value >= range.min && value <= range.max) {
    feature->Set(value);
}

Algorithm Selection

// Get available algorithms for UI population
auto algorithms = algorithmFeature->GetList();
// Present options to user or select programmatically

Error Handling

    try
    {
        feature->Set(value);
    }
    catch (const peak::common::InvalidParameterException& /*e*/)
    {
        // Handle invalid parameter
    }

Note

Pipeline features are designed to be used within pipeline controllers but can also be accessed directly for advanced configuration.

All features provide automatic parameter validation and serialization support for robust configuration management.

Feature availability depends on the underlying device capabilities and controller implementation.

Enumeration Type Documentation

AutoBrightnessPolicy

enum class AutoBrightnessPolicy

strong

Auto brightness control policy enumeration.

Defines the different strategies for automatic brightness control, determining which camera parameters the controller is allowed to adjust to achieve the target brightness level.

Since

1.8

Enumerator
ExposureAndGain	Use both exposure time and gain adjustments for optimal brightness control.
ExposureOnly	Use only exposure time adjustments, keeping gain constant.
GainOnly	Use only gain adjustments, keeping exposure time constant.

BrightnessAnalysisAlgorithm

enum class BrightnessAnalysisAlgorithm

strong

Brightness analysis algorithm enumeration.

Defines the available algorithms for analyzing brightness in automatic exposure and brightness control systems. Each algorithm provides a different method for calculating the representative brightness value from the image data.

Since

1.8

Enumerator
Median	Median-based brightness calculation - uses the median value of pixel intensities.
Mean	Mean-based brightness calculation - uses the average value of pixel intensities.

BrightnessComponentType

enum class BrightnessComponentType

strong

Brightness component type enumeration.

Defines the different types of brightness components that can be controlled in automatic exposure systems. Each component represents a different aspect of image brightness control with specific characteristics and limitations.

Since

1.8

Enumerator
Invalid	Invalid or uninitialized component type.
Exposure	Exposure time component - controls sensor integration time.
AnalogGain	Analog gain component - hardware gain applied before digitization.
DigitalGain	Digital gain component - gain applied after digitization.
CombinedGain	Combined gain component - both analog and digital (combined) gain.
HostGain	Host gain component - software-based gain processing.
Gain	Automatic gain component - automatic gain control.

FocusSearchAlgorithm

enum class FocusSearchAlgorithm

strong

Focus search algorithm enumeration.

Defines the available algorithms for automatic focus search operations. Each algorithm provides different characteristics in terms of speed, accuracy, and robustness for various focusing scenarios.

Since

1.8

Enumerator
Auto	Automatic algorithm selection - default algorithm. Deprecated This value is deprecated. The automatic selection always defaults to the Golden Ratio algorithm. Use GoldenRatio instead.
GoldenRatio	Golden ratio search - efficient for unimodal focus curves.
HillClimbing	Hill climbing search - good for local optimization.
GlobalSearch	Global search - comprehensive but slower search.
FullScan	Full scan - scans entire focus range for maximum accuracy.

FocusSharpnessAlgorithm

enum class FocusSharpnessAlgorithm

strong

Focus sharpness algorithm enumeration.

Defines the available algorithms for measuring image sharpness in automatic focus systems. Each algorithm provides different characteristics for detecting the optimal focus position based on image analysis.

Since

1.8

Enumerator
Auto	Automatic algorithm selection - controller chooses the best algorithm. Deprecated This value is deprecated. The automatic selection always defaults to the Tenengrad algorithm. Use Tenengrad instead.
Tenengrad	Tenengrad algorithm - gradient-based sharpness measurement.
Sobel	Sobel algorithm - edge detection based sharpness measurement.
MeanScore	Mean score algorithm - statistical sharpness measurement.
HistogramVariance	Histogram variance algorithm - variance-based sharpness measurement.

RoiPreset

enum class RoiPreset

strong

Preset enumeration for the Region of interest.

ROI configurations that can be applied without manually specifying coordinates. These presets automatically adapt to the current image size.

Since

2.0

Enumerator
Center	Sets a centered ROI that is one-third of the image dimensions.

Weight

enum class Weight

strong

Weight enumeration for weighted regions of interest.

Defines the importance levels that can be assigned to regions of interest in automatic control algorithms. Different weights influence how much priority the algorithms give to each region.

Since

1.8

Enumerator
Weak	Low importance - minimal influence on auto algorithms.
Medium	Normal importance - standard influence on auto algorithms.
Strong	High importance - strong influence on auto algorithms.

Function Documentation

operator<<() [1/5]

std::ostream & operator<< ( std::ostream & os, BrightnessAnalysisAlgorithm algorithm )

inline

Stream insertion operator for BrightnessAnalysisAlgorithm enumeration.

Enables direct output of BrightnessAnalysisAlgorithm values to output streams using their string representation.

Parameters

[in,out]	os	The output stream to write to
[in]	algorithm	The BrightnessAnalysisAlgorithm value to output

Returns

Reference to the output stream for chaining

Note

Uses ToString() function for string conversion

See also

ToString(BrightnessAnalysisAlgorithm)

BrightnessAnalysisAlgorithm

Since

1.8

operator<<() [2/5]

std::ostream & operator<< ( std::ostream & os, BrightnessComponentType type )

inline

Stream insertion operator for BrightnessComponentType enumeration.

Enables direct output of BrightnessComponentType values to output streams using their string representation.

Parameters

[in,out]	os	The output stream to write to
[in]	type	The BrightnessComponentType value to output

Returns

Reference to the output stream for chaining

Note

Uses ToString() function for string conversion

See also

ToString(BrightnessComponentType)

BrightnessComponentType

Since

1.8

operator<<() [3/5]

std::ostream & operator<< ( std::ostream & os, FocusSearchAlgorithm algorithm )

inline

Stream insertion operator for FocusSearchAlgorithm enumeration.

Enables direct output of FocusSearchAlgorithm values to output streams using their string representation.

Parameters

[in,out]	os	The output stream to write to
[in]	algorithm	The FocusSearchAlgorithm value to output

Returns

Reference to the output stream for chaining

Note

Uses ToString() function for string conversion

See also

ToString(FocusSearchAlgorithm)

FocusSearchAlgorithm

Since

1.8

operator<<() [4/5]

std::ostream & operator<< ( std::ostream & os, FocusSharpnessAlgorithm algorithm )

inline

Stream insertion operator for FocusSharpnessAlgorithm enumeration.

Enables direct output of FocusSharpnessAlgorithm values to output streams using their string representation.

Parameters

[in,out]	os	The output stream to write to
[in]	algorithm	The FocusSharpnessAlgorithm value to output

Returns

Reference to the output stream for chaining

Note

Uses ToString() function for string conversion

See also

ToString(FocusSharpnessAlgorithm)

FocusSharpnessAlgorithm

Since

1.8

operator<<() [5/5]

std::ostream & operator<< ( std::ostream & os, Weight weight )

inline

Stream insertion operator for Weight enumeration.

Enables direct output of Weight values to output streams using their string representation.

Parameters

[in,out]	os	The output stream to write to
[in]	weight	The Weight value to output

Returns

Reference to the output stream for chaining

Note

Uses ToString() function for string conversion

See also

ToString(Weight)

Weight

Since

1.8

ToString() [1/6]

std::string ToString ( AutoBrightnessPolicy policy )

inline

Converts AutoBrightnessPolicy enumeration to string representation.

Parameters

[in]

policy

The auto brightness policy to convert

Returns

String representation of the policy

Exceptions

peak::afl::error::InvalidParameterException

if policy is unknown

See also

AutoBrightnessPolicy

Since

1.8

ToString() [2/6]

std::string ToString ( BrightnessAnalysisAlgorithm algorithm )

inline

Converts BrightnessAnalysisAlgorithm enumeration to string representation.

Parameters

[in]

algorithm

The brightness analysis algorithm to convert

Returns

String representation of the algorithm

Exceptions

peak::afl::error::InvalidParameterException

if algorithm is unknown

See also

BrightnessAnalysisAlgorithm

Since

1.8

ToString() [3/6]

std::string ToString ( BrightnessComponentType type )

inline

Converts BrightnessComponentType enumeration to string representation.

Parameters

[in]

type

The brightness component type to convert

Returns

String representation of the component type

Exceptions

peak::afl::error::InternalErrorException

if type is invalid

See also

BrightnessComponentType

Since

1.8

ToString() [4/6]

std::string ToString ( FocusSearchAlgorithm algorithm )

inline

Converts FocusSearchAlgorithm enumeration to string representation.

Parameters

[in]

algorithm

The focus search algorithm to convert

Returns

String representation of the algorithm

Exceptions

peak::afl::error::InvalidParameterException

if algorithm is unknown

See also

FocusSearchAlgorithm

Since

1.8

ToString() [5/6]

std::string ToString ( FocusSharpnessAlgorithm algorithm )

inline

Converts FocusSharpnessAlgorithm enumeration to string representation.

Parameters

[in]

algorithm

The focus sharpness algorithm to convert

Returns

String representation of the algorithm

Exceptions

peak::afl::error::InvalidParameterException

if algorithm is unknown

See also

FocusSharpnessAlgorithm

Since

1.8

ToString() [6/6]

std::string ToString ( Weight weight )

inline

Converts Weight enumeration to string representation.

Parameters

[in]

weight

The weight value to convert

Returns

String representation of the weight

Exceptions

peak::afl::error::InternalErrorException

if weight is invalid

See also

Weight

Since

1.8