A mean-based auto-exposure algorithm. More...

Classes
struct	AgcConstraint
	The boundaries and target for an AeConstraintMode constraint. More...

struct	Params
	Collection of parameters for the mean luminance AGC algorithm. More...

struct	Result
	Collection of results of the mean luminance AGC algorithm. More...

class	Traits
	A collection of callbacks. More...

Public Member Functions
void	configure (utils::Duration lineDuration, const CameraSensorHelper *sensorHelper)
	Configure the exposure mode helpers.

int	parseTuningData (const ValueNode &tuningData)
	Parse tuning data for AeConstraintMode and AeExposureMode controls.

void	setLimits (utils::Duration minExposureTime, utils::Duration maxExposureTime, double minGain, double maxGain, std::vector< AgcConstraint > constraints)
	Set the ExposureModeHelper limits for this class.

const std::map< int32_t, std::vector< AgcConstraint > > &	constraintModes () const
	Get the constraint modes that have been parsed from tuning data.

const std::map< int32_t, ExposureModeHelper > &	exposureModeHelpers () const
	Get the ExposureModeHelpers that have been parsed from tuning data.

Result	calculateNewEv (const Params &params)
	Calculate the new exposure value and split it between exposure time and gain.

double	effectiveYTarget (double lux, double exposureCompensation) const
	Get the currently effective y target.

Detailed Description

A mean-based auto-exposure algorithm.

This algorithm calculates an exposure time, analogue and digital gain such that the normalised mean luminance value of an image is driven towards a target, which itself is discovered from tuning data. The algorithm is a two-stage process.

In the first stage, an initial gain value is derived by iteratively comparing the gain-adjusted mean luminance across the entire image against a target, and selecting a value which pushes it as closely as possible towards the target.

In the second stage we calculate the gain required to drive the average of a section of a histogram to a target value, where the target and the boundaries of the section of the histogram used in the calculation are taken from the values defined for the currently configured AeConstraintMode within the tuning data. This class provides a helper function to parse those tuning data to discover the constraints, and so requires a specific format for those data which is described in parseTuningData(). The gain from the first stage is then clamped to the gain from this stage.

The final gain is used to adjust the effective exposure value of the image, and that new exposure value is divided into exposure time, analogue gain and digital gain according to the selected AeExposureMode. This class uses the ExposureModeHelper class to assist in that division, and expects the data needed to initialise that class to be present in tuning data in a format described in parseTuningData().

In order to be able to use this algorithm an IPA module needs to be able to do the following:

Provide a luminance estimation across an entire image.
Provide a luminance Histogram for the image to use in calculating constraint compliance. The precision of the Histogram that is available will determine the supportable precision of the constraints.

IPA modules that want to use this class to implement their AEGC algorithm should derive AgcMeanLuminance::Traits and override the necessary functions. The users must call parseTuningData() in init(), and must also call configure() and setLimits() in configure(). They may then use calculateNewEv() in process(). If the limits passed to setLimits() change for any reason (for example, in response to a FrameDurationLimit control being passed in queueRequest()) then setLimits() must be called again with the new values.

Member Function Documentation

◆ calculateNewEv()

AgcMeanLuminance::Result libcamera::ipa::AgcMeanLuminance::calculateNewEv ( const Params & params )

Calculate the new exposure value and split it between exposure time and gain.

Parameters

[in] params The set of parameters for the exppsure value calculation

Calculate a new exposure value to try to obtain the target. The calculated exposure value is filtered to prevent rapid changes from frame to frame, and divided into exposure time, analogue, quantization and digital gain.

Returns: Tuple of exposure time, analogue gain, quantization gain and digital gain

◆ configure()

void libcamera::ipa::AgcMeanLuminance::configure	(	utils::Duration	lineDuration,
		const CameraSensorHelper *	sensorHelper
	)

Configure the exposure mode helpers.

Parameters

[in]	lineDuration	The sensor line length
[in]	sensorHelper	The sensor helper

This function configures the exposure mode helpers so they can correctly take quantization effects into account.

◆ effectiveYTarget()

double libcamera::ipa::AgcMeanLuminance::effectiveYTarget	(	double	lux,
		double	exposureCompensation
	)		const

Get the currently effective y target.

Parameters

[in]	lux	The effective lux value
[in]	exposureCompensation	The exposure compensation value

This function returns the current y target including exposure compensation.

Returns: The y target value

◆ parseTuningData()

int libcamera::ipa::AgcMeanLuminance::parseTuningData ( const ValueNode & tuningData )

Parse tuning data for AeConstraintMode and AeExposureMode controls.

Parameters

[in] tuningData the ValueNode representing the tuning data

This function parses tuning data to build the list of allowed values for the AeConstraintMode and AeExposureMode controls. Those tuning data must provide the data in a specific format; the Agc algorithm's tuning data should contain a dictionary called AeConstraintMode containing per-mode setting dictionaries with the key being a value from controls::AeConstraintModeNameValueMap. The yTarget can either be provided as single value or as array in which case it is interpreted as a PWL mapping lux levels to yTarget values. Each mode dict may contain either a "lower" or "upper" key or both, for example:

algorithms:
  - Agc:
      AeConstraintMode:
        ConstraintNormal:
          lower:
            qLo: 0.98
            qHi: 1.0
            yTarget: 0.5
        ConstraintHighlight:
          lower:
            qLo: 0.98
            qHi: 1.0
            yTarget: 0.5
          upper:
            qLo: 0.98
            qHi: 1.0
            yTarget: [ 100, 0.8, 20000, 0.5 ]

For the AeExposureMode control the data should contain a dictionary called AeExposureMode containing per-mode setting dictionaries with the key being a value from controls::AeExposureModeNameValueMap. Each mode dict should contain an array of exposure times with the key "exposureTime" and an array of gain values with the key "gain", in this format:

algorithms:
  - Agc:
      AeExposureMode:
        ExposureNormal:
          exposureTime: [ 100, 10000, 30000, 60000, 120000 ]
          gain: [ 2.0, 4.0, 6.0, 8.0, 10.0 ]
        ExposureShort:
          exposureTime: [ 100, 10000, 30000, 60000, 120000 ]
          gain: [ 2.0, 4.0, 6.0, 8.0, 10.0 ]

Returns: 0 on success or a negative error code

◆ setLimits()

void libcamera::ipa::AgcMeanLuminance::setLimits	(	utils::Duration	minExposureTime,
		utils::Duration	maxExposureTime,
		double	minGain,
		double	maxGain,
		std::vector< AgcConstraint >	constraints
	)

Set the ExposureModeHelper limits for this class.

Parameters

[in]	minExposureTime	Minimum exposure time to allow
[in]	maxExposureTime	Maximum ewposure time to allow
[in]	minGain	Minimum gain to allow
[in]	maxGain	Maximum gain to allow
[in]	constraints	Additional constraints to apply

This function calls ExposureModeHelper::setLimits() for each ExposureModeHelper that has been created for this class.

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

src/ipa/libipa/agc_mean_luminance.h
src/ipa/libipa/agc_mean_luminance.cpp

Classes

Public Member Functions

Detailed Description

Member Function Documentation

◆ calculateNewEv()

◆ configure()

◆ effectiveYTarget()

◆ parseTuningData()

◆ setLimits()