Update docs (#8)

* add documentation and missing doxygen dependency

* update readme and mainpage

.github/workflows/cmake.yml

@@ -18,7 +18,7 @@ jobs:
     - name: setup
       run: |
         sudo apt update
-        sudo apt -y install libopencv-dev libglfw3 libglfw3-dev libxkbcommon-dev libxinerama-dev libxcursor-dev libxi-dev doxygen
+        sudo apt -y install libopencv-dev libglfw3 libglfw3-dev libxkbcommon-dev libxinerama-dev libxcursor-dev libxi-dev doxygen graphviz
     - name: configure
       run: cmake --preset gcc-debug
     - name: build

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.23)
 
-project(pixelarium VERSION 0.0.0)
+project(pixelarium VERSION 0.0.1)
 
 set(CMAKE_VERBOSE_MAKEFILE ON)
 set(CXX_STANDARD 20)

Readme.org

@@ -8,8 +8,8 @@
 
 * Synopsis
 
-Pixelarium strives to be a batteries-included visualizer application to be used in conjunction with an external algorithm.
+Pixelarium strives to be a batteries-included visualizer application used in conjunction with an externally implemented and linked arbitrary functionality.
-It can be linked e.g. against a library containing arbitrary functionally. Pixelarium can support viewing the results and result files of such a library.
+It can be linked e.g. against a library containing arbitrary functionality. Pixelarium can support viewing the results and result files of such a library.
 It tries to be as flexible as possible.
 
 This is still work in progress and will change significantly.

doc/Doxyfile.in

@@ -1,9 +1,11 @@
 PROJECT_NAME           = @PIXELARIUM_TITLE@
+PROJECT_NUMBER         = @CMAKE_PROJECT_VERSION@
 
 OUTPUT_DIRECTORY       = @PROJECT_BINARY_DIR@/doc
 INPUT                  = @PROJECT_SOURCE_DIR@/lib/app \
                          @PROJECT_SOURCE_DIR@/doc \
                          @PROJECT_SOURCE_DIR@/lib/imaging \
+                         @PROJECT_SOURCE_DIR@/lib/imaging/impl \
                          @PROJECT_SOURCE_DIR@/lib/utilities \
                          @PROJECT_SOURCE_DIR@/lib/rendering \
                          @PROJECT_SOURCE_DIR@/lib/resources

doc/index.md

@@ -1,7 +1,8 @@
+
 # Synopsis
 
-Pixelarium strives to be a batteries-included visualizer application to be used in conjunction with an external algorithm.
+Pixelarium strives to be a batteries-included visualizer application used in conjunction with an externally implemented and linked arbitrary functionality.
-It can be linked e.g. against a library containing arbitrary functionally. Pixelarium can support viewing the results and result files of such a library.
+It can be linked e.g. against a library containing arbitrary functionality. Pixelarium can support viewing the results and result files of such a library.
 It tries to be as flexible as possible.
 
 This is still work in progress and will change significantly.
@@ -52,3 +53,4 @@ If you want to specify compiler settings and options which are not defined in a
     cmake --build build
 
 
+

lib/app/app_resources_default.h.in

@@ -4,6 +4,7 @@
 #include <string_view>
 
 #cmakedefine PIXELARIUM_TITLE "@PIXELARIUM_TITLE@"
+#cmakedefine PIXELARIUM_VERSION "@CMAKE_PROJECT_VERSION@"
 
 // clang-format off
 #define MAINMENUNAME        "Menu"

lib/imaging/IPixelariumImage.hpp

@@ -10,12 +10,18 @@ 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.
     UNKNOWN = -10,
+    /// @brief Represents an abstract image type (e.g., a placeholder).
     ABSTRACT = 0,
+    /// @brief Represents a PNG image file.
     PNG = 1,
+    /// @brief Represents a JPG image file.
     JPG = 2,
+    /// @brief Represents a CZI image file.
     CZI = 3,
 };
 
@@ -33,19 +39,38 @@ class IPixelariumImage
    public:
     virtual ~IPixelariumImage() = default;
 
-    // this will have to throw or something for multidimensional images
+    /// @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::unique_ptr<cv::Mat> TryGetImage() = 0;
 
+    /// @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.
     virtual std::unique_ptr<cv::Mat> TryGetImage(const IImageQuery&) = 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::unique_ptr<cv::Mat>> TryGetImages(const IImageQuery&) = 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())
@@ -62,5 +87,4 @@ class IPixelariumImage
    protected:
     std::filesystem::path uri_;
 };
-
 }  // namespace pixelarium::imaging