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

[Kieran Bingham]

Hi David,

Quoting David Plowman via libcamera-devel (2023-01-25 13:20:18)
> 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 two controls intended to be used by AEC/AGC
> algorithms:
> 
> AeFlickerMode to determine whether flicker avoidance is active or not.
> 
> AeFlickerPeriod to specify a custom flicker period when the period is
> other than 50 or 60Hz.

Oh excellent, this had been flickering in the back of my mind for some
time.

I expect you're going to be providing an implementation for
pipeline/raspberrypi, but this should be easy to add to
pipeline/uvcvideo too with appropriate mapping to:

#define V4L2_CID_POWER_LINE_FREQUENCY   (V4L2_CID_BASE+24)
enum v4l2_power_line_frequency {
        V4L2_CID_POWER_LINE_FREQUENCY_DISABLED  = 0,
        V4L2_CID_POWER_LINE_FREQUENCY_50HZ      = 1,
        V4L2_CID_POWER_LINE_FREQUENCY_60HZ      = 2,
        V4L2_CID_POWER_LINE_FREQUENCY_AUTO      = 3,
};


> Signed-off-by: David Plowman <david.plowman at raspberrypi.com>
> ---
>  src/libcamera/control_ids.yaml | 52 ++++++++++++++++++++++++++++++++++
>  1 file changed, 52 insertions(+)
> 
> diff --git a/src/libcamera/control_ids.yaml b/src/libcamera/control_ids.yaml
> index adea5f90..5e5428ea 100644
> --- a/src/libcamera/control_ids.yaml
> +++ b/src/libcamera/control_ids.yaml
> @@ -14,6 +14,58 @@ controls:
>  
>          \sa ExposureTime AnalogueGain
>  
> +  - AeFlickerMode:
> +      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 the exposure time to integer multiples
> +        of this cycle period, wherever possible.
> +
> +        Implementations may not support all of the flicker modes listed below.

Hrm... this makes me wonder how an application can determine what is
possible, and what we would expect if the application tries to set a
mode that isn't possible on that device.

I don't think we have anything yet at the framework level to be able to
expose which subset of a mode are valid for a given camera...

For example, the UVC pipeline wouldn't support FlickerCustom.

(I don't think that itself blocks the definition of these options though)

> +
> +      enum:
> +        - name: FlickerOff
> +          value: 0
> +          description: No flicker avoidance is performed.
> +        - name: Flicker50Hz
> +          value: 1
> +          description: 50Hz flicker avoidance.
> +            Suppress flicker effects caused by lighting runing with a
> +            100Hz period (such as produced by 50Hz mains electricity).
> +        - name: Flicker60Hz
> +          value: 2
> +          description: 60Hz flicker avoidance.
> +            Suppress flicker effects caused by lighting running with a
> +            120Hz period (such as 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 AeFlickerPeriod.
> +
> +            \sa AeFlickerPeriod
> +        - name: FlickerAuto
> +          value: 4
> +          description: Automatic flicker period detection and avoidance.
> +            The system will automatically determine the most likely value
> +            of the flicker period, and avoid flicker of this frequency.
> +        
> +  - AeFlickerPeriod:
> +      type: int32_t
> +      description: Custom flicker period in microseconds.
> +        This value is taken as the current flicker period to avoid. It
> +        is used when the AeFlickerMode is set to FlickerCustom.
> +
> +        For example, to avoid 50Hz mains flicker, you could set the period
> +        to 10000, corresponding to 10ms (twice the mains frequency), and
> +        AeFlickerMode to FlickerCustom.
> +
> +        \sa AeFlickerMode

I like that applications would be able to control this so precisely,
rather than just the standard 50/60Hz modes.

--
Kieran


> +
>    - AeLocked:
>        type: bool
>        description: |
> -- 
> 2.30.2
>