#+options: author:t broken-links:nil c:nil creator:nil
#+options: timestamp:t title:t toc:t todo:t |:t
#+title: Pixelarium
#+subtitle: A Image Vizualizer based on DearImGUI
#+date: <2025-03-12 Wed>
#+author: Maximilian Kueffner
#+exclude_tags: noexport

[[https://github.com/m-aXimilian/pixelarium/actions/workflows/ci-workflow.yml][file:https://github.com/m-aXimilian/pixelarium/actions/workflows/ci-workflow.yml/badge.svg]]
[[https://github.com/m-aXimilian/pixelarium/actions/workflows/mega-linter.yml][file:https://github.com/m-aXimilian/pixelarium/actions/workflows/mega-linter.yml/badge.svg]]

* Synopsis

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 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.

* Supported Types

Currently, Pixelarium supports the following image file formats:
- jpeg
- png
- tiff
- czi


where possible, the [[https://docs.opencv.org/3.4/d4/da8/group__imgcodecs.html][OpenCV codecs]] are used to interpret the respective file type. The czi-format is supported via [[https://github.com/ZEISS/libczi][libCZI]].

* Prerequisites

Dependencies are either submodules in the =modules= subdirectory or artifacts of the cmake build process from the =cmake= directory. This repository should therefore be cloned recursively:
#+begin_src sh
  git clone --recurse-submodules https://github.com/m-aXimilian/pixelarium.git
#+end_src

Apart from that, this project needs OpenCV installed on the host system and available for cmake's =find_package=.

* Building

Given that the prerequisites are fulfilled, building can be achieved via one of the presets or by calling cmake directly.

** Presets

Pixelarium has a few presets setting specific compilers and configurations defined in =CMakePresets.json=.

They can be listed by calling
#+begin_src sh :results raw :wrap src sh
  cmake --list-presets
#+end_src
which will give something like
#+RESULTS:
#+begin_src sh
Available configure presets:

  "clang-release"
  "clang-debug"
  "gcc-release"
  "gcc-debug"
#+end_src

Building with the =clang-debug= preset would look like
#+begin_src sh
  cmake --preset clang-debug
  cmake --build --preset clang-debug
#+end_src

** Direct

If you want to specify compiler settings and options which are not defined in a preset, use cmake "directly" like
#+begin_src sh
  cmake -B build -S .
  cmake --build build
#+end_src

* Usage

All there is to do in order to get an initial window on screen is to create an instance of [[file:lib/app/AppGLFW.hpp][=AppGLFW=]] (or one of its child classes) and start it.

#+begin_src C++
  unique_ptr<ILog> logger = make_unique<SpdLogger>("logfile.log", "loggername");
  ImageResourcePool image_pool;

  auto app {DefaultApp(*logger, image_pool)};
  app.Start();
#+end_src

This will get the default application on screen which looks like
[[file:doc/figures/default-app.png]]


The [[file:examples/][examples]] directory aims to showcase a few usage examples of this project.

** [[file:examples/simple/][simple]]

This is the most straight-forward usage of Pixelarium. It simply instantiates a [[file:lib/app/DefaultApp.hpp][=DefaultApp=]] and runs it.

** [[file:examples/custom_0/][custom_0]]

This is meant to showcase that [[file:lib/app/DefaultApp.hpp][=DefaultApp=]] ([[file:lib/app/AppGLFW.hpp][=AppGLFW=]] as well) is meant to be customized via inheritance.
As a usage example, it implements a simple binary image reader. It can be presented with a binary file of layout
#+begin_src C++
  struct ParsedImage
  {
      uint8_t depth;
      uint8_t channels;
      uint16_t width;
      uint16_t height;
      void* data;
  };
#+end_src
i.e., a header encoding 1 byte for the pixel-depth, 1 byte for the channel count, 2 byte each for width and height in pixel followed by the actual pixeldata.

** [[file:examples/custom_1/][custom_1]]

An example showcasing how to inject a user defined control into the existing scaffolding of =DefaultApp= using a multiplication filter. This is in many ways similar to the previous example.