[v5,10/22] ipa: libipa: lux: Convert to "algorithm"
diff mbox series

Message ID 20261116174919.1056403-11-barnabas.pocze@ideasonboard.com
State Superseded
Headers show
Series
  • libcamera: rcar-gen4 + rpp-x1
Related show

Commit Message

Barnabás Pőcze Nov. 16, 2026, 5:49 p.m. UTC
Bring the "Lux" type in-line with other generic algorithm implementations
like `CcmAlgorithm`, `GammaAlgorithm`, etc.

Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
---
 src/ipa/libipa/lux.cpp            | 136 +++++++++++++++++++++---------
 src/ipa/libipa/lux.h              |  36 ++++++--
 src/ipa/rkisp1/algorithms/lux.cpp |  34 +++-----
 src/ipa/rkisp1/algorithms/lux.h   |   4 +-
 src/ipa/rkisp1/ipa_context.h      |   9 +-
 5 files changed, 142 insertions(+), 77 deletions(-)

Comments

Kieran Bingham Nov. 16, 2026, 6:28 p.m. UTC | #1
Quoting Barnabás Pőcze (2026-11-16 17:49:06)
> Bring the "Lux" type in-line with other generic algorithm implementations
> like `CcmAlgorithm`, `GammaAlgorithm`, etc.
> 
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> ---
>  src/ipa/libipa/lux.cpp            | 136 +++++++++++++++++++++---------
>  src/ipa/libipa/lux.h              |  36 ++++++--
>  src/ipa/rkisp1/algorithms/lux.cpp |  34 +++-----
>  src/ipa/rkisp1/algorithms/lux.h   |   4 +-
>  src/ipa/rkisp1/ipa_context.h      |   9 +-
>  5 files changed, 142 insertions(+), 77 deletions(-)
> 
> diff --git a/src/ipa/libipa/lux.cpp b/src/ipa/libipa/lux.cpp
> index 12ba073a11..2d8c621e5c 100644
> --- a/src/ipa/libipa/lux.cpp
> +++ b/src/ipa/libipa/lux.cpp
> @@ -3,22 +3,22 @@
>   * Copyright (C) 2019, Raspberry Pi Ltd
>   * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>
>   *
> - * Helper class that implements lux estimation
> + * libIPA lux estimation
>   */
>  #include "lux.h"
>  
> -#include <algorithm>
> -#include <chrono>
> -
>  #include <libcamera/base/log.h>
>  
> +#include <libcamera/control_ids.h>
> +#include <libcamera/controls.h>
> +
>  #include "libcamera/internal/value_node.h"
>  
>  #include "histogram.h"
>  
>  /**
>   * \file lux.h
> - * \brief Helper class that implements lux estimation
> + * \brief libipa implementation of lux estimation
>   *
>   * Estimating the lux level of an image is a common operation that can for
>   * instance be used to adjust the target Y value in AGC or for Bayesian AWB
> @@ -33,51 +33,82 @@ LOG_DEFINE_CATEGORY(Lux)
>  
>  namespace ipa {
>  
> +namespace lux {
> +
>  /**
> - * \class Lux
> - * \brief Class that implements lux estimation
> + * \class ActiveState
> + * \brief The active state for the algorithm
>   *
> - * IPAs that wish to use lux estimation should create a Lux algorithm module
> - * that lightly wraps this module by providing the platform-specific luminance
> - * histogram. The Lux entry in the tuning file must then precede the algorithms
> - * that depend on the estimated lux value.
> + * \var ActiveState::lux
> + * \brief The latest lux estimation
>   */
>  
>  /**
> - * \var Lux::referenceExposureTime_
> + * \class FrameContext
> + * \brief The frame context for the algorithm
> + *
> + * \var FrameContext::lux
> + * \brief The estimated lux value for the given frame
> + */
> +
> +} /* namespace lux */
> +
> +/**
> + * \class LuxAlgorithm
> + * \brief Lux estimation algorithm
> + *
> + * This algorithm provides lux estimation based on tuning data. IPAs that wish to
> + * use lux estimation should create a Lux algorithm module that lightly wraps this
> + * module by providing the platform-specific luminance histogram. The Lux entry in
> + * the tuning file must then precede the algorithms that depend on the estimated lux
> + * value.
> + */
> +
> +/**
> + * \class LuxAlgorithm::ProcessParams
> + * \brief Parameters for LuxAlgorithm::process()
> + *
> + * \var LuxAlgorithm::ProcessParams::exposureTime
> + * \brief Effective exposure time of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::analogueGain
> + * \brief Effective analogue gain of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::digitalGain
> + * \brief Effective digital gain of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::yHist
> + * \brief Luminance histogram of the frame
> + */
> +
> +/**
> + * \var LuxAlgorithm::referenceExposureTime_
>   * \brief The exposure time of the reference image, in microseconds
>   */
>  
>  /**
> - * \var Lux::referenceAnalogueGain_
> + * \var LuxAlgorithm::referenceAnalogueGain_
>   * \brief The analogue gain of the reference image
>   */
>  
>  /**
> - * \var Lux::referenceDigitalGain_
> + * \var LuxAlgorithm::referenceDigitalGain_
>   * \brief The analogue gain of the reference image
>   */
>  
>  /**
> - * \var Lux::referenceY_
> + * \var LuxAlgorithm::referenceY_
>   * \brief The measured luminance of the reference image, normalized to 1
>   *
>   */
>  
>  /**
> - * \var Lux::referenceLux_
> + * \var LuxAlgorithm::referenceLux_
>   * \brief The estimated lux level of the reference image
>   */
>  
>  /**
> -  * \brief Construct the Lux helper module
> -  */
> -Lux::Lux()
> -{
> -}
> -
> -/**
> - * \brief Parse tuning data
> + * \brief Initialize algorithm and parse tuning data
>   * \param[in] tuningData The ValueNode representing the tuning data
>   *
>   * This function parses tuning data for the common Lux module. It requires
> @@ -95,7 +126,7 @@ Lux::Lux()
>   *
>   * \return 0 on success or a negative error code
>   */
> -int Lux::parseTuningData(const ValueNode &tuningData)
> +int LuxAlgorithm::init(const ValueNode &tuningData)
>  {
>         auto value = tuningData["referenceExposureTime"].get<double>();
>         if (!value) {
> @@ -141,25 +172,50 @@ int Lux::parseTuningData(const ValueNode &tuningData)
>  }
>  
>  /**
> - * \brief Estimate lux given runtime values
> - * \param[in] exposureTime Exposure time applied to the frame
> - * \param[in] aGain Analogue gain applied to the frame
> - * \param[in] dGain Digital gain applied to the frame
> - * \param[in] yHist Histogram from the ISP statistics
> + * \param[in] state The active state
> + * \param[in] frameContext The frame context
>   *
> - * Estimate the lux given the exposure time, gain, and histogram.
> + * This function finalizes \ref lux::FrameContext::lux "frameContext.lux"
> + * based on the latest estimation.
> + */
> +void LuxAlgorithm::prepare(const lux::ActiveState &state, lux::FrameContext &frameContext)
> +{
> +       frameContext.lux = state.lux;
> +}
> +
> +/**
> + * \param[in] state The active state
> + * \param[in] frameContext The frame context
> + * \param[in] params The processing parameters
> + * \param[in] metadata The metadata
>   *
> - * \return Estimated lux value
> + * This function updates the lux estimation based on the luminance histogram
> + * and other parameters of a completed frame, and additionally it also updates
> + * \a metadata for the frame.
>   */
> -double Lux::estimateLux(utils::Duration exposureTime,
> -                       double aGain, double dGain,
> -                       const Histogram &yHist) const
> +void LuxAlgorithm::process(lux::ActiveState &state, const lux::FrameContext &frameContext,
> +                          ControlList &metadata, std::optional<ProcessParams> &&params)
> +{
> +       /*
> +        * Report the lux level used by algorithms to prepare this frame
> +        * not the lux level *of* this frame.
> +        */
> +       metadata.set(controls::Lux, frameContext.lux);
> +
> +       /* If no statistics are available, keep the latest estimation. */
> +       if (!params)
> +               return;
> +
> +       state.lux = estimateLux(*params);
> +}
> +
> +double LuxAlgorithm::estimateLux(const ProcessParams &params) const
>  {
> -       double currentY = yHist.interQuantileMean(0, 1);
> -       double exposureTimeRatio = referenceExposureTime_ / exposureTime;
> -       double aGainRatio = referenceAnalogueGain_ / aGain;
> -       double dGainRatio = referenceDigitalGain_ / dGain;
> -       double yRatio = (currentY / yHist.bins()) / referenceY_;
> +       double currentY = params.yHist.interQuantileMean(0, 1);
> +       double exposureTimeRatio = referenceExposureTime_ / params.exposureTime;
> +       double aGainRatio = referenceAnalogueGain_ / params.analogueGain;
> +       double dGainRatio = referenceDigitalGain_ / params.digitalGain;
> +       double yRatio = (currentY / params.yHist.bins()) / referenceY_;
>  
>         double estimatedLux = exposureTimeRatio * aGainRatio * dGainRatio *
>                               yRatio * referenceLux_;
> diff --git a/src/ipa/libipa/lux.h b/src/ipa/libipa/lux.h
> index b6837ab729..5bce7855ad 100644
> --- a/src/ipa/libipa/lux.h
> +++ b/src/ipa/libipa/lux.h
> @@ -8,27 +8,49 @@
>  
>  #pragma once
>  
> +#include <optional>
> +
>  #include <libcamera/base/utils.h>
>  
>  namespace libcamera {
>  
> +class ControlList;
>  class ValueNode;
>  
>  namespace ipa {
>  
>  class Histogram;
>  
> -class Lux
> +namespace lux {
> +
> +struct ActiveState {
> +       double lux;
> +};
> +
> +struct FrameContext {
> +       double lux;
> +};
> +
> +} /* namespace lux */
> +
> +class LuxAlgorithm
>  {
>  public:
> -       Lux();
> -
> -       int parseTuningData(const ValueNode &tuningData);
> -       double estimateLux(utils::Duration exposureTime,
> -                          double aGain, double dGain,
> -                          const Histogram &yHist) const;
> +       struct ProcessParams {
> +               utils::Duration exposureTime;
> +               double analogueGain;
> +               double digitalGain;
> +               const Histogram &yHist;
> +       };
> +
> +       int init(const ValueNode &tuningData);
> +       void prepare(const lux::ActiveState &state, lux::FrameContext &frameContext);
> +       void process(lux::ActiveState &state, const lux::FrameContext &frameContext,
> +                    ControlList &metadata, std::optional<ProcessParams> &&params);
>  
>  private:
> +       double estimateLux(const ProcessParams &params) const;
> +
>         utils::Duration referenceExposureTime_;
>         double referenceAnalogueGain_;
>         double referenceDigitalGain_;
> diff --git a/src/ipa/rkisp1/algorithms/lux.cpp b/src/ipa/rkisp1/algorithms/lux.cpp
> index ce6928a55d..68ad41d6cf 100644
> --- a/src/ipa/rkisp1/algorithms/lux.cpp
> +++ b/src/ipa/rkisp1/algorithms/lux.cpp
> @@ -31,19 +31,12 @@ namespace ipa::rkisp1::algorithms {
>   * other algorithms (such as AGC) to use.
>   */
>  
> -/**
> - * \brief Construct an rkisp1 Lux algo module
> - */
> -Lux::Lux()
> -{
> -}
> -
>  /**
>   * \copydoc libcamera::ipa::Algorithm::init
>   */
>  int Lux::init([[maybe_unused]] IPAContext &context, const ValueNode &tuningData)
>  {
> -       return lux_.parseTuningData(tuningData);
> +       return lux_.init(tuningData);
>  }
>  
>  /**
> @@ -53,7 +46,7 @@ void Lux::prepare(IPAContext &context, [[maybe_unused]] const uint32_t frame,
>                   IPAFrameContext &frameContext,
>                   [[maybe_unused]] RkISP1Params *params)
>  {
> -       frameContext.lux.lux = context.activeState.lux.lux;
> +       lux_.prepare(context.activeState.lux, frameContext.lux);
>  }
>  
>  /**
> @@ -65,25 +58,24 @@ void Lux::process(IPAContext &context,
>                   const rkisp1_stat_buffer *stats,
>                   ControlList &metadata)
>  {
> -       /*
> -        * Report the lux level used by algorithms to prepare this frame
> -        * not the lux level *of* this frame.
> -        */
> -       metadata.set(controls::Lux, frameContext.lux.lux);

I like this a lot because now this implemetation specific detail will
not be copied into each instance.


> -
> -       if (!stats)
> +       if (!stats) {
> +               lux_.process(context.activeState.lux, frameContext.lux, metadata, {});
>                 return;
> -
> -       utils::Duration exposureTime = context.configuration.agc.lineDuration *
> -                                      frameContext.sensor.exposure;
> -       double gain = frameContext.sensor.gain;
> +       }
>  
>         /* \todo Deduplicate the histogram calculation from AGC */
>         const rkisp1_cif_isp_stat *params = &stats->params;
>         Histogram yHist({ params->hist.hist_bins, context.hw.numHistogramBins },
>                         [](uint32_t x) { return x >> 4; });
>  
> -       context.activeState.lux.lux = lux_.estimateLux(exposureTime, gain, 1.0, yHist);
> +       lux_.process(context.activeState.lux, frameContext.lux, metadata,
> +                    { {
> +                            .exposureTime = context.configuration.agc.lineDuration *
> +                                            frameContext.sensor.exposure,
> +                            .analogueGain = frameContext.sensor.gain,
> +                            .digitalGain = 1,
> +                            .yHist = yHist,
> +                    } });
>  }
>  
>  REGISTER_IPA_ALGORITHM(Lux, "Lux")
> diff --git a/src/ipa/rkisp1/algorithms/lux.h b/src/ipa/rkisp1/algorithms/lux.h
> index 8cb35cbae2..f7d2581e57 100644
> --- a/src/ipa/rkisp1/algorithms/lux.h
> +++ b/src/ipa/rkisp1/algorithms/lux.h
> @@ -20,8 +20,6 @@ namespace ipa::rkisp1::algorithms {
>  class Lux : public Algorithm
>  {
>  public:
> -       Lux();
> -
>         int init(IPAContext &context, const ValueNode &tuningData) override;
>         void prepare(IPAContext &context, const uint32_t frame,
>                      IPAFrameContext &frameContext,
> @@ -32,7 +30,7 @@ public:
>                      ControlList &metadata) override;
>  
>  private:
> -       ipa::Lux lux_;
> +       ipa::LuxAlgorithm lux_;
>  };
>  
>  } /* namespace ipa::rkisp1::algorithms */
> diff --git a/src/ipa/rkisp1/ipa_context.h b/src/ipa/rkisp1/ipa_context.h
> index a6db004c16..b34ea53406 100644
> --- a/src/ipa/rkisp1/ipa_context.h
> +++ b/src/ipa/rkisp1/ipa_context.h
> @@ -32,6 +32,7 @@
>  #include "libipa/fixedpoint.h"
>  #include "libipa/gamma.h"
>  #include "libipa/lsc.h"
> +#include "libipa/lux.h"
>  
>  namespace libcamera {
>  
> @@ -105,9 +106,7 @@ struct IPAActiveState {
>  
>         ipa::gamma::ActiveState gamma;
>  
> -       struct {
> -               double lux;
> -       } lux;
> +       ipa::lux::ActiveState lux;
>  
>         struct {
>                 controls::WdrModeEnum mode;
> @@ -162,9 +161,7 @@ struct IPAFrameContext : public FrameContext {
>  
>         ipa::ccm::FrameContext ccm;
>  
> -       struct {
> -               double lux;
> -       } lux;
> +       ipa::lux::FrameContext lux;

And now these will be more consistent.


Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

>  
>         struct {
>                 controls::WdrModeEnum mode;
> -- 
> 2.56.1
>
Jacopo Mondi Nov. 17, 2026, 8:49 a.m. UTC | #2
Hi Barnabás

On Mon, Nov 16, 2026 at 06:49:06PM +0100, Barnabás Pőcze wrote:
> Bring the "Lux" type in-line with other generic algorithm implementations
> like `CcmAlgorithm`, `GammaAlgorithm`, etc.
>
> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> ---
>  src/ipa/libipa/lux.cpp            | 136 +++++++++++++++++++++---------
>  src/ipa/libipa/lux.h              |  36 ++++++--
>  src/ipa/rkisp1/algorithms/lux.cpp |  34 +++-----
>  src/ipa/rkisp1/algorithms/lux.h   |   4 +-
>  src/ipa/rkisp1/ipa_context.h      |   9 +-
>  5 files changed, 142 insertions(+), 77 deletions(-)
>
> diff --git a/src/ipa/libipa/lux.cpp b/src/ipa/libipa/lux.cpp
> index 12ba073a11..2d8c621e5c 100644
> --- a/src/ipa/libipa/lux.cpp
> +++ b/src/ipa/libipa/lux.cpp
> @@ -3,22 +3,22 @@
>   * Copyright (C) 2019, Raspberry Pi Ltd
>   * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>
>   *
> - * Helper class that implements lux estimation
> + * libIPA lux estimation
>   */
>  #include "lux.h"
>
> -#include <algorithm>
> -#include <chrono>
> -
>  #include <libcamera/base/log.h>
>
> +#include <libcamera/control_ids.h>
> +#include <libcamera/controls.h>
> +
>  #include "libcamera/internal/value_node.h"
>
>  #include "histogram.h"
>
>  /**
>   * \file lux.h
> - * \brief Helper class that implements lux estimation
> + * \brief libipa implementation of lux estimation
>   *
>   * Estimating the lux level of an image is a common operation that can for
>   * instance be used to adjust the target Y value in AGC or for Bayesian AWB
> @@ -33,51 +33,82 @@ LOG_DEFINE_CATEGORY(Lux)
>
>  namespace ipa {
>
> +namespace lux {
> +
>  /**
> - * \class Lux
> - * \brief Class that implements lux estimation
> + * \class ActiveState
> + * \brief The active state for the algorithm
>   *
> - * IPAs that wish to use lux estimation should create a Lux algorithm module
> - * that lightly wraps this module by providing the platform-specific luminance
> - * histogram. The Lux entry in the tuning file must then precede the algorithms
> - * that depend on the estimated lux value.
> + * \var ActiveState::lux
> + * \brief The latest lux estimation
>   */
>
>  /**
> - * \var Lux::referenceExposureTime_
> + * \class FrameContext
> + * \brief The frame context for the algorithm
> + *
> + * \var FrameContext::lux
> + * \brief The estimated lux value for the given frame
> + */
> +
> +} /* namespace lux */
> +
> +/**
> + * \class LuxAlgorithm
> + * \brief Lux estimation algorithm
> + *
> + * This algorithm provides lux estimation based on tuning data. IPAs that wish to
> + * use lux estimation should create a Lux algorithm module that lightly wraps this
> + * module by providing the platform-specific luminance histogram. The Lux entry in
> + * the tuning file must then precede the algorithms that depend on the estimated lux
> + * value.
> + */
> +
> +/**
> + * \class LuxAlgorithm::ProcessParams
> + * \brief Parameters for LuxAlgorithm::process()
> + *
> + * \var LuxAlgorithm::ProcessParams::exposureTime
> + * \brief Effective exposure time of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::analogueGain
> + * \brief Effective analogue gain of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::digitalGain
> + * \brief Effective digital gain of the frame
> + *
> + * \var LuxAlgorithm::ProcessParams::yHist
> + * \brief Luminance histogram of the frame
> + */
> +
> +/**
> + * \var LuxAlgorithm::referenceExposureTime_
>   * \brief The exposure time of the reference image, in microseconds
>   */
>
>  /**
> - * \var Lux::referenceAnalogueGain_
> + * \var LuxAlgorithm::referenceAnalogueGain_
>   * \brief The analogue gain of the reference image
>   */
>
>  /**
> - * \var Lux::referenceDigitalGain_
> + * \var LuxAlgorithm::referenceDigitalGain_
>   * \brief The analogue gain of the reference image
>   */
>
>  /**
> - * \var Lux::referenceY_
> + * \var LuxAlgorithm::referenceY_
>   * \brief The measured luminance of the reference image, normalized to 1
>   *
>   */
>
>  /**
> - * \var Lux::referenceLux_
> + * \var LuxAlgorithm::referenceLux_
>   * \brief The estimated lux level of the reference image
>   */
>
>  /**
> -  * \brief Construct the Lux helper module
> -  */
> -Lux::Lux()
> -{
> -}
> -
> -/**
> - * \brief Parse tuning data
> + * \brief Initialize algorithm and parse tuning data
>   * \param[in] tuningData The ValueNode representing the tuning data
>   *
>   * This function parses tuning data for the common Lux module. It requires
> @@ -95,7 +126,7 @@ Lux::Lux()
>   *
>   * \return 0 on success or a negative error code
>   */
> -int Lux::parseTuningData(const ValueNode &tuningData)
> +int LuxAlgorithm::init(const ValueNode &tuningData)
>  {
>  	auto value = tuningData["referenceExposureTime"].get<double>();
>  	if (!value) {
> @@ -141,25 +172,50 @@ int Lux::parseTuningData(const ValueNode &tuningData)
>  }
>
>  /**
> - * \brief Estimate lux given runtime values
> - * \param[in] exposureTime Exposure time applied to the frame
> - * \param[in] aGain Analogue gain applied to the frame
> - * \param[in] dGain Digital gain applied to the frame
> - * \param[in] yHist Histogram from the ISP statistics
> + * \param[in] state The active state
> + * \param[in] frameContext The frame context
>   *
> - * Estimate the lux given the exposure time, gain, and histogram.
> + * This function finalizes \ref lux::FrameContext::lux "frameContext.lux"
> + * based on the latest estimation.
> + */
> +void LuxAlgorithm::prepare(const lux::ActiveState &state, lux::FrameContext &frameContext)
> +{
> +	frameContext.lux = state.lux;
> +}
> +
> +/**
> + * \param[in] state The active state
> + * \param[in] frameContext The frame context
> + * \param[in] params The processing parameters
> + * \param[in] metadata The metadata
>   *
> - * \return Estimated lux value
> + * This function updates the lux estimation based on the luminance histogram
> + * and other parameters of a completed frame, and additionally it also updates
> + * \a metadata for the frame.
>   */
> -double Lux::estimateLux(utils::Duration exposureTime,
> -			double aGain, double dGain,
> -			const Histogram &yHist) const
> +void LuxAlgorithm::process(lux::ActiveState &state, const lux::FrameContext &frameContext,
> +			   ControlList &metadata, std::optional<ProcessParams> &&params)

Why && ?

> +{
> +	/*
> +	 * Report the lux level used by algorithms to prepare this frame
> +	 * not the lux level *of* this frame.
> +	 */
> +	metadata.set(controls::Lux, frameContext.lux);
> +
> +	/* If no statistics are available, keep the latest estimation. */
> +	if (!params)
> +		return;
> +
> +	state.lux = estimateLux(*params);
> +}
> +
> +double LuxAlgorithm::estimateLux(const ProcessParams &params) const
>  {
> -	double currentY = yHist.interQuantileMean(0, 1);
> -	double exposureTimeRatio = referenceExposureTime_ / exposureTime;
> -	double aGainRatio = referenceAnalogueGain_ / aGain;
> -	double dGainRatio = referenceDigitalGain_ / dGain;
> -	double yRatio = (currentY / yHist.bins()) / referenceY_;
> +	double currentY = params.yHist.interQuantileMean(0, 1);
> +	double exposureTimeRatio = referenceExposureTime_ / params.exposureTime;
> +	double aGainRatio = referenceAnalogueGain_ / params.analogueGain;
> +	double dGainRatio = referenceDigitalGain_ / params.digitalGain;
> +	double yRatio = (currentY / params.yHist.bins()) / referenceY_;
>
>  	double estimatedLux = exposureTimeRatio * aGainRatio * dGainRatio *
>  			      yRatio * referenceLux_;
> diff --git a/src/ipa/libipa/lux.h b/src/ipa/libipa/lux.h
> index b6837ab729..5bce7855ad 100644
> --- a/src/ipa/libipa/lux.h
> +++ b/src/ipa/libipa/lux.h
> @@ -8,27 +8,49 @@
>
>  #pragma once
>
> +#include <optional>
> +
>  #include <libcamera/base/utils.h>
>
>  namespace libcamera {
>
> +class ControlList;
>  class ValueNode;
>
>  namespace ipa {
>
>  class Histogram;
>
> -class Lux
> +namespace lux {
> +
> +struct ActiveState {
> +	double lux;
> +};
> +
> +struct FrameContext {
> +	double lux;
> +};
> +
> +} /* namespace lux */
> +
> +class LuxAlgorithm
>  {
>  public:
> -	Lux();
> -
> -	int parseTuningData(const ValueNode &tuningData);
> -	double estimateLux(utils::Duration exposureTime,
> -			   double aGain, double dGain,
> -			   const Histogram &yHist) const;
> +	struct ProcessParams {
> +		utils::Duration exposureTime;
> +		double analogueGain;
> +		double digitalGain;
> +		const Histogram &yHist;
> +	};
> +
> +	int init(const ValueNode &tuningData);
> +	void prepare(const lux::ActiveState &state, lux::FrameContext &frameContext);
> +	void process(lux::ActiveState &state, const lux::FrameContext &frameContext,
> +		     ControlList &metadata, std::optional<ProcessParams> &&params);
>
>  private:
> +	double estimateLux(const ProcessParams &params) const;
> +
>  	utils::Duration referenceExposureTime_;
>  	double referenceAnalogueGain_;
>  	double referenceDigitalGain_;
> diff --git a/src/ipa/rkisp1/algorithms/lux.cpp b/src/ipa/rkisp1/algorithms/lux.cpp
> index ce6928a55d..68ad41d6cf 100644
> --- a/src/ipa/rkisp1/algorithms/lux.cpp
> +++ b/src/ipa/rkisp1/algorithms/lux.cpp
> @@ -31,19 +31,12 @@ namespace ipa::rkisp1::algorithms {
>   * other algorithms (such as AGC) to use.
>   */
>
> -/**
> - * \brief Construct an rkisp1 Lux algo module
> - */
> -Lux::Lux()
> -{
> -}
> -
>  /**
>   * \copydoc libcamera::ipa::Algorithm::init
>   */
>  int Lux::init([[maybe_unused]] IPAContext &context, const ValueNode &tuningData)
>  {
> -	return lux_.parseTuningData(tuningData);
> +	return lux_.init(tuningData);
>  }
>
>  /**
> @@ -53,7 +46,7 @@ void Lux::prepare(IPAContext &context, [[maybe_unused]] const uint32_t frame,
>  		  IPAFrameContext &frameContext,
>  		  [[maybe_unused]] RkISP1Params *params)
>  {
> -	frameContext.lux.lux = context.activeState.lux.lux;
> +	lux_.prepare(context.activeState.lux, frameContext.lux);
>  }
>
>  /**
> @@ -65,25 +58,24 @@ void Lux::process(IPAContext &context,
>  		  const rkisp1_stat_buffer *stats,
>  		  ControlList &metadata)
>  {
> -	/*
> -	 * Report the lux level used by algorithms to prepare this frame
> -	 * not the lux level *of* this frame.
> -	 */
> -	metadata.set(controls::Lux, frameContext.lux.lux);
> -
> -	if (!stats)
> +	if (!stats) {
> +		lux_.process(context.activeState.lux, frameContext.lux, metadata, {});
>  		return;
> -
> -	utils::Duration exposureTime = context.configuration.agc.lineDuration *
> -				       frameContext.sensor.exposure;
> -	double gain = frameContext.sensor.gain;
> +	}
>
>  	/* \todo Deduplicate the histogram calculation from AGC */
>  	const rkisp1_cif_isp_stat *params = &stats->params;
>  	Histogram yHist({ params->hist.hist_bins, context.hw.numHistogramBins },
>  			[](uint32_t x) { return x >> 4; });
>
> -	context.activeState.lux.lux = lux_.estimateLux(exposureTime, gain, 1.0, yHist);
> +	lux_.process(context.activeState.lux, frameContext.lux, metadata,
> +		     { {
> +			     .exposureTime = context.configuration.agc.lineDuration *
> +					     frameContext.sensor.exposure,
> +			     .analogueGain = frameContext.sensor.gain,
> +			     .digitalGain = 1,
> +			     .yHist = yHist,
> +		     } });

I wonder how useful it is to use an optional<>. In which case IPA
modules call process() with std::nullopt ? And in case they do, can't
they just skip calling process() ?

>  }
>
>  REGISTER_IPA_ALGORITHM(Lux, "Lux")
> diff --git a/src/ipa/rkisp1/algorithms/lux.h b/src/ipa/rkisp1/algorithms/lux.h
> index 8cb35cbae2..f7d2581e57 100644
> --- a/src/ipa/rkisp1/algorithms/lux.h
> +++ b/src/ipa/rkisp1/algorithms/lux.h
> @@ -20,8 +20,6 @@ namespace ipa::rkisp1::algorithms {
>  class Lux : public Algorithm
>  {
>  public:
> -	Lux();
> -
>  	int init(IPAContext &context, const ValueNode &tuningData) override;
>  	void prepare(IPAContext &context, const uint32_t frame,
>  		     IPAFrameContext &frameContext,
> @@ -32,7 +30,7 @@ public:
>  		     ControlList &metadata) override;
>
>  private:
> -	ipa::Lux lux_;
> +	ipa::LuxAlgorithm lux_;
>  };
>
>  } /* namespace ipa::rkisp1::algorithms */
> diff --git a/src/ipa/rkisp1/ipa_context.h b/src/ipa/rkisp1/ipa_context.h
> index a6db004c16..b34ea53406 100644
> --- a/src/ipa/rkisp1/ipa_context.h
> +++ b/src/ipa/rkisp1/ipa_context.h
> @@ -32,6 +32,7 @@
>  #include "libipa/fixedpoint.h"
>  #include "libipa/gamma.h"
>  #include "libipa/lsc.h"
> +#include "libipa/lux.h"
>
>  namespace libcamera {
>
> @@ -105,9 +106,7 @@ struct IPAActiveState {
>
>  	ipa::gamma::ActiveState gamma;
>
> -	struct {
> -		double lux;
> -	} lux;
> +	ipa::lux::ActiveState lux;
>
>  	struct {
>  		controls::WdrModeEnum mode;
> @@ -162,9 +161,7 @@ struct IPAFrameContext : public FrameContext {
>
>  	ipa::ccm::FrameContext ccm;
>
> -	struct {
> -		double lux;
> -	} lux;
> +	ipa::lux::FrameContext lux;

In any case, this is a good addition
Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>

>
>  	struct {
>  		controls::WdrModeEnum mode;
> --
> 2.56.1
>
Barnabás Pőcze Nov. 17, 2026, 12:43 p.m. UTC | #3
2026. 11. 17. 9:49 keltezéssel, Jacopo Mondi írta:
> Hi Barnabás
> 
> On Mon, Nov 16, 2026 at 06:49:06PM +0100, Barnabás Pőcze wrote:
>> Bring the "Lux" type in-line with other generic algorithm implementations
>> like `CcmAlgorithm`, `GammaAlgorithm`, etc.
>>
>> Signed-off-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
>> ---
>>   src/ipa/libipa/lux.cpp            | 136 +++++++++++++++++++++---------
>>   src/ipa/libipa/lux.h              |  36 ++++++--
>>   src/ipa/rkisp1/algorithms/lux.cpp |  34 +++-----
>>   src/ipa/rkisp1/algorithms/lux.h   |   4 +-
>>   src/ipa/rkisp1/ipa_context.h      |   9 +-
>>   5 files changed, 142 insertions(+), 77 deletions(-)
>>
>> diff --git a/src/ipa/libipa/lux.cpp b/src/ipa/libipa/lux.cpp
>> index 12ba073a11..2d8c621e5c 100644
>> --- a/src/ipa/libipa/lux.cpp
>> +++ b/src/ipa/libipa/lux.cpp
>> @@ -3,22 +3,22 @@
>>    * Copyright (C) 2019, Raspberry Pi Ltd
>>    * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>
>>    *
>> - * Helper class that implements lux estimation
>> + * libIPA lux estimation
>>    */
>>   #include "lux.h"
>>
>> -#include <algorithm>
>> -#include <chrono>
>> -
>>   #include <libcamera/base/log.h>
>>
>> +#include <libcamera/control_ids.h>
>> +#include <libcamera/controls.h>
>> +
>>   #include "libcamera/internal/value_node.h"
>>
>>   #include "histogram.h"
>>
>>   /**
>>    * \file lux.h
>> - * \brief Helper class that implements lux estimation
>> + * \brief libipa implementation of lux estimation
>>    *
>>    * Estimating the lux level of an image is a common operation that can for
>>    * instance be used to adjust the target Y value in AGC or for Bayesian AWB
>> @@ -33,51 +33,82 @@ LOG_DEFINE_CATEGORY(Lux)
>>
>>   namespace ipa {
>>
>> +namespace lux {
>> +
>>   /**
>> - * \class Lux
>> - * \brief Class that implements lux estimation
>> + * \class ActiveState
>> + * \brief The active state for the algorithm
>>    *
>> - * IPAs that wish to use lux estimation should create a Lux algorithm module
>> - * that lightly wraps this module by providing the platform-specific luminance
>> - * histogram. The Lux entry in the tuning file must then precede the algorithms
>> - * that depend on the estimated lux value.
>> + * \var ActiveState::lux
>> + * \brief The latest lux estimation
>>    */
>>
>>   /**
>> - * \var Lux::referenceExposureTime_
>> + * \class FrameContext
>> + * \brief The frame context for the algorithm
>> + *
>> + * \var FrameContext::lux
>> + * \brief The estimated lux value for the given frame
>> + */
>> +
>> +} /* namespace lux */
>> +
>> +/**
>> + * \class LuxAlgorithm
>> + * \brief Lux estimation algorithm
>> + *
>> + * This algorithm provides lux estimation based on tuning data. IPAs that wish to
>> + * use lux estimation should create a Lux algorithm module that lightly wraps this
>> + * module by providing the platform-specific luminance histogram. The Lux entry in
>> + * the tuning file must then precede the algorithms that depend on the estimated lux
>> + * value.
>> + */
>> +
>> +/**
>> + * \class LuxAlgorithm::ProcessParams
>> + * \brief Parameters for LuxAlgorithm::process()
>> + *
>> + * \var LuxAlgorithm::ProcessParams::exposureTime
>> + * \brief Effective exposure time of the frame
>> + *
>> + * \var LuxAlgorithm::ProcessParams::analogueGain
>> + * \brief Effective analogue gain of the frame
>> + *
>> + * \var LuxAlgorithm::ProcessParams::digitalGain
>> + * \brief Effective digital gain of the frame
>> + *
>> + * \var LuxAlgorithm::ProcessParams::yHist
>> + * \brief Luminance histogram of the frame
>> + */
>> +
>> +/**
>> + * \var LuxAlgorithm::referenceExposureTime_
>>    * \brief The exposure time of the reference image, in microseconds
>>    */
>>
>>   /**
>> - * \var Lux::referenceAnalogueGain_
>> + * \var LuxAlgorithm::referenceAnalogueGain_
>>    * \brief The analogue gain of the reference image
>>    */
>>
>>   /**
>> - * \var Lux::referenceDigitalGain_
>> + * \var LuxAlgorithm::referenceDigitalGain_
>>    * \brief The analogue gain of the reference image
>>    */
>>
>>   /**
>> - * \var Lux::referenceY_
>> + * \var LuxAlgorithm::referenceY_
>>    * \brief The measured luminance of the reference image, normalized to 1
>>    *
>>    */
>>
>>   /**
>> - * \var Lux::referenceLux_
>> + * \var LuxAlgorithm::referenceLux_
>>    * \brief The estimated lux level of the reference image
>>    */
>>
>>   /**
>> -  * \brief Construct the Lux helper module
>> -  */
>> -Lux::Lux()
>> -{
>> -}
>> -
>> -/**
>> - * \brief Parse tuning data
>> + * \brief Initialize algorithm and parse tuning data
>>    * \param[in] tuningData The ValueNode representing the tuning data
>>    *
>>    * This function parses tuning data for the common Lux module. It requires
>> @@ -95,7 +126,7 @@ Lux::Lux()
>>    *
>>    * \return 0 on success or a negative error code
>>    */
>> -int Lux::parseTuningData(const ValueNode &tuningData)
>> +int LuxAlgorithm::init(const ValueNode &tuningData)
>>   {
>>   	auto value = tuningData["referenceExposureTime"].get<double>();
>>   	if (!value) {
>> @@ -141,25 +172,50 @@ int Lux::parseTuningData(const ValueNode &tuningData)
>>   }
>>
>>   /**
>> - * \brief Estimate lux given runtime values
>> - * \param[in] exposureTime Exposure time applied to the frame
>> - * \param[in] aGain Analogue gain applied to the frame
>> - * \param[in] dGain Digital gain applied to the frame
>> - * \param[in] yHist Histogram from the ISP statistics
>> + * \param[in] state The active state
>> + * \param[in] frameContext The frame context
>>    *
>> - * Estimate the lux given the exposure time, gain, and histogram.
>> + * This function finalizes \ref lux::FrameContext::lux "frameContext.lux"
>> + * based on the latest estimation.
>> + */
>> +void LuxAlgorithm::prepare(const lux::ActiveState &state, lux::FrameContext &frameContext)
>> +{
>> +	frameContext.lux = state.lux;
>> +}
>> +
>> +/**
>> + * \param[in] state The active state
>> + * \param[in] frameContext The frame context
>> + * \param[in] params The processing parameters
>> + * \param[in] metadata The metadata
>>    *
>> - * \return Estimated lux value
>> + * This function updates the lux estimation based on the luminance histogram
>> + * and other parameters of a completed frame, and additionally it also updates
>> + * \a metadata for the frame.
>>    */
>> -double Lux::estimateLux(utils::Duration exposureTime,
>> -			double aGain, double dGain,
>> -			const Histogram &yHist) const
>> +void LuxAlgorithm::process(lux::ActiveState &state, const lux::FrameContext &frameContext,
>> +			   ControlList &metadata, std::optional<ProcessParams> &&params)
> 
> Why && ?

No particular reason, it could be `const &` as well. It was just my preference
since `AgcAlgorithm` also uses `&&` (although it has a good reason to do so).


> 
>> +{
>> +	/*
>> +	 * Report the lux level used by algorithms to prepare this frame
>> +	 * not the lux level *of* this frame.
>> +	 */
>> +	metadata.set(controls::Lux, frameContext.lux);
>> +
>> +	/* If no statistics are available, keep the latest estimation. */
>> +	if (!params)
>> +		return;
>> +
>> +	state.lux = estimateLux(*params);
>> +}
>> +
>> +double LuxAlgorithm::estimateLux(const ProcessParams &params) const
>>   {
>> -	double currentY = yHist.interQuantileMean(0, 1);
>> -	double exposureTimeRatio = referenceExposureTime_ / exposureTime;
>> -	double aGainRatio = referenceAnalogueGain_ / aGain;
>> -	double dGainRatio = referenceDigitalGain_ / dGain;
>> -	double yRatio = (currentY / yHist.bins()) / referenceY_;
>> +	double currentY = params.yHist.interQuantileMean(0, 1);
>> +	double exposureTimeRatio = referenceExposureTime_ / params.exposureTime;
>> +	double aGainRatio = referenceAnalogueGain_ / params.analogueGain;
>> +	double dGainRatio = referenceDigitalGain_ / params.digitalGain;
>> +	double yRatio = (currentY / params.yHist.bins()) / referenceY_;
>>
>>   	double estimatedLux = exposureTimeRatio * aGainRatio * dGainRatio *
>>   			      yRatio * referenceLux_;
>> diff --git a/src/ipa/libipa/lux.h b/src/ipa/libipa/lux.h
>> index b6837ab729..5bce7855ad 100644
>> --- a/src/ipa/libipa/lux.h
>> +++ b/src/ipa/libipa/lux.h
>> @@ -8,27 +8,49 @@
>>
>>   #pragma once
>>
>> +#include <optional>
>> +
>>   #include <libcamera/base/utils.h>
>>
>>   namespace libcamera {
>>
>> +class ControlList;
>>   class ValueNode;
>>
>>   namespace ipa {
>>
>>   class Histogram;
>>
>> -class Lux
>> +namespace lux {
>> +
>> +struct ActiveState {
>> +	double lux;
>> +};
>> +
>> +struct FrameContext {
>> +	double lux;
>> +};
>> +
>> +} /* namespace lux */
>> +
>> +class LuxAlgorithm
>>   {
>>   public:
>> -	Lux();
>> -
>> -	int parseTuningData(const ValueNode &tuningData);
>> -	double estimateLux(utils::Duration exposureTime,
>> -			   double aGain, double dGain,
>> -			   const Histogram &yHist) const;
>> +	struct ProcessParams {
>> +		utils::Duration exposureTime;
>> +		double analogueGain;
>> +		double digitalGain;
>> +		const Histogram &yHist;
>> +	};
>> +
>> +	int init(const ValueNode &tuningData);
>> +	void prepare(const lux::ActiveState &state, lux::FrameContext &frameContext);
>> +	void process(lux::ActiveState &state, const lux::FrameContext &frameContext,
>> +		     ControlList &metadata, std::optional<ProcessParams> &&params);
>>
>>   private:
>> +	double estimateLux(const ProcessParams &params) const;
>> +
>>   	utils::Duration referenceExposureTime_;
>>   	double referenceAnalogueGain_;
>>   	double referenceDigitalGain_;
>> diff --git a/src/ipa/rkisp1/algorithms/lux.cpp b/src/ipa/rkisp1/algorithms/lux.cpp
>> index ce6928a55d..68ad41d6cf 100644
>> --- a/src/ipa/rkisp1/algorithms/lux.cpp
>> +++ b/src/ipa/rkisp1/algorithms/lux.cpp
>> @@ -31,19 +31,12 @@ namespace ipa::rkisp1::algorithms {
>>    * other algorithms (such as AGC) to use.
>>    */
>>
>> -/**
>> - * \brief Construct an rkisp1 Lux algo module
>> - */
>> -Lux::Lux()
>> -{
>> -}
>> -
>>   /**
>>    * \copydoc libcamera::ipa::Algorithm::init
>>    */
>>   int Lux::init([[maybe_unused]] IPAContext &context, const ValueNode &tuningData)
>>   {
>> -	return lux_.parseTuningData(tuningData);
>> +	return lux_.init(tuningData);
>>   }
>>
>>   /**
>> @@ -53,7 +46,7 @@ void Lux::prepare(IPAContext &context, [[maybe_unused]] const uint32_t frame,
>>   		  IPAFrameContext &frameContext,
>>   		  [[maybe_unused]] RkISP1Params *params)
>>   {
>> -	frameContext.lux.lux = context.activeState.lux.lux;
>> +	lux_.prepare(context.activeState.lux, frameContext.lux);
>>   }
>>
>>   /**
>> @@ -65,25 +58,24 @@ void Lux::process(IPAContext &context,
>>   		  const rkisp1_stat_buffer *stats,
>>   		  ControlList &metadata)
>>   {
>> -	/*
>> -	 * Report the lux level used by algorithms to prepare this frame
>> -	 * not the lux level *of* this frame.
>> -	 */
>> -	metadata.set(controls::Lux, frameContext.lux.lux);
>> -
>> -	if (!stats)
>> +	if (!stats) {
>> +		lux_.process(context.activeState.lux, frameContext.lux, metadata, {});
>>   		return;
>> -
>> -	utils::Duration exposureTime = context.configuration.agc.lineDuration *
>> -				       frameContext.sensor.exposure;
>> -	double gain = frameContext.sensor.gain;
>> +	}
>>
>>   	/* \todo Deduplicate the histogram calculation from AGC */
>>   	const rkisp1_cif_isp_stat *params = &stats->params;
>>   	Histogram yHist({ params->hist.hist_bins, context.hw.numHistogramBins },
>>   			[](uint32_t x) { return x >> 4; });
>>
>> -	context.activeState.lux.lux = lux_.estimateLux(exposureTime, gain, 1.0, yHist);
>> +	lux_.process(context.activeState.lux, frameContext.lux, metadata,
>> +		     { {
>> +			     .exposureTime = context.configuration.agc.lineDuration *
>> +					     frameContext.sensor.exposure,
>> +			     .analogueGain = frameContext.sensor.gain,
>> +			     .digitalGain = 1,
>> +			     .yHist = yHist,
>> +		     } });
> 
> I wonder how useful it is to use an optional<>. In which case IPA
> modules call process() with std::nullopt ? And in case they do, can't
> they just skip calling process() ?

I think it generally makes sense to have a way to call `process()` even
if the statistics / etc. is not available:

   * it notifies the algorithm about the completion of a frame
   * it can supply metadata

It's a good question whether or not continuing to supply the latest lux
value is a reasonable idea. On one hand, it is technically "outdated",
and there is no way to signal that to the application. But on another hand,
this is the value that other algorithms will use. So I don't know.


> 
>>   }
>>
>>   REGISTER_IPA_ALGORITHM(Lux, "Lux")
>> diff --git a/src/ipa/rkisp1/algorithms/lux.h b/src/ipa/rkisp1/algorithms/lux.h
>> index 8cb35cbae2..f7d2581e57 100644
>> --- a/src/ipa/rkisp1/algorithms/lux.h
>> +++ b/src/ipa/rkisp1/algorithms/lux.h
>> @@ -20,8 +20,6 @@ namespace ipa::rkisp1::algorithms {
>>   class Lux : public Algorithm
>>   {
>>   public:
>> -	Lux();
>> -
>>   	int init(IPAContext &context, const ValueNode &tuningData) override;
>>   	void prepare(IPAContext &context, const uint32_t frame,
>>   		     IPAFrameContext &frameContext,
>> @@ -32,7 +30,7 @@ public:
>>   		     ControlList &metadata) override;
>>
>>   private:
>> -	ipa::Lux lux_;
>> +	ipa::LuxAlgorithm lux_;
>>   };
>>
>>   } /* namespace ipa::rkisp1::algorithms */
>> diff --git a/src/ipa/rkisp1/ipa_context.h b/src/ipa/rkisp1/ipa_context.h
>> index a6db004c16..b34ea53406 100644
>> --- a/src/ipa/rkisp1/ipa_context.h
>> +++ b/src/ipa/rkisp1/ipa_context.h
>> @@ -32,6 +32,7 @@
>>   #include "libipa/fixedpoint.h"
>>   #include "libipa/gamma.h"
>>   #include "libipa/lsc.h"
>> +#include "libipa/lux.h"
>>
>>   namespace libcamera {
>>
>> @@ -105,9 +106,7 @@ struct IPAActiveState {
>>
>>   	ipa::gamma::ActiveState gamma;
>>
>> -	struct {
>> -		double lux;
>> -	} lux;
>> +	ipa::lux::ActiveState lux;
>>
>>   	struct {
>>   		controls::WdrModeEnum mode;
>> @@ -162,9 +161,7 @@ struct IPAFrameContext : public FrameContext {
>>
>>   	ipa::ccm::FrameContext ccm;
>>
>> -	struct {
>> -		double lux;
>> -	} lux;
>> +	ipa::lux::FrameContext lux;
> 
> In any case, this is a good addition
> Reviewed-by: Jacopo Mondi <jacopo.mondi@ideasonboard.com>
> 
>>
>>   	struct {
>>   		controls::WdrModeEnum mode;
>> --
>> 2.56.1
>>

Patch
diff mbox series

diff --git a/src/ipa/libipa/lux.cpp b/src/ipa/libipa/lux.cpp
index 12ba073a11..2d8c621e5c 100644
--- a/src/ipa/libipa/lux.cpp
+++ b/src/ipa/libipa/lux.cpp
@@ -3,22 +3,22 @@ 
  * Copyright (C) 2019, Raspberry Pi Ltd
  * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>
  *
- * Helper class that implements lux estimation
+ * libIPA lux estimation
  */
 #include "lux.h"
 
-#include <algorithm>
-#include <chrono>
-
 #include <libcamera/base/log.h>
 
+#include <libcamera/control_ids.h>
+#include <libcamera/controls.h>
+
 #include "libcamera/internal/value_node.h"
 
 #include "histogram.h"
 
 /**
  * \file lux.h
- * \brief Helper class that implements lux estimation
+ * \brief libipa implementation of lux estimation
  *
  * Estimating the lux level of an image is a common operation that can for
  * instance be used to adjust the target Y value in AGC or for Bayesian AWB
@@ -33,51 +33,82 @@  LOG_DEFINE_CATEGORY(Lux)
 
 namespace ipa {
 
+namespace lux {
+
 /**
- * \class Lux
- * \brief Class that implements lux estimation
+ * \class ActiveState
+ * \brief The active state for the algorithm
  *
- * IPAs that wish to use lux estimation should create a Lux algorithm module
- * that lightly wraps this module by providing the platform-specific luminance
- * histogram. The Lux entry in the tuning file must then precede the algorithms
- * that depend on the estimated lux value.
+ * \var ActiveState::lux
+ * \brief The latest lux estimation
  */
 
 /**
- * \var Lux::referenceExposureTime_
+ * \class FrameContext
+ * \brief The frame context for the algorithm
+ *
+ * \var FrameContext::lux
+ * \brief The estimated lux value for the given frame
+ */
+
+} /* namespace lux */
+
+/**
+ * \class LuxAlgorithm
+ * \brief Lux estimation algorithm
+ *
+ * This algorithm provides lux estimation based on tuning data. IPAs that wish to
+ * use lux estimation should create a Lux algorithm module that lightly wraps this
+ * module by providing the platform-specific luminance histogram. The Lux entry in
+ * the tuning file must then precede the algorithms that depend on the estimated lux
+ * value.
+ */
+
+/**
+ * \class LuxAlgorithm::ProcessParams
+ * \brief Parameters for LuxAlgorithm::process()
+ *
+ * \var LuxAlgorithm::ProcessParams::exposureTime
+ * \brief Effective exposure time of the frame
+ *
+ * \var LuxAlgorithm::ProcessParams::analogueGain
+ * \brief Effective analogue gain of the frame
+ *
+ * \var LuxAlgorithm::ProcessParams::digitalGain
+ * \brief Effective digital gain of the frame
+ *
+ * \var LuxAlgorithm::ProcessParams::yHist
+ * \brief Luminance histogram of the frame
+ */
+
+/**
+ * \var LuxAlgorithm::referenceExposureTime_
  * \brief The exposure time of the reference image, in microseconds
  */
 
 /**
- * \var Lux::referenceAnalogueGain_
+ * \var LuxAlgorithm::referenceAnalogueGain_
  * \brief The analogue gain of the reference image
  */
 
 /**
- * \var Lux::referenceDigitalGain_
+ * \var LuxAlgorithm::referenceDigitalGain_
  * \brief The analogue gain of the reference image
  */
 
 /**
- * \var Lux::referenceY_
+ * \var LuxAlgorithm::referenceY_
  * \brief The measured luminance of the reference image, normalized to 1
  *
  */
 
 /**
- * \var Lux::referenceLux_
+ * \var LuxAlgorithm::referenceLux_
  * \brief The estimated lux level of the reference image
  */
 
 /**
-  * \brief Construct the Lux helper module
-  */
-Lux::Lux()
-{
-}
-
-/**
- * \brief Parse tuning data
+ * \brief Initialize algorithm and parse tuning data
  * \param[in] tuningData The ValueNode representing the tuning data
  *
  * This function parses tuning data for the common Lux module. It requires
@@ -95,7 +126,7 @@  Lux::Lux()
  *
  * \return 0 on success or a negative error code
  */
-int Lux::parseTuningData(const ValueNode &tuningData)
+int LuxAlgorithm::init(const ValueNode &tuningData)
 {
 	auto value = tuningData["referenceExposureTime"].get<double>();
 	if (!value) {
@@ -141,25 +172,50 @@  int Lux::parseTuningData(const ValueNode &tuningData)
 }
 
 /**
- * \brief Estimate lux given runtime values
- * \param[in] exposureTime Exposure time applied to the frame
- * \param[in] aGain Analogue gain applied to the frame
- * \param[in] dGain Digital gain applied to the frame
- * \param[in] yHist Histogram from the ISP statistics
+ * \param[in] state The active state
+ * \param[in] frameContext The frame context
  *
- * Estimate the lux given the exposure time, gain, and histogram.
+ * This function finalizes \ref lux::FrameContext::lux "frameContext.lux"
+ * based on the latest estimation.
+ */
+void LuxAlgorithm::prepare(const lux::ActiveState &state, lux::FrameContext &frameContext)
+{
+	frameContext.lux = state.lux;
+}
+
+/**
+ * \param[in] state The active state
+ * \param[in] frameContext The frame context
+ * \param[in] params The processing parameters
+ * \param[in] metadata The metadata
  *
- * \return Estimated lux value
+ * This function updates the lux estimation based on the luminance histogram
+ * and other parameters of a completed frame, and additionally it also updates
+ * \a metadata for the frame.
  */
-double Lux::estimateLux(utils::Duration exposureTime,
-			double aGain, double dGain,
-			const Histogram &yHist) const
+void LuxAlgorithm::process(lux::ActiveState &state, const lux::FrameContext &frameContext,
+			   ControlList &metadata, std::optional<ProcessParams> &&params)
+{
+	/*
+	 * Report the lux level used by algorithms to prepare this frame
+	 * not the lux level *of* this frame.
+	 */
+	metadata.set(controls::Lux, frameContext.lux);
+
+	/* If no statistics are available, keep the latest estimation. */
+	if (!params)
+		return;
+
+	state.lux = estimateLux(*params);
+}
+
+double LuxAlgorithm::estimateLux(const ProcessParams &params) const
 {
-	double currentY = yHist.interQuantileMean(0, 1);
-	double exposureTimeRatio = referenceExposureTime_ / exposureTime;
-	double aGainRatio = referenceAnalogueGain_ / aGain;
-	double dGainRatio = referenceDigitalGain_ / dGain;
-	double yRatio = (currentY / yHist.bins()) / referenceY_;
+	double currentY = params.yHist.interQuantileMean(0, 1);
+	double exposureTimeRatio = referenceExposureTime_ / params.exposureTime;
+	double aGainRatio = referenceAnalogueGain_ / params.analogueGain;
+	double dGainRatio = referenceDigitalGain_ / params.digitalGain;
+	double yRatio = (currentY / params.yHist.bins()) / referenceY_;
 
 	double estimatedLux = exposureTimeRatio * aGainRatio * dGainRatio *
 			      yRatio * referenceLux_;
diff --git a/src/ipa/libipa/lux.h b/src/ipa/libipa/lux.h
index b6837ab729..5bce7855ad 100644
--- a/src/ipa/libipa/lux.h
+++ b/src/ipa/libipa/lux.h
@@ -8,27 +8,49 @@ 
 
 #pragma once
 
+#include <optional>
+
 #include <libcamera/base/utils.h>
 
 namespace libcamera {
 
+class ControlList;
 class ValueNode;
 
 namespace ipa {
 
 class Histogram;
 
-class Lux
+namespace lux {
+
+struct ActiveState {
+	double lux;
+};
+
+struct FrameContext {
+	double lux;
+};
+
+} /* namespace lux */
+
+class LuxAlgorithm
 {
 public:
-	Lux();
-
-	int parseTuningData(const ValueNode &tuningData);
-	double estimateLux(utils::Duration exposureTime,
-			   double aGain, double dGain,
-			   const Histogram &yHist) const;
+	struct ProcessParams {
+		utils::Duration exposureTime;
+		double analogueGain;
+		double digitalGain;
+		const Histogram &yHist;
+	};
+
+	int init(const ValueNode &tuningData);
+	void prepare(const lux::ActiveState &state, lux::FrameContext &frameContext);
+	void process(lux::ActiveState &state, const lux::FrameContext &frameContext,
+		     ControlList &metadata, std::optional<ProcessParams> &&params);
 
 private:
+	double estimateLux(const ProcessParams &params) const;
+
 	utils::Duration referenceExposureTime_;
 	double referenceAnalogueGain_;
 	double referenceDigitalGain_;
diff --git a/src/ipa/rkisp1/algorithms/lux.cpp b/src/ipa/rkisp1/algorithms/lux.cpp
index ce6928a55d..68ad41d6cf 100644
--- a/src/ipa/rkisp1/algorithms/lux.cpp
+++ b/src/ipa/rkisp1/algorithms/lux.cpp
@@ -31,19 +31,12 @@  namespace ipa::rkisp1::algorithms {
  * other algorithms (such as AGC) to use.
  */
 
-/**
- * \brief Construct an rkisp1 Lux algo module
- */
-Lux::Lux()
-{
-}
-
 /**
  * \copydoc libcamera::ipa::Algorithm::init
  */
 int Lux::init([[maybe_unused]] IPAContext &context, const ValueNode &tuningData)
 {
-	return lux_.parseTuningData(tuningData);
+	return lux_.init(tuningData);
 }
 
 /**
@@ -53,7 +46,7 @@  void Lux::prepare(IPAContext &context, [[maybe_unused]] const uint32_t frame,
 		  IPAFrameContext &frameContext,
 		  [[maybe_unused]] RkISP1Params *params)
 {
-	frameContext.lux.lux = context.activeState.lux.lux;
+	lux_.prepare(context.activeState.lux, frameContext.lux);
 }
 
 /**
@@ -65,25 +58,24 @@  void Lux::process(IPAContext &context,
 		  const rkisp1_stat_buffer *stats,
 		  ControlList &metadata)
 {
-	/*
-	 * Report the lux level used by algorithms to prepare this frame
-	 * not the lux level *of* this frame.
-	 */
-	metadata.set(controls::Lux, frameContext.lux.lux);
-
-	if (!stats)
+	if (!stats) {
+		lux_.process(context.activeState.lux, frameContext.lux, metadata, {});
 		return;
-
-	utils::Duration exposureTime = context.configuration.agc.lineDuration *
-				       frameContext.sensor.exposure;
-	double gain = frameContext.sensor.gain;
+	}
 
 	/* \todo Deduplicate the histogram calculation from AGC */
 	const rkisp1_cif_isp_stat *params = &stats->params;
 	Histogram yHist({ params->hist.hist_bins, context.hw.numHistogramBins },
 			[](uint32_t x) { return x >> 4; });
 
-	context.activeState.lux.lux = lux_.estimateLux(exposureTime, gain, 1.0, yHist);
+	lux_.process(context.activeState.lux, frameContext.lux, metadata,
+		     { {
+			     .exposureTime = context.configuration.agc.lineDuration *
+					     frameContext.sensor.exposure,
+			     .analogueGain = frameContext.sensor.gain,
+			     .digitalGain = 1,
+			     .yHist = yHist,
+		     } });
 }
 
 REGISTER_IPA_ALGORITHM(Lux, "Lux")
diff --git a/src/ipa/rkisp1/algorithms/lux.h b/src/ipa/rkisp1/algorithms/lux.h
index 8cb35cbae2..f7d2581e57 100644
--- a/src/ipa/rkisp1/algorithms/lux.h
+++ b/src/ipa/rkisp1/algorithms/lux.h
@@ -20,8 +20,6 @@  namespace ipa::rkisp1::algorithms {
 class Lux : public Algorithm
 {
 public:
-	Lux();
-
 	int init(IPAContext &context, const ValueNode &tuningData) override;
 	void prepare(IPAContext &context, const uint32_t frame,
 		     IPAFrameContext &frameContext,
@@ -32,7 +30,7 @@  public:
 		     ControlList &metadata) override;
 
 private:
-	ipa::Lux lux_;
+	ipa::LuxAlgorithm lux_;
 };
 
 } /* namespace ipa::rkisp1::algorithms */
diff --git a/src/ipa/rkisp1/ipa_context.h b/src/ipa/rkisp1/ipa_context.h
index a6db004c16..b34ea53406 100644
--- a/src/ipa/rkisp1/ipa_context.h
+++ b/src/ipa/rkisp1/ipa_context.h
@@ -32,6 +32,7 @@ 
 #include "libipa/fixedpoint.h"
 #include "libipa/gamma.h"
 #include "libipa/lsc.h"
+#include "libipa/lux.h"
 
 namespace libcamera {
 
@@ -105,9 +106,7 @@  struct IPAActiveState {
 
 	ipa::gamma::ActiveState gamma;
 
-	struct {
-		double lux;
-	} lux;
+	ipa::lux::ActiveState lux;
 
 	struct {
 		controls::WdrModeEnum mode;
@@ -162,9 +161,7 @@  struct IPAFrameContext : public FrameContext {
 
 	ipa::ccm::FrameContext ccm;
 
-	struct {
-		double lux;
-	} lux;
+	ipa::lux::FrameContext lux;
 
 	struct {
 		controls::WdrModeEnum mode;