[libcamera-devel] [PATCH v2 4/6] libcamera: controls: Add AWB related controls

[Naushir Patuck]

Hi Laurent,

On Thu, 26 Mar 2020 at 15:46, Laurent Pinchart
<laurent.pinchart at ideasonboard.com> wrote:
>
> Hi Naush,
>
> Thank you for the patch.
>
> On Fri, Mar 20, 2020 at 03:11:42PM +0000, Kieran Bingham wrote:
> > On 09/03/2020 12:33, Naushir Patuck wrote:
> > > AwbMode is a new enum type to specify operating mode of the AWB
> > > algorithm. All modes may not be supported by all platforms.
> > >
> > > ManualWbGains is a new float arary type used to specify manual red
> >
> > /arary/array/
> >
> > > and blue (in that order) colour channel gains when AWB is disabled.
> > >
> > > Signed-off-by: Naushir Patuck <naush at raspberrypi.com>
> > > ---
> > >  src/libcamera/control_ids.yaml | 47 ++++++++++++++++++++++++++++++++++
> > >  1 file changed, 47 insertions(+)
> > >
> > > diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
> > > index da1a7b43..9a33094a 100644
> > > --- a/src/libcamera/control_ids.yaml
> > > +++ b/src/libcamera/control_ids.yaml
> > > @@ -143,6 +143,53 @@ controls:
> > >        description: |
> > >          Enable or disable the AWB.
> > >
> > > +  - AwbMode:
> > > +      type: int32_t
> > > +      description: |
> > > +        Specify the range of illumants to use for the AWB algorihtm. The modes
> >
> > /illumants/illuminance/
> > or
> > /illumants/luminance/ ?
> > I'm not quite sure what word you were going for with illumants.
> >
> > s/algorihtm/algorithm/
> >
> > > +        supported are platform specific, and not all modes may be supported.
> > > +      enum:
> > > +        - name: AwbAuto
> > > +          value: 0
> > > +          description: Search over the whole CT range.
> > > +        - name: AwbIncandescent
> > > +          value: 1
> > > +          description: Incandescent AWB lamp mode.
> > > +        - name: AwbTungsten
> > > +          value: 2
> > > +          description: Tungsten AWB lamp mode.
> > > +        - name: AwbFluorescent
> > > +          value: 3
> > > +          description: Fluorescent AWB lamp mode.
> > > +        - name: AwbIndoor
> > > +          value: 4
> > > +          description: Indoor AWB lighting mode.
> > > +        - name: AwbDaylight
> > > +          value: 5
> > > +          description: Daylight AWB lighting mode.
> > > +        - name: AwbCloudy
> > > +          value: 6
> > > +          description: Cloudy AWB lighting mode.
> >
> > I wonder what sort order we should apply to control values like this?
> > I'm sure Laurent would love anything to be alphabetically sorted by a
> > default if nothing else applies, but would there be an expected order to
> > this list otherwise?
>
> I like auto being first, and it fortunately starts with an A ;-) Jokes
> aside, this is a pretty standard configuration parameter for cameras,
> would there be any published standard that we could follow for possible
> values ?
>

The only one that comes to mind would be the Android Camera HAL 3 values:
https://source.android.com/devices/camera/camera3_3Amodes

We have already diverged slightly from that list :)

> > > +        - name: AwbCustom1
> > > +          value: 7
> > > +          description: Custom AWB mode 1.
> > > +        - name: AwbCustom2
> > > +          value: 8
> > > +          description: Custom AWB mode 2.
> > > +        - name: AwbCustom3
> > > +          value: 9
> > > +          description: Custom AWB mode 3.
> > > +        - name: AwbModeMax
> > > +          value: 9
> > > +          description: Maximum allowed value (place any new values above here).
> >
> > Only the same response as the others here,
> >
> > > +
> > > +  - ManualWbGains:
> > > +      type: float
> > > +      description: |
> > > +        Specify a fixed gain parameter for the Red and Blue colour channels,
> > > +        in that order.
> > > +      size: [2]
>
> How do these controls interact with ManualGain ? I wonder if we
> shouldn't merge them all in a 2x2 matrix of red, 2 x green and blue
> gains.

My intention was that ManualGain would be the analogue (and possibly
some digital) gain applied by the sensor in manual AE modes.  Perhaps
to be more explicit I should rename  ManualAnalgoueGain...?  In any
case, this gain value are applied to all bayer colour channels at the
sensor level.

ManualWbGains is used in Manual AWB mode.  If you do not use one of
the presets (AwbIncandescent, AwbTungsten, etc.), you can specify your
own gain to apply (in the ISP pipeline) to fix the white point.  I
don't know if this is a standard thing done by other vendors, but the
white balance is computed as gains applied on the red and blue
channels only.  The green channel(s) is fixed at 1x gain for white
balance adjustment.  If you did want to add further gain to the signal
(i.e. digital gain), it would be then applied equally to all RGB
channels, but in addition to any white balance gains that were applied
to the R and B channels.

However.... to cause more confusion, there is an ISO control that will
likely be added at some point.  I think the convention is that ISO is
a combination of all gains (analogue and digital) applied in the full
imaging pipeline, but not accounting for the white balance gain
adjustments to the R/B channels.

So to finally answer your question, these operations all seem
independent to me, so I do not think we would be able to merge the
controls into one 2x2 matrix.

>
> > > +
> > >    - Brightness:
> > >        type: int32_t
> > >        description: Specify a fixed brightness parameter
>
> --
> Regards,
>
> Laurent Pinchart

Regards,
Naush