libcamera: libcamera::ipa::AgcMeanLuminance Class Reference

libcamera v0.7.2 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ipa::AgcMeanLuminance Class Referenceabstract

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

Inheritance diagram for libcamera::ipa::AgcMeanLuminance:
[legend]

## 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 ValueNode &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:

1. Provide a luminance estimation across an entire image.
2. 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 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

## ◆ resetFrameCount()

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

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

void 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