[libcamera-devel] [PATCH] ipa: ipu3: awb: Add some documentation on the algorithm used

[Kieran Bingham]

On 02/09/2021 12:51, Jean-Michel Hautbois wrote:
> The AWB algorithm is based on the Grey world algorithm and uses the
> statistics generated by the ImgU for that. Explain how it uses those,
> and reference the original algorithm at the same time.
> 
> Signed-off-by: Jean-Michel Hautbois <jeanmichel.hautbois at ideasonboard.com>
> ---
>  src/ipa/ipu3/algorithms/awb.cpp | 26 ++++++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/src/ipa/ipu3/algorithms/awb.cpp b/src/ipa/ipu3/algorithms/awb.cpp
> index d97724fa..f0b12d1a 100644
> --- a/src/ipa/ipu3/algorithms/awb.cpp
> +++ b/src/ipa/ipu3/algorithms/awb.cpp
> @@ -20,6 +20,32 @@ LOG_DEFINE_CATEGORY(IPU3Awb)
>  static constexpr uint32_t kMinZonesCounted = 16;
>  static constexpr uint32_t kMinGreenLevelInZone = 32;
>  
> +/**
> + * The Grey World algorithm assumes that the scene, in average, is neutral grey.
> + * Reference: Lam, Edmund & Fung, George. (2008). Automatic White Balancing in
> + * Digital Photography. 10.1201/9781420054538.ch10.

Does this mean that /this/ algorithm is an implementation of the Grey
World algorithm?

We should say so.

"""
This AWB algorithm module provides a simple Grey World algorithm
implementation based upon the procedures and methods described in
Automatic White Balancing in Digital Photography.

The Grey World algorithm assumes that the scene, in average, is a
neutral grey.

Reference: Lam, Edmund & Fung, George. (2008). Automatic White Balancing
in Digital Photography. 10.1201/9781420054538.ch10.
"""

> + *
> + * The IPU3 generates statistics from the Bayer Down Scaler output into a grid
> + * defined in the ipu3_uapi_awb_config_s structure.
> + *
> + * For example, when the BDS outputs a frame of 2592x1944, the grid may be
> + * configured to 81x30 cells each with a size of 32x64 pixels.
> + * We then have an average of 2048 R, G and B pixels per cell.
> + *
> + * The AWB algorithm uses a fixed grid size of kAwbStatsSizeX x kAwbStatsSizeY.

"This AWB algorithm" ?

But otherwise,

Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>

> + * Each of this new grid cell will be called a zone.
> + *
> + * Before calculating the gains, we will convert the statistics from the BDS
> + * grid to an internal grid configuration in generateAwbStats.
> + * As part of converting the statistics to an internal grid, the saturation
> + * flag from the originating grid cell is used to decide if the zone contains
> + * saturated pixels or not, making the zone relevant or not.
> + * A saturated zone will be excluded from the calculation.
> + *
> + * The Grey World algorithm will then estimate the red and blue gains to apply, and
> + * store the results in the metadata.
> + */
> +
>  /**
>   * \struct Accumulator
>   * \brief RGB statistics for a given region
>