@@ -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> &¶ms)
+{
+ /*
+ * 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 ¶ms) 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_;
@@ -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> &¶ms);
private:
+ double estimateLux(const ProcessParams ¶ms) const;
+
utils::Duration referenceExposureTime_;
double referenceAnalogueGain_;
double referenceDigitalGain_;
@@ -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,25 @@ 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")
@@ -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 */
@@ -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;