[libcamera-devel] [PATCH v3 1/2] libcamera: controls: Add controls for AEC/AGC flicker avoidance

[Kieran Bingham]

Quoting Nicolas Dufresne via libcamera-devel (2023-04-03 20:34:26)
> Le mardi 28 mars 2023 à 09:55 +0100, David Plowman via libcamera-devel a écrit :
> > Flicker is the term used to describe brightness banding or oscillation
> > of images caused typically by artificial lighting driven by a 50 or
> > 60Hz mains supply. We add three controls intended to be used by
> > AEC/AGC algorithms:
> > 
> > AeFlickerMode to enable flicker avoidance.
> > 
> > AeFlickerCustom to set custom flicker periods.
> > 
> > AeFlickerDetected to report any flicker that is currently detected.
> > 
> > Signed-off-by: David Plowman <david.plowman at raspberrypi.com>
> > ---
> >  src/libcamera/control_ids.yaml | 84 +++++++++++++++++++++++++++-------
> >  1 file changed, 67 insertions(+), 17 deletions(-)
> > 
> > diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
> > index adea5f90..b472050c 100644
> > --- a/src/libcamera/control_ids.yaml
> > +++ b/src/libcamera/control_ids.yaml
> > @@ -156,6 +156,73 @@ controls:
> >          control of which features should be automatically adjusted shouldn't
> >          better be handled through a separate AE mode control.
> >  
> > +  - AeFlickerMode:
> 
> Maybe loaded question, since it goes beyound the scope of the patch, but how are
> we suppose to know which controls is an actual control, and which one are
> metadata ? (read-only, possibly on sync with request ?)

a camera exposes a ControlList as camera->controls()
Those (and only those) are the valid controls for that camera.

When a request completes, it can share data in request->metadata() which
is a ControlList of ControlValues that can be interpreted by the
application to see what was, or any control value that the pipeline
handler chooses to put in there really. I think we did look at having
separate 'Metadata' control lists - but it seemed like that would be a
lot of duplication of keys...

Unless you're asking how can we know 'from the documentation'. .. in
which case - currently it's not specifically defined, but we could add a
property to the yaml file?

--
Kieran


> 
> > +      type: int32_t
> > +      description: |
> > +        Set the flicker mode, which determines whether, and how, the AGC/AEC
> > +        algorithm attempts to hide flicker effects caused by the duty cycle of
> > +        artificial lighting.
> > +
> > +        Although implementation dependent, many algorithms for "flicker
> > +        avoidance" work by restricting this exposure time to integer multiples
> > +        of the cycle period, wherever possible.
> > +
> > +        Implementations may not support all of the flicker modes listed below.
> > +
> > +      enum:
> > +        - name: FlickerOff
> > +          value: 0
> > +          description: No flicker avoidance is performed.
> > +        - name: FlickerFreq50Hz
> > +          value: 1
> > +          description: 50Hz flicker avoidance.
> > +            Suppress flicker effects caused by lighting running with a 100Hz
> > +            period (such as that produced by 50Hz mains electricity).
> > +        - name: FlickerFreq60Hz
> > +          value: 2
> > +          description: 60Hz flicker avoidance.
> > +            Suppress flicker effects caused by lighting running with a 120Hz
> > +            period (such as that produced by 60Hz mains electricity).
> > +        - name: FlickerCustom
> > +          value: 3
> > +          description: Custom flicker avoidance.
> > +            Suppress flicker effects caused by lighting running with a period
> > +            specified by the AeFlickerCustom control.
> > +            \sa AeFlickerCustom
> > +        - name: FlickerAuto
> > +          value: 4
> > +          description: Automatic flicker period detection and avoidance.
> > +            The system will automatically determine the most likely value of
> > +            flicker period, and avoid flicker of this frequency.
> > +
> > +  - AeFlickerCustom:
> > +      type: int32_t
> > +      description: Custom flicker period in microseconds.
> > +        This value sets the current flicker period to avoid. It is used when
> > +        AeFlickerMode is set to FlickerCustom.
> > +
> > +        If this control is not available, then the setting of custom flicker
> > +        periods is not supported.
> > +
> > +        \sa AeFlickerMode
> > +
> > +  - AeFlickerDetected:
> > +      type: int32_t
> > +      description: Flicker period detected in microseconds.
> > +        The value reported here indicates the currently detected flicker
> > +        period, or zero if no flicker at all is detected.
> > +
> > +        So in the case of 50Hz mains flicker, the value would be 10000
> > +        (corresponding to 100Hz), or 8333 (120Hz) for 60Hz mains flicker. But
> > +        note that it is not required that any form of scene flicker is detected
> > +        at all, so depending on the implementation, this metadata may just
> > +        report zero or be entirely absent.
> > +
> > +        AeFlickerDetected may also report other values for non-standard flicker
> > +        periods.
> > +
> > +        \sa AeFlickerMode
> > +
> >    - Brightness:
> >        type: float
> >        description: |
> > @@ -843,23 +910,6 @@ controls:
> >            value: 1
> >            description: The lens shading map mode is available.
> >  
> > -  - SceneFlicker:
> > -      type: int32_t
> > -      draft: true
> > -      description: |
> > -       Control to report the detected scene light frequency. Currently
> > -       identical to ANDROID_STATISTICS_SCENE_FLICKER.
> > -      enum:
> > -        - name: SceneFickerOff
> > -          value: 0
> > -          description: No flickering detected.
> > -        - name: SceneFicker50Hz
> > -          value: 1
> > -          description: 50Hz flickering detected.
> > -        - name: SceneFicker60Hz
> > -          value: 2
> > -          description: 60Hz flickering detected.
> > -
> >    - PipelineDepth:
> >        type: int32_t
> >        draft: true
>