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

Inheritance diagram for libcamera::ipa::AgcMeanLuminance:

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

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

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

void	setExposureCompensation (double gain)
	Set the exposure compensation value.

void	setLux (unsigned int lux)
	Set the lux level.

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, std::shared_ptr< ExposureModeHelper > > &	exposureModeHelpers () const
	Get the ExposureModeHelpers that have been parsed from tuning data.

ControlInfoMap::Map	controls ()
	Get the controls that have been generated after parsing tuning data.

std::tuple< utils::Duration, double, double, double >	calculateNewEv (uint32_t constraintModeIndex, uint32_t exposureModeIndex, const Histogram &yHist, utils::Duration effectiveExposureValue)
	Calculate the new exposure value and splut it between exposure time and gain.

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

void	resetFrameCount ()
	Reset the frame counter.

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 it and provide an overriding estimateLuminance() function for this class to use. They must call parseTuningData() in init(), and must also call setLimits() and resetFrameCounter() 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()

std::tuple< utils::Duration, double, double, double > libcamera::ipa::AgcMeanLuminance::calculateNewEv	(	uint32_t	constraintModeIndex,
		uint32_t	exposureModeIndex,
		const Histogram &	yHist,
		utils::Duration	effectiveExposureValue
	)

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

Parameters

[in]	constraintModeIndex	The index of the current constraint mode
[in]	exposureModeIndex	The index of the current exposure mode
[in]	yHist	A Histogram from the ISP statistics to use in constraining the calculated gain
[in]	effectiveExposureValue	The EV applied to the frame from which the statistics in use derive

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 ( ) const

Get the currently effective y target.

This function returns the current y target including exposure compensation.

Returns: The y target value

◆ parseTuningData()

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

Parse tuning data for AeConstraintMode and AeExposureMode controls.

Parameters

[in] tuningData the YamlObject 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

◆ resetFrameCount()

libcamera::ipa::AgcMeanLuminance::resetFrameCount ( )

inline

Reset the frame counter.

This function resets the internal frame counter, which exists to help the algorithm decide whether it should respond instantly or not. The expectation is for derived classes to call this function before each camera start call in their configure() function.

◆ setExposureCompensation()

libcamera::ipa::AgcMeanLuminance::setExposureCompensation ( double gain )

inline

Set the exposure compensation value.

Parameters

[in] gain The exposure compensation gain

This function sets the exposure compensation value to be used in the AGC calculations. It is expressed as gain instead of EV.

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

◆ setLux()

libcamera::ipa::AgcMeanLuminance::setLux ( unsigned int lux )

inline

Set the lux level.

Parameters

[in] lux The lux level

This function sets the lux level to be used in the AGC calculations. A value of 0 means no measurement and a default value of kDefaultLuxLevel is used if necessary.

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()

◆ resetFrameCount()

◆ setExposureCompensation()

◆ setLimits()

◆ setLux()