Misc (#19)

* get image returns optional<Mat> instead of unique_ptr<Mat>

* introduce complexity

* rename image load function

* add example for a basic reader for binary image files

* fix windows build?

* add a status bar underneath the menu bar

* use status bar in custom_0 example app

* clang formats

* packing w/ pragma push

* add "Save As" functions to image views

* resize over reserve

* rm local override uri

* add simple thread pool

* rename to simple_thread_pool

* get rid of useless renderlib

* document version inc

* extract hardcoded values to in-header

* clang format patch

* clone registered image in custom_0

* document binary-file header

* minor fixes

* clang format

* rm unused render cmake

lib/app/rendering/CvMatRender.cpp

@@ -0,0 +1,123 @@
+#include "CvMatRender.hpp"
+
+#include <opencv2/core/mat.hpp>
+#include <opencv2/imgproc.hpp>
+
+#include "imaging/IPixelariumImage.hpp"
+
+using namespace pixelarium::imaging;
+
+/// @brief Constructor for the CvMatRender class.
+/// @param img A shared pointer to the PixelariumImage to be rendered.
+pixelarium::application::CvMatRender::CvMatRender(const cv::Mat& img) : base_(img), texture_(0)
+{
+    // storing a copy of the to-be-rendered image
+    // because it will be resized and filtered eventually which we absolutely
+    // must not do on the original image
+    this->ResetRenderImage();
+    cv::cvtColor(this->img_, this->img_, cv::COLOR_BGR2RGBA);
+}
+
+/// @brief Destructor for the CvMatRender class.
+/// Deallocates the OpenGL texture if it exists.
+pixelarium::application::CvMatRender::~CvMatRender()
+{
+    if (texture_)
+    {
+        glDeleteTextures(1, &texture_);
+        texture_ = 0;
+    }
+}
+
+/// @brief Uploads the current image data to an OpenGL texture.
+/// @return The ID of the uploaded OpenGL texture.
+/// @throws std::runtime_error if the image data is empty or if there is an OpenGL error.
+GLuint pixelarium::application::CvMatRender::uploadTexture()
+{
+    if (img_.empty())
+    {
+        throw std::runtime_error("Image data is empty.");
+    }
+
+    if (!this->texture_)
+    {
+        glGenTextures(1, &this->texture_);
+        if (this->texture_ == 0)
+        {
+            throw std::runtime_error("Failed to generate OpenGL texture.");
+        }
+    }
+
+    glBindTexture(GL_TEXTURE_2D, this->texture_);
+
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
+
+    const int width = img_.cols;
+    const int height = img_.rows;
+    // see
+    // https://stackoverflow.com/questions/10167534/how-to-find-out-what-type-of-a-mat-object-is-with-mattype-in-opencv
+    // for pixel a pixel type table
+    switch (img_.type())
+    {
+        case CV_8U:
+            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_BYTE, img_.data);
+            break;
+        case CV_16U:
+        case CV_16UC3:
+        case CV_16UC4:
+            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_UNSIGNED_SHORT, img_.data);
+            break;
+        case CV_32F:
+        case CV_32FC4:
+            glTexImage2D(GL_TEXTURE_2D, 0, GL_DEPTH_COMPONENT, width, height, 0, GL_DEPTH_COMPONENT, GL_FLOAT,
+                         img_.data);
+            break;
+        default:
+            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, img_.cols, img_.rows, 0, GL_RGBA, GL_UNSIGNED_BYTE, img_.data);
+            break;
+    }
+
+    GLenum error = glGetError();
+    if (error != GL_NO_ERROR)
+    {
+        throw std::runtime_error("OpenGL error during texture upload: " + std::to_string(error));
+    }
+
+    return this->texture_;
+}
+
+/// @brief Renders the image by uploading it as a texture.
+/// @return The ID of the OpenGL texture.
+GLuint pixelarium::application::CvMatRender::Render() { return this->uploadTexture(); }
+
+/// @brief Renders the image with a specified scaling factor.
+/// @param factor The scaling factor for resizing the image.
+/// @return The ID of the OpenGL texture.
+GLuint pixelarium::application::CvMatRender::Render(float factor)
+{
+    cv::resize(this->base_, this->img_, cv::Size(0, 0), factor, factor, cv::INTER_LINEAR_EXACT);
+
+    return this->uploadTexture();
+}
+
+/// @brief Renders the image to fit within the specified width and height.
+/// @param width The maximum width of the rendered image.
+/// @param height The maximum height of the rendered image.
+/// @return The ID of the OpenGL texture.
+GLuint pixelarium::application::CvMatRender::Render(size_t width, size_t height)
+{
+    const auto sz{this->base_.size()};
+
+    const auto get_factor = [](auto opt1, auto opt2) -> float { return opt1 < opt2 ? opt1 : opt2; };
+
+    auto factor = get_factor(width / static_cast<float>(sz.width), height / static_cast<float>(sz.height));
+
+    return this->Render(factor);
+}
+
+void pixelarium::application::CvMatRender::ResetRenderImage()
+{
+    // we copy here
+    this->img_ = this->base_.clone();
+}

lib/app/rendering/CvMatRender.hpp

@@ -0,0 +1,52 @@
+#pragma once
+// windows.h must come before GL/GL.h here.
+// clang format would change this, effectively rendering the build broken.
+// clang-format off
+#ifdef _WIN32
+#include <windows.h>
+#include <GL/GL.h>
+#else
+#define GL_SILENCE_DEPRECATION
+#if defined(IMGUI_IMPL_OPENGL_ES2)
+#include <GLES2/gl2.h>
+#endif
+#include <GLFW/glfw3.h>  // Will drag system OpenGL headers
+#endif
+#include <opencv2/core/mat.hpp>
+// clang-format on
+
+namespace pixelarium::application
+{
+/// @brief Renders cv::Mat bitmaps as OpenGL textures.
+class CvMatRender
+{
+   public:
+    // we want the default constructor for the time being
+    // (although it does not make much sense and should
+    // get removed in the future)
+    // as the using AppGLFW constructs it empty as a member
+    // when coming to life.
+    // CvMatRender() = default;
+    CvMatRender(CvMatRender&) = delete;
+    CvMatRender(const CvMatRender&) = delete;
+    CvMatRender(CvMatRender&&) = delete;
+    CvMatRender& operator=(CvMatRender&) = delete;
+    CvMatRender& operator=(CvMatRender&& other) = delete;
+    ~CvMatRender();
+    explicit CvMatRender(const cv::Mat& img);
+
+   public:
+    GLuint Render();
+    GLuint Render(float factor);
+    GLuint Render(size_t width, size_t height);
+    void ResetRenderImage();
+
+   private:
+    cv::Mat img_;
+    const cv::Mat& base_;
+    GLuint texture_;
+
+    GLuint uploadTexture();
+};
+
+}  // namespace pixelarium::application

lib/app/rendering/IPixelariumImageView.cpp

@@ -0,0 +1,26 @@
+#include "IPixelariumImageView.hpp"
+
+#include <opencv2/imgcodecs.hpp>
+
+#include "app_resources_default.h"
+#include "portable-file-dialogs.h"
+
+auto pixelarium::application::IPixelariumImageView::ImageViewMenuBar() -> void
+{
+    if (ImGui::BeginMenuBar())
+    {
+        if (ImGui::MenuItem(SAVEAS))
+        {
+            auto dest = pfd::save_file("Save File", ".", {"Image Files", "*.png *.jpg *.jpeg *.tiff"},
+                                       pfd::opt::force_overwrite)
+                            .result();
+            if (!dest.empty())
+            {
+                // this->img_->SaveImage(dest);
+                cv::imwrite(dest, cached_image_);
+            }
+        }
+
+        ImGui::EndMenuBar();
+    }
+}

lib/app/rendering/IPixelariumImageView.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <memory>
+
+#include "imaging/IPixelariumImage.hpp"
+#include "imgui.h"
+
+namespace pixelarium::application
+{
+/// @brief An interface defining the contract on views to dedicated implementations of IPixelariumImage
+class IPixelariumImageView
+{
+   public:
+    virtual ~IPixelariumImageView() = default;
+    virtual void ShowImage() = 0;
+
+    // default implemented
+   public:
+    virtual const bool* GetStatus() const noexcept { return &this->open_p; }
+    virtual void ForceUpdate() noexcept { this->is_dirty_ = true; }
+
+    // this must be called immediately before a "ImGui::Begin" context
+    // as it will affect the next window and result in undeterministic effects
+    // when called "out of sync"
+    virtual void SetInitialSize(float width = 700.0f, float height = 700.0f)
+    {
+        ImGui::SetNextWindowSize({width, height});
+    }
+
+   protected:
+    virtual void ImageViewMenuBar();
+
+   protected:
+    std::shared_ptr<imaging::IPixelariumImageCvMat> img_{};
+    cv::Mat cached_image_{};
+    bool open_p{true};
+    bool is_dirty_{true};
+    bool first_render_{true};
+};
+}  // namespace pixelarium::application

lib/app/rendering/ImageViewFactory.cpp

@@ -0,0 +1,59 @@
+#include "ImageViewFactory.hpp"
+
+#include <format>
+#include <memory>
+
+#include "IPixelariumImageView.hpp"
+#include "PixelariumImageViewCzi.hpp"
+#include "PixelariumImageViewDefault.hpp"
+#include "imaging/IPixelariumImage.hpp"
+#include "imaging/PixelariumImageFactory.hpp"
+
+/// @brief Creates a PixelariumImageView from a resource image.
+/// @param image_id The ID of the image resource to render.
+/// @return A unique pointer to the PixelariumImageView, or nullptr if the image resource is not found or is empty.  The
+/// image data is copied.
+std::unique_ptr<pixelarium::application::IPixelariumImageView> pixelarium::application::ImageViewFactory::RenderImage(
+    resources::ResourceKey image_id)
+{
+    using ImageType = imaging::ImageFileType;
+    auto res{this->image_pool_.GetResource(image_id)};
+
+    auto img{res.lock()};
+
+    if (img == nullptr)
+    {
+        return {};
+    }
+
+    if (img->Empty())
+    {
+        return {};
+    }
+
+    auto type = imaging::ExtensionToType(img->Uri().extension().string());
+    if (img->Uri().empty())
+    {
+        log_.Info(std::format("{}: empty Uri for {}.", __PRETTY_FUNCTION__, img->Name()));
+        type = ImageType::kMemory;
+    }
+
+    switch (type)
+    {
+        case ImageType::kUnknown:
+        case ImageType::kAbstract:
+        case ImageType::kPng:
+        case ImageType::kJpg:
+        case ImageType::kTiff:
+        case ImageType::kMemory:
+            log_.Info(std::format("{}: Creating a Default View", __PRETTY_FUNCTION__));
+            // beware: here we copy the actual image resource over to the new image
+            return std::make_unique<PixelariumImageViewDefault>(img);
+        case ImageType::kCzi:
+            log_.Info(std::format("{}: Creating a CZI View", __PRETTY_FUNCTION__));
+            // beware: here we copy the actual image resource over to the new image
+            return std::make_unique<PixelariumImageViewCzi>(img, log_);
+        default:
+            return {};
+    }
+}

lib/app/rendering/ImageViewFactory.hpp

@@ -0,0 +1,25 @@
+#pragma once
+
+#include "IPixelariumImageView.hpp"
+#include "resources/resource.hpp"
+#include "utilities/ILog.hpp"
+
+namespace pixelarium::application
+{
+/// @brief Factory for instantiating matching views to different implementations of IPixelariumImage.
+class ImageViewFactory
+{
+    using Image = imaging::IPixelariumImageCvMat;
+    using Pool = resources::ImageResourcePool;
+    using Log = utils::log::ILog;
+
+   public:
+    explicit ImageViewFactory(Pool& pool, const Log& log) : image_pool_(pool), log_(log) {}
+
+    std::unique_ptr<IPixelariumImageView> RenderImage(resources::ResourceKey id);
+
+   private:
+    Pool& image_pool_;
+    const Log& log_;
+};
+}  // namespace pixelarium::application

lib/app/rendering/PixelariumImageViewCzi.cpp

@@ -0,0 +1,120 @@
+#include "PixelariumImageViewCzi.hpp"
+
+#include <format>
+#include <memory>
+
+#include "CvMatRender.hpp"
+#include "RenderHelpers.hpp"
+#include "imaging/IPixelariumImage.hpp"
+#include "imaging/impl/PixelariumCzi.hpp"
+#include "imgui.h"
+
+void pixelarium::application::PixelariumImageViewCzi::RefreshCachedImage()
+{
+    if (this->cached_image_.empty() || this->is_dirty_)
+    {
+        log_.Info(std::format("{}: refreshing image.", __PRETTY_FUNCTION__));
+        imaging::CziParams params;
+        params.dimension_map = this->dimension_map_;
+        this->cached_image_ = this->img_->TryGetImage(params).value_or(cv::Mat{});
+        // Resetting the image while the renderer is possibly accessing the
+        // image at the same time is not a good idea. Therefore, we simply create
+        // a new renderer here.
+        this->render_ = std::make_unique<CvMatRender>(this->cached_image_);
+        this->is_dirty_ = false;
+    }
+}
+
+pixelarium::application::PixelariumImageViewCzi::PixelariumImageViewCzi(std::shared_ptr<Image> img, const Log& log)
+    : log_(log), render_(std::make_unique<CvMatRender>(*img->TryGetImage()))
+{
+    img_ = img;
+    auto czi_img = std::static_pointer_cast<imaging::PixelariumCzi>(this->img_);
+
+    auto stats = czi_img->GetStatistics();
+    stats.dimBounds.EnumValidDimensions(
+        [&](libCZI::DimensionIndex dim, int start, int) -> bool
+        {
+            this->dimension_map_[dim] = start;
+            return true;
+        });
+
+    // this->SetInitialSize();
+    log_.Info(std::format("{}: dimension map size: {}", __PRETTY_FUNCTION__, dimension_map_.size()));
+}
+
+/// @brief Displays the image in an ImGui window.
+///
+/// If the image is null, empty, or has an empty name, the function returns immediately.  Otherwise, it creates an ImGui
+/// window with a horizontal scrollbar and menu bar. The image is rendered using the CvMatRender object, resizing it to
+/// fit the available window space.  The raw and rendered dimensions are displayed below the image.
+void pixelarium::application::PixelariumImageViewCzi::ShowImage()
+{
+    auto czi_img = std::static_pointer_cast<imaging::PixelariumCzi>(this->img_);
+
+    if (!czi_img) return;
+
+    RefreshCachedImage();
+
+    if (czi_img->Empty() || this->img_->type_ == imaging::ImageFileType::kUnknown || cached_image_.empty() ||
+        czi_img->Name().empty())
+    {
+        // do nothing
+        return;
+    }
+
+    if (first_render_)
+    {
+        first_render_ = false;
+        constexpr auto initial_width{700.0f};
+        const auto cached_width{cached_image_.cols};
+        const auto cached_heigth{cached_image_.rows};
+        const auto ratio{static_cast<float>(cached_heigth) / cached_width};
+        SetInitialSize(initial_width, (initial_width * ratio + 100));
+    }
+
+    ImGui::Begin(this->img_->Name().c_str(), &this->open_p,
+                 ImGuiWindowFlags_HorizontalScrollbar | ImGuiWindowFlags_MenuBar);
+
+    ImageViewMenuBar();
+
+    this->curr_dim_ = ImGui::GetContentRegionAvail();
+    auto new_dim = ImGui::GetContentRegionAvail();
+    auto texture =
+        dim_changed_p(this->curr_dim_, new_dim)
+            ? this->render_->Render(static_cast<size_t>(this->curr_dim_.x), static_cast<size_t>(this->curr_dim_.y))
+            : this->render_->Render();
+
+    this->curr_dim_ = new_dim;
+
+    ImVec2 dim(cached_image_.cols, cached_image_.rows);
+
+    ImGui::Image(reinterpret_cast<ImTextureID>(reinterpret_cast<void*>(texture)),
+                 aspect_const_dimensions(dim, new_dim));
+
+    ImGui::Separator();
+    ImGui::Text("%s", std::format("   Raw Dimensions W : {}, H: {}", dim.x, dim.y).c_str());
+    ImGui::Text("%s", std::format("Render Dimensions W : {}, H: {}", curr_dim_.x, curr_dim_.y).c_str());
+    ImGui::Text("Dimensions");
+    ImGui::Separator();
+    if (ImGui::Button("Update"))
+    {
+        this->ForceUpdate();
+    }
+
+    auto stats = czi_img->GetStatistics();
+    stats.dimBounds.EnumValidDimensions(
+        [&](libCZI::DimensionIndex dim, int start, int size) -> bool
+        {
+            auto dim_char = libCZI::Utils::DimensionToChar(dim);
+            if (ImGui::SliderInt(std::format("{}({}-{})", dim_char, start, size).c_str(), &dimension_map_[dim], start,
+                                 size - 1))
+            {
+                this->ForceUpdate();
+            }
+
+            return true;
+        });
+
+    ImGui::End();
+}

lib/app/rendering/PixelariumImageViewCzi.hpp

@@ -0,0 +1,41 @@
+#pragma once
+
+#include <memory>
+#include <unordered_map>
+
+#include "CvMatRender.hpp"
+#include "IPixelariumImageView.hpp"
+#include "imaging/IPixelariumImage.hpp"
+#include "imgui.h"
+#include "libCZI_DimCoordinate.h"
+#include "utilities/ILog.hpp"
+
+namespace pixelarium::application
+{
+/// @brief A CZI-specific implementation of IPixelariumImageView.
+class PixelariumImageViewCzi : public IPixelariumImageView
+{
+    using Image = imaging::IPixelariumImageCvMat;
+    using Log = utils::log::ILog;
+
+   public:
+    explicit PixelariumImageViewCzi(std::shared_ptr<Image> img, const Log& log);
+    PixelariumImageViewCzi() = delete;
+    PixelariumImageViewCzi(PixelariumImageViewCzi&) = delete;
+    PixelariumImageViewCzi(const PixelariumImageViewCzi&) = delete;
+    PixelariumImageViewCzi(PixelariumImageViewCzi&&) = delete;
+    PixelariumImageViewCzi& operator=(PixelariumImageViewCzi&) = delete;
+    PixelariumImageViewCzi& operator=(PixelariumImageViewCzi&&) = delete;
+
+    void ShowImage() override;
+
+   private:
+    ImVec2 curr_dim_{};
+    const Log& log_;
+    std::unordered_map<libCZI::DimensionIndex, int> dimension_map_;
+    std::unique_ptr<CvMatRender> render_;
+
+   private:
+    void RefreshCachedImage();
+};
+}  // namespace pixelarium::application

lib/app/rendering/PixelariumImageViewDefault.cpp

@@ -0,0 +1,69 @@
+#include "PixelariumImageViewDefault.hpp"
+
+#include <format>
+
+#include "RenderHelpers.hpp"
+#include "app_resources_default.h"
+#include "imaging/IPixelariumImage.hpp"
+#include "imgui.h"
+
+void pixelarium::application::PixelariumImageViewDefault::RefreshCachedImage()
+{
+    if (this->cached_image_.empty() || this->is_dirty_)
+    {
+        this->cached_image_ = this->img_->TryGetImage().value_or(cv::Mat{});
+        this->is_dirty_ = false;
+    }
+}
+
+/// @brief Displays the image in an ImGui window.
+///
+/// If the image is null, empty, or has an empty name, the function returns immediately.  Otherwise, it creates an ImGui
+/// window with a horizontal scrollbar and menu bar. The image is rendered using the CvMatRender object, resizing it to
+/// fit the available window space.  The raw and rendered dimensions are displayed below the image.
+void pixelarium::application::PixelariumImageViewDefault::ShowImage()
+{
+    RefreshCachedImage();
+
+    if (this->img_->Empty() || this->img_->type_ == imaging::ImageFileType::kUnknown || this->cached_image_.empty() ||
+        this->img_->Name().empty())
+    {
+        // do nothing
+        return;
+    }
+
+    if (first_render_)
+    {
+        first_render_ = false;
+
+        const auto cached_width{cached_image_.cols};
+        const auto cached_heigth{cached_image_.rows};
+        const auto ratio{static_cast<float>(cached_heigth) / cached_width};
+        SetInitialSize(kInitialWindowWidth, (kInitialWindowWidth * ratio + 100));
+    }
+
+    ImGui::Begin(this->img_->Name().c_str(), &this->open_p,
+                 ImGuiWindowFlags_HorizontalScrollbar | ImGuiWindowFlags_MenuBar);
+
+    ImageViewMenuBar();
+
+    this->curr_dim_ = ImGui::GetContentRegionAvail();
+    auto new_dim = ImGui::GetContentRegionAvail();
+    auto texture =
+        dim_changed_p(this->curr_dim_, new_dim)
+            ? this->render_.Render(static_cast<size_t>(this->curr_dim_.x), static_cast<size_t>(this->curr_dim_.y))
+            : this->render_.Render();
+
+    this->curr_dim_ = new_dim;
+
+    ImVec2 dim(cached_image_.cols, cached_image_.rows);
+
+    ImGui::Image(reinterpret_cast<ImTextureID>(reinterpret_cast<void*>(texture)),
+                 aspect_const_dimensions(dim, new_dim));
+
+    ImGui::Separator();
+    ImGui::Text("%s", std::format("   Raw Dimensions W : {}, H: {}", dim.x, dim.y).c_str());
+    ImGui::Text("%s", std::format("Render Dimensions W : {}, H: {}", curr_dim_.x, curr_dim_.y).c_str());
+
+    ImGui::End();
+}

lib/app/rendering/PixelariumImageViewDefault.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <memory>
+
+#include "CvMatRender.hpp"
+#include "IPixelariumImageView.hpp"
+#include "imaging/IPixelariumImage.hpp"
+#include "imgui.h"
+
+namespace pixelarium::application
+{
+/// @brief A default implementation of IPixelariumImageView.
+/// This is sufficient for single dimension images like png or jpg.
+class PixelariumImageViewDefault : public IPixelariumImageView
+{
+    using Image = imaging::IPixelariumImageCvMat;
+
+   public:
+    explicit PixelariumImageViewDefault(std::shared_ptr<Image> img) : render_(*img->TryGetImage())
+    {
+        img_ = img;
+        // this->SetInitialSize();
+    }
+    PixelariumImageViewDefault() = delete;
+    PixelariumImageViewDefault(PixelariumImageViewDefault&) = delete;
+    PixelariumImageViewDefault(const PixelariumImageViewDefault&) = delete;
+    PixelariumImageViewDefault(PixelariumImageViewDefault&&) = delete;
+    PixelariumImageViewDefault& operator=(PixelariumImageViewDefault&) = delete;
+    PixelariumImageViewDefault& operator=(PixelariumImageViewDefault&&) = delete;
+
+    void ShowImage() override;
+
+   private:
+    ImVec2 curr_dim_{};
+    CvMatRender render_;
+
+   private:
+    void RefreshCachedImage();
+};
+}  // namespace pixelarium::application

lib/app/rendering/RenderHelpers.cpp

@@ -0,0 +1,32 @@
+#include "RenderHelpers.hpp"
+
+#include <cstdlib>
+
+/// @brief Checks if the dimensions of two ImVec2 vectors have changed significantly.
+/// @param ref_rect The reference ImVec2 vector.
+/// @param new_rect The new ImVec2 vector to compare against.
+/// @return True if the absolute difference between the y-coordinates is greater than 5 or the x-coordinates are
+/// different; otherwise, false.
+bool pixelarium::application::dim_changed_p(const ImVec2& ref_rect, const ImVec2& new_rect)
+{
+    if (std::abs(ref_rect.y - new_rect.y) > 5 || std::abs(ref_rect.x - new_rect.x))
+    {
+        return true;
+    }
+
+    return false;
+}
+
+/// @brief Calculates dimensions to maintain aspect ratio.
+/// @param img The input image.
+/// @param curr_dim The current dimensions.
+/// @return The calculated dimensions maintaining aspect ratio.
+ImVec2 pixelarium::application::aspect_const_dimensions(const ImVec2& raw_dim, const ImVec2& curr_dim)
+{
+    const auto w_fact = (curr_dim.x / raw_dim.x);
+    const auto h_fact = (curr_dim.y / raw_dim.y);
+
+    const auto fact = w_fact < h_fact ? w_fact : h_fact;
+
+    return ImVec2(raw_dim.x * fact, raw_dim.y * fact);
+}

lib/app/rendering/RenderHelpers.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+#include "imgui.h"
+
+namespace pixelarium::application
+{
+bool dim_changed_p(const ImVec2& ref_rect, const ImVec2& new_rect);
+
+ImVec2 aspect_const_dimensions(const ImVec2& raw_dim, const ImVec2& curr_dim);
+};  // namespace pixelarium::application

lib/app/rendering/RenderImageManager.cpp

@@ -0,0 +1,80 @@
+#include "RenderImageManager.hpp"
+
+#include <format>
+
+using namespace std;
+
+/// @brief Updates the collection of rendered images by removing images marked for deletion.
+/// This function iterates through the \c keys_to_delete_ list and removes the corresponding images from the collection.
+/// It does not acquire the mutex to avoid deadlocks with the `Remove` function.
+void pixelarium::application::RenderImageManager::UpdateCollection()
+{
+    for (const auto& key : keys_to_delete_)
+    {
+        this->Remove(key);
+    }
+
+    keys_to_delete_.clear();
+}
+
+/// @brief Marks a resource for deletion.
+/// @param key The ID of the resource to mark for deletion.
+void pixelarium::application::RenderImageManager::MarkForDeletion(resources::ResourceKey key)
+{
+    this->log_.Debug(std::format("{} marking key: \"{}\" for deletion.", __PRETTY_FUNCTION__, key));
+    lock_guard<mutex> guard(this->mut_);
+    keys_to_delete_.insert(key);
+}
+
+/// @brief Removes a render image from the manager.
+/// @param key The key of the render image to remove.
+/// @return True if the render image was removed, false otherwise.
+bool pixelarium::application::RenderImageManager::Remove(resources::ResourceKey key) noexcept
+{
+    bool remove_state{false};
+    this->log_.Debug(std::format("{} removing key: \"{}\" from renderlist.", __PRETTY_FUNCTION__, key));
+    {
+        lock_guard<mutex> guard(this->mut_);
+        remove_state = this->render_image_map_.erase(key) == 1;
+    }
+
+    return remove_state;
+}
+
+/// @brief Adds a resource to the render image map.
+/// @param key The ID of the resource to add.
+/// @return void.  No exception is thrown.
+void pixelarium::application::RenderImageManager::Add(resources::ResourceKey key) noexcept
+{
+    // we don't want to add what's already there
+    // or empty render images
+    if (this->render_image_map_.contains(key))
+    {
+        return;
+    }
+
+    auto current_view = this->view_factory_->RenderImage(key);
+    if (current_view == nullptr)
+    {
+        return;
+    }
+
+    this->log_.Debug(std::format("{}: adding key: \"{}\" to renderlist.", __PRETTY_FUNCTION__, key));
+
+    lock_guard<mutex> guard(this->mut_);
+    // clang-format off
+        this->render_image_map_.insert(
+            {
+                key,
+                RenderImageStateWrapper
+                {
+                    .view{ std::move(current_view) },
+                }
+            }
+            );
+    // clang-format on
+}
+
+/// @brief Clears all render images from the manager.
+/// @note This function is noexcept.
+void pixelarium::application::RenderImageManager::Clear() noexcept { this->render_image_map_.clear(); }

lib/app/rendering/RenderImageManager.hpp

@@ -0,0 +1,74 @@
+#pragma once
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <unordered_set>
+
+#include "IPixelariumImageView.hpp"
+#include "ImageViewFactory.hpp"
+#include "resources/resource.hpp"
+#include "utilities/ILog.hpp"
+
+// This is intended as an additional abstraction
+// aggregating views that should be rendered (or not)
+namespace pixelarium::application
+{
+/// @brief Instead of directly using the view, we
+/// proxy it through a wrapper. This allows for arbitrary additional data
+/// to be added in future
+struct RenderImageStateWrapper
+{
+    std::unique_ptr<IPixelariumImageView> view;
+    const bool* show_state;
+};
+
+/// @brief Manage instances of IPixelariumImageView.
+///
+/// This class is used to keep track of what must be rendered.
+/// It manages a set of IPixelariumImageView instances that can be traversed
+/// via its Enumerate() function.
+/// Views that shall not be rendered anymore should be marked for deletion
+/// with MarkForDeletion()
+class RenderImageManager
+{
+    using Pool = resources::ImageResourcePool;
+
+   public:
+    explicit RenderImageManager(Pool& pool, const utils::log::ILog& log)
+        : view_factory_(std::make_unique<ImageViewFactory>(pool, log)), log_(log)
+    {
+    }
+
+    void Clear() noexcept;
+
+    void Add(resources::ResourceKey key) noexcept;
+
+    bool Remove(resources::ResourceKey key) noexcept;
+
+    // can't be const because func mutates the state
+    template <typename Callable>
+        requires std::invocable<Callable, resources::ResourceKey, RenderImageStateWrapper&>
+    void Enumerate(Callable&& func)
+    {
+        for (auto& [key, val] : this->render_image_map_)
+        {
+            if (val.view != nullptr)
+            {
+                func(key, val);
+            }
+        }
+    }
+
+    void MarkForDeletion(resources::ResourceKey key);
+
+    void UpdateCollection();
+
+   private:
+    std::unordered_map<resources::ResourceKey, RenderImageStateWrapper> render_image_map_;
+    std::unique_ptr<ImageViewFactory> view_factory_;
+    std::mutex mut_;
+    std::unordered_set<resources::ResourceKey> keys_to_delete_;
+
+    const utils::log::ILog& log_;
+};
+}  // namespace pixelarium::application