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

[Laurent Pinchart]

On Mon, Apr 03, 2023 at 09:34:28PM +0100, Kieran Bingham via libcamera-devel wrote:
> 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?

I think we should.

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

-- 
Regards,

Laurent Pinchart