build system and module refactoring + simple histogram scratch (#20)

* scratch adding histogram to image views

Histograms should come from some sort of histogram service. This is
currently just a POC.

* custom logger implementation w/o spdlog

* missing cmake file

* fix tests

* use operator<< over direct stream exposure

* rm print header

* add threading test + refactor towards interface libraries

omits the need for =target_include_directories= calls /everywhere/

* rm print header

* rm constexpr

* templated thread_pool

* fix doxyfile

* default enable doc building

* czi reader refactor

* rm erroneous include expression

* clang-format

* single lib include with PUBLIC visibility

* compile imgui stdlib

* clang format

* documentation update

centralize `LogLevelToString` to `ILog.hpp`

update docs and examples

lib/imaging/include/IPixelariumImage.hpp

@@ -0,0 +1,153 @@
+#pragma once
+
+#include <filesystem>
+#include <functional>
+#include <opencv2/core/mat.hpp>
+#include <string>
+
+namespace pixelarium::imaging
+{
+using ImageQueryFunctor = std::function<void(const std::string&, void*, int*)>;
+
+/// @brief Enumeration of supported image file types.
+enum class ImageFileType
+{
+    /// @brief Represents an unknown or unsupported file type.
+    kUnknown = -10,
+    /// @brief Represents an abstract image type (e.g., a placeholder).
+    kAbstract = 0,
+    /// @brief Represents a PNG image file.
+    kPng = 1,
+    /// @brief Represents a JPG image file.
+    kJpg = 2,
+    /// @brief Represents a CZI image file.
+    kCzi = 3,
+    /// @brief Represents a TIFF image file.
+    kTiff = 4,
+    /// @brief Represents an in-memory image.
+    kMemory = 5,
+};
+
+/// @brief An abstract interface to define a semantic query
+/// for a multi-dimensional image.
+struct IImageQuery
+{
+    virtual ~IImageQuery() = default;
+};
+
+/// @brief This aims to be a generic image abstraction
+/// meant for codec specific implementation.
+template <class Data>
+class IPixelariumImage
+{
+   public:
+    virtual ~IPixelariumImage() = default;
+
+    /// @brief Attempts to retrieve the image.
+    /// @return A unique pointer to a Mat object containing the image data,
+    /// or nullptr if the image is not found or cannot be retrieved.
+    /// May throw exceptions for multidimensional images.
+    virtual std::optional<Data> TryGetImage() = 0;
+
+    /// @brief Attempts to retrieve the image.
+    /// @param query The query object defining the images to retrieve.
+    /// @return A unique pointer to a Mat object containing the image data,
+    /// or nullptr if the image is not found or cannot be retrieved.
+    virtual std::optional<Data> TryGetImage(const IImageQuery& query) = 0;
+
+    /// @brief Attempts to retrieve a collection of images based on a query.
+    /// @param query The query object defining the images to retrieve.
+    /// @return A vector of unique pointers to cv::Mat objects. Each element is an image.
+    /// Returns an empty vector if no images are found or if an error occurs.
+    virtual std::vector<std::optional<Data>> TryGetImages(const IImageQuery& query) = 0;
+
+    /// @brief Checks if the image is empty.
+    /// @return true if the image is empty, false otherwise.
+    virtual bool Empty() const noexcept = 0;
+
+    // default implemented
+   public:
+    /// @brief  Gets the resource identifier as a file path.
+    /// @return @c std::filesystem::path of the underlying resource.
+    virtual std::filesystem::path Uri() const noexcept { return this->uri_; }
+
+    /// @brief  Gets the resource name.
+    /// @note   Implementations of IPixelariumImage that live in memory
+    ///         should override this to get something meaningful as the name
+    ///         cannot be fetched from the resource uri in that case.
+    /// @return The name of the underlying resource.
+    virtual std::string Name() const noexcept
+    {
+        if (!this->uri_.empty())
+        {
+            return this->uri_.filename().string();
+        }
+
+        return {};
+    }
+
+   public:
+    const static ImageFileType type_{ImageFileType::kAbstract};
+
+   protected:
+    std::filesystem::path uri_;
+};
+
+/// @brief Interface template specialization of IPixelariumImage
+///        using cv::Mat as the wrapped data type.
+class IPixelariumImageCvMat : public IPixelariumImage<cv::Mat>
+{
+   public:
+    virtual ~IPixelariumImageCvMat() = default;
+
+    /// @brief Attempts to retrieve the image.
+    /// @return A unique pointer to a Mat object containing the image data,
+    /// or nullptr if the image is not found or cannot be retrieved.
+    /// May throw exceptions for multidimensional images.
+    virtual std::optional<cv::Mat> TryGetImage() = 0;
+
+    /// @brief Attempts to retrieve the image.
+    /// @param query The query object defining the images to retrieve.
+    /// @return A unique pointer to a Mat object containing the image data,
+    /// or nullptr if the image is not found or cannot be retrieved.
+    virtual std::optional<cv::Mat> TryGetImage(const IImageQuery& query) = 0;
+
+    /// @brief Attempts to retrieve a collection of images based on a query.
+    /// @param query The query object defining the images to retrieve.
+    /// @return A vector of unique pointers to cv::Mat objects. Each element is an image.
+    /// Returns an empty vector if no images are found or if an error occurs.
+    virtual std::vector<std::optional<cv::Mat>> TryGetImages(const IImageQuery& query) = 0;
+
+    /// @brief Checks if the image is empty.
+    /// @return true if the image is empty, false otherwise.
+    virtual bool Empty() const noexcept = 0;
+
+    /// @brief Saves an image to the resource identifier given by uri.
+    /// @return true if saving was successful, false otherwise.
+    virtual bool SaveImage(const std::string& uri);
+
+    // default implemented
+   public:
+    /// @brief  Gets the resource identifier as a file path.
+    /// @return @c std::filesystem::path of the underlying resource.
+    virtual std::filesystem::path Uri() const noexcept { return this->uri_; }
+
+    /// @brief  Gets the resource name.
+    /// @note   Implementations of IPixelariumImage that live in memory
+    ///         should override this to get something meaningful as the name
+    ///         cannot be fetched from the resource uri in that case.
+    /// @return The name of the underlying resource.
+    virtual std::string Name() const noexcept
+    {
+        if (!this->uri_.empty())
+        {
+            return this->uri_.filename().string();
+        }
+
+        return {};
+    }
+
+   public:
+    const static ImageFileType type_{ImageFileType::kAbstract};
+};
+}  // namespace pixelarium::imaging