[{"id":29801,"web_url":"https://patchwork.libcamera.org/comment/29801/","msgid":"<171801758903.1489778.9704357819474306293@ping.linuxembedded.co.uk>","date":"2024-06-10T11:06:29","subject":"Re: [PATCH v6 1/3] ipa: libipa: Add Matrix class","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Quoting Paul Elder (2024-06-07 09:09:04)\n> Add a class to represent a Matrix object and operations for adding\n> matrices, multipling a matrix by a scalar, and multiplying two matrices.\n> \n> Signed-off-by: Paul Elder <paul.elder@ideasonboard.com>\n> Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com>\n> \n\nLike the Vector class, my only query in here is that we're adding\ninternal support infrastructure without unit tests.\n\nIt seems like we're missing a unit test section for libipa - that\npreceeds this patch (and Vector) so I think we can let these patches\ncontinue without - but I think we really should add in unit tests to\ncommon code classes if we expect them to be re-used!\n\nReviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>\n\n> ---\n> Changes in v6:\n> - fix doxygen\n> \n> Changes in v5:\n> - add documentation\n> \n> Changes in v4:\n> - remove stray semicolons\n> - add operator<<\n> - clean up/optimize constructor\n> - replace get() and set() with operator[] (and a second [] can be used\n>   as operator[] returns a Span)\n> \n> Changes in v3:\n> - fix template parameters of operator* to allow different types for the\n>   scalar multiplier and the matrix's number type\n> - clear data in constructors\n> - fix assert in constructor\n> \n> Changes v2:\n> - make rows and columns into template arguments\n> - initialize to identity matrix on construction\n> - add getter and setter\n> - change from struct to class\n> - fix matrix multiplication\n> - clean up unused includes\n> - avoid dereferencing an absent std::optional\n> ---\n>  src/ipa/libipa/matrix.cpp  | 124 ++++++++++++++++++++++++++\n>  src/ipa/libipa/matrix.h    | 173 +++++++++++++++++++++++++++++++++++++\n>  src/ipa/libipa/meson.build |   2 +\n>  3 files changed, 299 insertions(+)\n>  create mode 100644 src/ipa/libipa/matrix.cpp\n>  create mode 100644 src/ipa/libipa/matrix.h\n> \n> diff --git a/src/ipa/libipa/matrix.cpp b/src/ipa/libipa/matrix.cpp\n> new file mode 100644\n> index 000000000..350dbeb05\n> --- /dev/null\n> +++ b/src/ipa/libipa/matrix.cpp\n> @@ -0,0 +1,124 @@\n> +/* SPDX-License-Identifier: BSD-2-Clause */\n> +/*\n> + * Copyright (C) 2019, Raspberry Pi Ltd\n> + * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>\n> + *\n> + * Matrix and related operations\n> + */\n> +\n> +#include \"matrix.h\"\n> +\n> +#include <libcamera/base/log.h>\n> +\n> +/**\n> + * \\file matrix.h\n> + * \\brief Matrix class\n> + */\n> +\n> +namespace libcamera {\n> +\n> +LOG_DEFINE_CATEGORY(Matrix)\n> +\n> +namespace ipa {\n> +\n> +/**\n> + * \\class Matrix\n> + * \\brief Matrix class\n> + * \\tparam T Type of numerical values to be stored in the matrix\n> + * \\tparam R Number of rows in the matrix\n> + * \\tparam C Number of columns in the matrix\n> + */\n> +\n> +/**\n> + * \\fn Matrix::Matrix()\n> + * \\brief Construct an identity matrix\n> + */\n> +\n> +/**\n> + * \\fn Matrix::Matrix(const std::vector<T> &data)\n> + * \\brief Construct matrix from supplied data\n> + * \\param data Data from which to construct a matrix\n> + *\n> + * \\a data is a one-dimensional vector and will be turned into a matrix in\n> + * row-major order. The size of \\a data must be equal to the product of the\n> + * number of rows and columns of the matrix (RxC).\n> + */\n> +\n> +/**\n> + * \\fn Matrix::readYaml\n> + * \\brief Populate the matrix with yaml data\n> + * \\param yaml Yaml data to populate the matrix with\n> + *\n> + * Any existing data in the matrix will be overwritten. The size of the data\n> + * read from \\a yaml must be equal to the product of the number of rows and\n> + * columns of the matrix (RxC).\n> + *\n> + * The yaml data is expected to be a list with elements of type T.\n> + *\n> + * \\return 0 on success, negative error code otherwise\n> + */\n> +\n> +/**\n> + * \\fn Matrix::toString\n> + * \\brief Assemble and return a string describing the matrix\n> + * \\return A string describing the matrix\n> + */\n> +\n> +/**\n> + * \\fn Span<const T, C> Matrix::operator[](size_t i) const\n> + * \\brief Index to a row in the matrix\n> + * \\param i Index of row to retrieve\n> + *\n> + * This operator[] returns a Span, which can then be indexed into again with\n> + * another operator[], allowing a convenient m[i][j] to access elements of the\n> + * matrix. Note that the lifetime of the Span returned by this first-level\n> + * operator[] is bound to that of the Matrix itself, so it is not recommended\n> + * to save the Span that is the result of this operator[].\n> + *\n> + * \\return Row \\a i from the matrix, as a Span\n> + */\n> +\n> +/**\n> + * \\fn Matrix::operator[](size_t i)\n> + * \\copydoc Matrix::operator[](size_t i) const\n> + */\n> +\n> +/**\n> + * \\fn Matrix::Matrix<U, R, C> operator*(T d, const Matrix<U, R, C> &m)\n> + * \\brief Scalar product\n> + * \\tparam T Type of the numerical scalar value\n> + * \\tparam U Type of numerical values in the matrix\n> + * \\tparam R Number of rows in the matrix\n> + * \\tparam C Number of columns in the matrix\n> + * \\param d Scalar\n> + * \\param m Matrix\n> + * \\return Product of scalar \\a d and matrix \\a m\n> + */\n> +\n> +/**\n> + * \\fn Matrix<T, R1, C2> operator*(const Matrix<T, R1, C1> &m1, const Matrix<T, R2, C2> &m2)\n> + * \\brief Matrix multiplication\n> + * \\tparam T Type of numerical values in the matrices\n> + * \\tparam R1 Number of rows in the first matrix\n> + * \\tparam C1 Number of columns in the first matrix\n> + * \\tparam R2 Number of rows in the second matrix\n> + * \\tparam C2 Number of columns in the second matrix\n> + * \\param m1 Multiplicand matrix\n> + * \\param m2 Multiplier matrix\n> + * \\return Matrix product of matrices \\a m1 and \\a m2\n> + */\n> +\n> +/**\n> + * \\fn Matrix<T, R, C> operator+(const Matrix<T, R, C> &m1, const Matrix<T, R, C> &m2)\n> + * \\brief Matrix addition\n> + * \\tparam T Type of numerical values in the matrices\n> + * \\tparam R Number of rows in the matrices\n> + * \\tparam C Number of columns in the matrices\n> + * \\param m1 Summand matrix\n> + * \\param m2 Summand matrix\n> + * \\return Matrix sum of matrices \\a m1 and \\a m2\n> + */\n> +\n> +} /* namespace ipa */\n> +\n> +} /* namespace libcamera */\n> diff --git a/src/ipa/libipa/matrix.h b/src/ipa/libipa/matrix.h\n> new file mode 100644\n> index 000000000..1f6447a3b\n> --- /dev/null\n> +++ b/src/ipa/libipa/matrix.h\n> @@ -0,0 +1,173 @@\n> +/* SPDX-License-Identifier: BSD-2-Clause */\n> +/*\n> + * Copyright (C) 2019, Raspberry Pi Ltd\n> + * Copyright (C) 2024, Paul Elder <paul.elder@ideasonboard.com>\n> + *\n> + * Matrix and related operations\n> + */\n> +#pragma once\n> +\n> +#include <algorithm>\n> +#include <cmath>\n> +#include <sstream>\n> +#include <vector>\n> +\n> +#include <libcamera/base/log.h>\n> +#include <libcamera/base/span.h>\n> +\n> +#include \"libcamera/internal/yaml_parser.h\"\n> +\n> +namespace libcamera {\n> +\n> +LOG_DECLARE_CATEGORY(Matrix)\n> +\n> +namespace ipa {\n> +\n> +#ifndef __DOXYGEN__\n> +template<typename T, unsigned int R, unsigned int C,\n> +        std::enable_if_t<std::is_arithmetic_v<T>> * = nullptr>\n> +#else\n> +template<typename T, unsigned int R, unsigned int C>\n> +#endif /* __DOXYGEN__ */\n> +class Matrix\n> +{\n> +public:\n> +       Matrix()\n> +               : data_(R * C, static_cast<T>(false))\n> +       {\n> +               for (size_t i = 0; i < std::min(R, C); i++)\n> +                       (*this)[i][i] = static_cast<T>(true);\n> +       }\n> +\n> +       Matrix(const std::vector<T> &data)\n> +       {\n> +               ASSERT(data.size() == R * C);\n> +\n> +               data_.clear();\n> +               for (const T &x : data)\n> +                       data_.push_back(x);\n> +       }\n> +\n> +       ~Matrix() = default;\n> +\n> +       int readYaml(const libcamera::YamlObject &yaml)\n> +       {\n> +               if (yaml.size() != R * C) {\n> +                       LOG(Matrix, Error)\n> +                               << \"Wrong number of values in matrix: expected \"\n> +                               << R * C << \", got \" << yaml.size();\n> +                       return -EINVAL;\n> +               }\n> +\n> +               unsigned int i = 0;\n> +               for (const auto &x : yaml.asList()) {\n> +                       auto value = x.get<T>();\n> +                       if (!value) {\n> +                               LOG(Matrix, Error) << \"Failed to read matrix value\";\n> +                               return -EINVAL;\n> +                       }\n> +\n> +                       data_[i++] = *value;\n> +               }\n> +\n> +               return 0;\n> +       }\n> +\n> +       const std::string toString() const\n> +       {\n> +               std::stringstream out;\n> +\n> +               out << \"Matrix { \";\n> +               for (unsigned int i = 0; i < R; i++) {\n> +                       out << \"[ \";\n> +                       for (unsigned int j = 0; j < C; j++) {\n> +                               out << (*this)[i][j];\n> +                               out << ((j + 1 < C) ? \", \" : \" \");\n> +                       }\n> +                       out << ((i + 1 < R) ? \"], \" : \"]\");\n> +               }\n> +               out << \" }\";\n> +\n> +               return out.str();\n> +       }\n> +\n> +       Span<const T, C> operator[](size_t i) const\n> +       {\n> +               return Span<const T, C>{ &data_.data()[i * C], C };\n> +       }\n> +\n> +       Span<T, C> operator[](size_t i)\n> +       {\n> +               return Span<T, C>{ &data_.data()[i * C], C };\n> +       }\n> +\n> +private:\n> +       std::vector<T> data_;\n> +};\n> +\n> +#ifndef __DOXYGEN__\n> +template<typename T, typename U, unsigned int R, unsigned int C,\n> +        std::enable_if_t<std::is_arithmetic_v<T> && std::is_arithmetic_v<U>> * = nullptr>\n> +#endif /* __DOXYGEN__ */\n> +Matrix<U, R, C> operator*(T d, const Matrix<U, R, C> &m)\n> +{\n> +       Matrix<U, R, C> result;\n> +\n> +       for (unsigned int i = 0; i < R; i++)\n> +               for (unsigned int j = 0; j < C; j++)\n> +                       result[i][j] = d * m[i][j];\n> +\n> +       return result;\n> +}\n> +\n> +#ifndef __DOXYGEN__\n> +template<typename T,\n> +        unsigned int R1, unsigned int C1,\n> +        unsigned int R2, unsigned int C2,\n> +        std::enable_if_t<std::is_arithmetic_v<T> && C1 == R2> * = nullptr>\n> +#endif /* __DOXYGEN__ */\n> +Matrix<T, R1, C2> operator*(const Matrix<T, R1, C1> &m1, const Matrix<T, R2, C2> &m2)\n> +{\n> +       Matrix<T, R1, C2> result;\n> +\n> +       for (unsigned int i = 0; i < R1; i++) {\n> +               for (unsigned int j = 0; j < C2; j++) {\n> +                       T sum = 0;\n> +\n> +                       for (unsigned int k = 0; k < C1; k++)\n> +                               sum += m1[i][k] * m2[k][j];\n> +\n> +                       result[i][j] = sum;\n> +               }\n> +       }\n> +\n> +       return result;\n> +}\n> +\n> +#ifndef __DOXYGEN__\n> +template<typename T, unsigned int R, unsigned int C,\n> +        std::enable_if_t<std::is_arithmetic_v<T>> * = nullptr>\n> +#endif /* __DOXYGEN__ */\n> +Matrix<T, R, C> operator+(const Matrix<T, R, C> &m1, const Matrix<T, R, C> &m2)\n> +{\n> +       Matrix<T, R, C> result;\n> +\n> +       for (unsigned int i = 0; i < R; i++)\n> +               for (unsigned int j = 0; j < C; j++)\n> +                       result[i][j] = m1[i][j] + m2[i][j];\n> +\n> +       return result;\n> +}\n> +\n> +} /* namespace ipa */\n> +\n> +#ifndef __DOXYGEN__\n> +template<typename T, unsigned int R, unsigned int C>\n> +std::ostream &operator<<(std::ostream &out, const ipa::Matrix<T, R, C> &m)\n> +{\n> +       out << m.toString();\n> +       return out;\n> +}\n> +#endif /* __DOXYGEN__ */\n> +\n> +} /* namespace libcamera */\n> diff --git a/src/ipa/libipa/meson.build b/src/ipa/libipa/meson.build\n> index 8ec9c7847..2547a5b83 100644\n> --- a/src/ipa/libipa/meson.build\n> +++ b/src/ipa/libipa/meson.build\n> @@ -7,6 +7,7 @@ libipa_headers = files([\n>      'exposure_mode_helper.h',\n>      'fc_queue.h',\n>      'histogram.h',\n> +    'matrix.h',\n>      'module.h',\n>      'pwl.h',\n>  ])\n> @@ -18,6 +19,7 @@ libipa_sources = files([\n>      'exposure_mode_helper.cpp',\n>      'fc_queue.cpp',\n>      'histogram.cpp',\n> +    'matrix.cpp',\n>      'module.cpp',\n>      'pwl.cpp',\n>  ])\n> -- \n> 2.39.2\n>","headers":{"Return-Path":"<libcamera-devel-bounces@lists.libcamera.org>","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 0D7A5BD87C\n\tfor <parsemail@patchwork.libcamera.org>;\n\tMon, 10 Jun 2024 11:06:35 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 32DBF65455;\n\tMon, 10 Jun 2024 13:06:34 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 481B765446\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tMon, 10 Jun 2024 13:06:32 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust6594.18-1.cable.virginm.net [86.31.185.195])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 3F28C66F;\n\tMon, 10 Jun 2024 13:06:20 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"Vvsu8rh3\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1718017580;\n\tbh=GaoVz9Hrc59tRUF15VPbd/A7fNLDiuSrD3fLadnyRns=;\n\th=In-Reply-To:References:Subject:From:Cc:To:Date:From;\n\tb=Vvsu8rh3OtDuLG82hs1lDmBiNSRL+WtSqV2BEtxh8xI6rNYgndqzCLF5o/V15HJX1\n\t+LE4tJ41ppNRVIO1NJEv7VTOr1FOF8ETHV6gRIVL+6fesc5O/pyHT8rTsdMOFLu+jF\n\teoloqTE4oFUJlhFANI9fZiYwNjM3ovtgawydrufw=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20240607080906.2684579-2-paul.elder@ideasonboard.com>","References":"<20240607080906.2684579-1-paul.elder@ideasonboard.com>\n\t<20240607080906.2684579-2-paul.elder@ideasonboard.com>","Subject":"Re: [PATCH v6 1/3] ipa: libipa: Add Matrix class","From":"Kieran Bingham <kieran.bingham@ideasonboard.com>","Cc":"Paul Elder <paul.elder@ideasonboard.com>,\n\tStefan Klug <stefan.klug@ideasonboard.com>","To":"Paul Elder <paul.elder@ideasonboard.com>,\n\tlibcamera-devel@lists.libcamera.org","Date":"Mon, 10 Jun 2024 12:06:29 +0100","Message-ID":"<171801758903.1489778.9704357819474306293@ping.linuxembedded.co.uk>","User-Agent":"alot/0.10","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" <libcamera-devel-bounces@lists.libcamera.org>"}}]