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

[Laurent Pinchart]

Hi Jean-Michel,

Thank you for the patch.

On Mon, Aug 23, 2021 at 02:49:34PM +0200, 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 | 25 +++++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/src/ipa/ipu3/algorithms/awb.cpp b/src/ipa/ipu3/algorithms/awb.cpp
> index 60a5fc52..8e4230b5 100644
> --- a/src/ipa/ipu3/algorithms/awb.cpp
> +++ b/src/ipa/ipu3/algorithms/awb.cpp
> @@ -17,6 +17,31 @@ namespace ipa::ipu3::algorithms {
>  
>  LOG_DEFINE_CATEGORY(IPU3Awb)
>  
> +/**
> + * 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.

The last part of the reference is a bit opaque, should we reference the
book (Single-Sensor Imaging: Methods and Applications for Digital
Cameras, pp. 267–294, CRC Press, 2008) ?

> + *
> + * 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.

Paragraph reflow, here and below.

> + *
> + * The AWB algorithm uses a fixed grid size of kAwbStatsSizeX x kAwbStatsSizeY.
> + * 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 IspStatsRegion

-- 
Regards,

Laurent Pinchart