ipa: libipa: Add MatrixInterpolator class

Add a class to encapsulate the functionality of fetching a matrix based
on an integer key, and interpolating if there is no exact match. This is
expected to be used by both color correction matrices / crosstalk
correction as well as lens shading correction.

A cache is included only for exact matches of the key. The caller is
expected to decide the tolererance for rounding.

Signed-off-by: Paul Elder <paul.elder@ideasonboard.com>
Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>
Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

src/ipa/libipa/matrix_interpolator.cpp

@@ -0,0 +1,110 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>
+ *
+ * Helper class for interpolating maps of matrices
+ */
+#include "matrix_interpolator.h"
+
+#include <algorithm>
+#include <string>
+
+#include <libcamera/base/log.h>
+
+#include "libcamera/internal/yaml_parser.h"
+
+#include "matrix.h"
+
+/**
+ * \file matrix_interpolator.h
+ * \brief Helper class for interpolating maps of matrices
+ */
+
+namespace libcamera {
+
+LOG_DEFINE_CATEGORY(MatrixInterpolator)
+
+namespace ipa {
+
+/**
+ * \class MatrixInterpolator
+ * \brief Class for storing, retrieving, and interpolating matrices
+ * \tparam T Type of numerical values to be stored in the matrices
+ * \tparam R Number of rows in the matrices
+ * \tparam C Number of columns in the matrices
+ *
+ * The main use case is to pass a map from color temperatures to corresponding
+ * matrices (eg. color correction), and then requesting a matrix for a specific
+ * color temperature. This class will abstract away the interpolation portion.
+ */
+
+/**
+ * \fn MatrixInterpolator::MatrixInterpolator(const std::map<unsigned int, Matrix<T, R, C>> &matrices)
+ * \brief Construct a matrix interpolator from a map of matrices
+ * \param matrices Map from which to construct the matrix interpolator
+ */
+
+/**
+ * \fn MatrixInterpolator::reset()
+ * \brief Reset the matrix interpolator content to a single identity matrix
+ */
+
+/**
+ * \fn int MatrixInterpolator<T, R, C>::readYaml()
+ * \brief Initialize an MatrixInterpolator instance from yaml
+ * \tparam T Type of data stored in the matrices
+ * \tparam R Number of rows of the matrices
+ * \tparam C Number of columns of the matrices
+ * \param[in] yaml The yaml object that contains the map of unsigned integers to matrices
+ * \param[in] key_name The name of the key in the yaml object
+ * \param[in] matrix_name The name of the matrix in the yaml object
+ *
+ * The yaml object is expected to be a list of maps. Each map has two or more
+ * pairs: one of \a key_name to the key value (usually color temperature), and
+ * one or more of \a matrix_name to the matrix. This is a bit difficult to
+ * explain, so here is an example (in python, as it is easier to parse than
+ * yaml):
+ *       [
+ *               {
+ *                   'ct': 2860,
+ *                   'ccm': [ 2.12089, -0.52461, -0.59629,
+ *                           -0.85342,  2.80445, -0.95103,
+ *                           -0.26897, -1.14788,  2.41685 ],
+ *                   'offsets': [ 0, 0, 0 ]
+ *               },
+ *
+ *               {
+ *                   'ct': 2960,
+ *                   'ccm': [ 2.26962, -0.54174, -0.72789,
+ *                           -0.77008,  2.60271, -0.83262,
+ *                           -0.26036, -1.51254,  2.77289 ],
+ *                   'offsets': [ 0, 0, 0 ]
+ *               },
+ *
+ *               {
+ *                   'ct': 3603,
+ *                   'ccm': [ 2.18644, -0.66148, -0.52496,
+ *                           -0.77828,  2.69474, -0.91645,
+ *                           -0.25239, -0.83059,  2.08298 ],
+ *                   'offsets': [ 0, 0, 0 ]
+ *               },
+ *       ]
+ *
+ * In this case, \a key_name would be 'ct', and \a matrix_name can be either
+ * 'ccm' or 'offsets'. This way multiple matrix interpolators can be defined in
+ * one set of color temperature ranges in the tuning file, and they can be
+ * retrieved separately with the \a matrix_name parameter.
+ *
+ * \return Zero on success, negative error code otherwise
+ */
+
+/**
+ * \fn Matrix<T, R, C> MatrixInterpolator<T, R, C>::get(unsigned int key)
+ * \brief Retrieve a matrix from the list of matrices, interpolating if necessary
+ * \param[in] key The unsigned integer key of the matrix to retrieve
+ * \return The matrix corresponding to the color temperature
+ */
+
+} /* namespace ipa */
+
+} /* namespace libcamera */