Pixel Studio v0.2.0

A high-performance, cross-platform C++23 Image Processing & Computer Vision Analytics Engine. Engineered with an Immediate Mode UI (Dear ImGui), OpenMP parallelization, Structure-of-Arrays (SoA) memory layouts, and zero-overhead GPU telemetries.

---

📸 Overview & Purpose

Pixel Studio was designed as a dual-purpose engine:

1. Computer Vision Educational Inspection Platform: Built specifically to visualize and intuitively understand complex CV algorithms (such as Harris Corner Detection and upcoming multi-scale descriptors like SIFT and SURF). With real-time slider updates, step-by-step pipeline inspection (Sobel gradients, Gaussian smoothing, keypoint thresholds), students and engineers can inspect algorithm internals down to the raw pixel level.
2. High-Performance C++ Engineering: Engineered from the ground up to handle high-resolution imagery (up to 48 Megapixels+) with sub-second execution times. It serves as a real-world benchmark for low-level system design, thread parallelism, and hardware-aware resource management.

---

🔄 Data Structure Refactor: Evolution from YUVA (float) to YCgCoA SoA

As announced in the project roadmap, the core image representation was refactored to replace the initial float-based YUVA Structure of Arrays (SoA) with a highly optimized, packed YCgCoA layout.

Why the Refactor Was Needed

Initially, a 16-byte-per-pixel float representation (4 × float32) was chosen because most image processing algorithms mathematically operate on continuous range values $[0.0, 1.0]$. While logical for initial algorithm development, holding full 32-bit floats for every channel in main memory created an unnecessarily large memory footprint.

The New YCgCoA Memory Layout

The new hybrid SoA structure maintains precision where required while cutting memory usage drastically:

• Memory Footprint: Reduced from 16 Bytes/pixel down to 6 Bytes/pixel (2 × uint8_t for Y & Alpha + 2 × int16_t for Cg & Co).
• Cache Efficiency: Shrinking the primary luminance channel ($Y$) from 4 Bytes to 1 Byte increases CPU cache line density by 4×. Since the vast majority of image manipulation algorithms only iterate over the $Y$ channel, cache hit rates and SIMD throughput increased significantly across all core operations.
• Streamlined Conversions: Because Alpha is now handled directly as uint8_t without needing float-to-int conversion or clamping, both toYCgCoA() and toRGBA() no longer require separate execution loops for uniform vs. non-uniform Alpha. Both now operate in a clean, single-pass loop.
• Fast Bit-Shifts: Integer representation enables fast bit-shift operations for gradient computations ($I_x$, $I_y$), while algorithms requiring extended dynamic range ($I_{xx}$, $I_{yy}$, $I_{xy}$, and Harris $R$-values) intentionally retain their dedicated float pipelines.

Metric	Legacy YUVA SoA (float)	Refactored YCgCoA SoA	Difference
Pixel Memory Footprint	16 Bytes / Pixel	6 Bytes / Pixel	-62.5%
48 MP Image Memory	~768 MB	~288 MB	-480 MB saved
Conversion Time (toYCgCoA, 48 MP)	~40.0 ms	~18.5 ms	+116% faster
Cache Line Density (Y-Channel)	4 pixels / line	16 pixels / line	4x Density
Conversion Loops (toYCgCoA / toRGBA)	2 loops (Alpha-dependent)	1 loop (Unified)	Simplified

---

⚡ High-Impact Features & Architecture Highlights

🎯 1. O(1) Stamp-Based Validation & Invalidation System

To prevent redundant computation across multi-stage image processing pipelines, Pixel Studio incorporates an $O(1)$ Stamp Verification Engine:

• Answers pipeline questions instantly: Does the active RGBA display vector match the selected image? Is the cached padImg based on the current image? Has Harris Detection executed on this exact dataset version?
• Eliminates buffer thrashing and invalidates downstream passes only when parent parameters change.

🧵 2. Thread Parallelism via OpenMP

• High-intensity spatial convolutions (Sobel derivatives, separable 1D Gaussian blurs, Non-Maximum Suppression) and any heavy lifting image manipulation algorithms are accelerated using OpenMP loop parallelization.
• To prevent UI thread lockups and complex race conditions within the Immediate Mode GUI, thread parallelism is strictly constrained to the processing algorithms - keeping the UI event loop completely deterministic and serial.

🖥️ 3. Hardware-Aware System Inspection (SysInfo)

Pixel Studio queries hardware topologies dynamically at initialization:

• Physical Core Affinity: Filters out virtual logical threads (Hyper-Threading / SMT) to determine the actual number of physical cores and automatically calculates the optimal OpenMP chunk size for the running system.
• Native OS Integration: Leverages OS-native FileChoosers (with pre-configured extension filters) and automatically syncs the UI theme (Light/Dark Mode) with system preferences upon startup.
• Cross-Platform Resilience: Uses conditionally compiled platform shims (#defines) to ensure clean compilation across Windows and Linux (CachyOS/GCC/Clang).

📐 4. Scalable Immediate Mode UI (UIComponents)

• Custom-crafted UI elements: CustomMenuItem, CustomTabButton, ThemeToggleButton, and ToggleButton.
• DPI-Aware Scaling Engine: Dynamically queries screen DPI at application launch to establish an absolute base scaling factor (UI::em). All UI dimensions, padding, and font hierarchies are pre-scaled once at startup - eliminating runtime layout recalculation during ImGui frames.

📊 5. Deterministic VRAM Tracking & Telemetry

• Deterministic Local Accounting: Initialized via native OpenGL driver queries at startup, followed by immediate, zero-latency byte-level tracking ($+ \text{Alloc} / - \text{Dealloc}$) on every GPU texture mutation and window/viewport resize event - bypassing blocking GPU driver polling during event-driven GUI loops (glfwWaitEvents).
• Smart Texture Lifecycle: VRAM textures for intermediate gradient inspection ($I_x, I_y, I_{xx}, I_{yy}, I_{xy}$) are loaded lazily on-demand and freed during algorithm rebuilds or tab closures.
• Live Status Indicator: Real-time color-coded feedback (🟢 GOOD < 60%, 🟡 WARN 60–85%, 🔴 ALERT > 85%) warns users of system VRAM pressure.

🛡️ 6. Exception-Free Diagnostics & Telemetry Frame

• Safety-Critical Design Pattern: Built strictly around deterministic error propagation (-fno-exceptions compatible) to eliminate non-deterministic stack-unwinding overhead and guarantee complete control over failure states within critical processing loops.
• Non-Blocking Telemetry & Status Pipeline: Implements a lightweight status-code, log, and metrics tracking system that channels internal warnings, file I/O states, and algorithm metrics directly into non-interfering UI toasts and status monitors.
• Guaranteed Control Flow: Pipeline and asset failures (e.g., via C-style stb error status checks) are gracefully captured through explicit result propagation, ensuring zero thread stagnation and 100% deterministic execution under all conditions.

⚡ 7. Dynamic Frame Pacing & Modal-Aware Event Loop

Pixel Studio combines power-efficiency with buttery-smooth UI animations through an adaptive event-driven render loop:

• Resource-Conscious Idle State: When the user is idle, the application suspends redundant rendering frames via glfwWaitEvents(), dropping CPU/GPU usage to virtually 0%.
• Automatic Animation Bypass: To prevent frame stuttering during modal interactions, popups, and dialog transitions, the engine continuously monitors GImGui->DimBgRatio.
• Seamless Pacing: While any backdrop dimming or UI animation is active, the wait-event mechanism is dynamically bypassed to enforce smooth, real-time rendering. As soon as the modal closes and animations subside, the system immediately drops back into low-power idle mode.

---

🖼️ Interactive Showcase & Inspection Views

🎯 Mathematical Precision & Synthetic Verification

Rigorous validation of the Harris-Stephens implementation using a synthetic geometric calibration grid. All 148 keypoints are detected with zero false positives along edge contours, confirming exact Eigenvalue computation and Non-Maximum Suppression (NMS).

---

🔬 Pipeline Inspection & Feature Detection

Vertical Gradient Matrix ($I_y$)	Architecture Feature Density ($I_{yy}$)
Real-time $I_y$ spatial gradient visualization via OpenMP-accelerated Sobel convolution.	Stress-testing on complex real-world data ($3648 \times 2365$ px) detecting 7,300+ keypoints with custom color overlays.

---

🎨 Bonus: Creative Pipeline Synthesis (Optional)

Demonstrating multi-stage execution - combining image inversion, color-space segmentation, and parallel feature extraction on a 30 MP landscape composition.

---

🔬 Performance Benchmarks

Evaluated on a 48 Megapixel (8000 × 6000) image payload:

Pipeline Stage	Processing Time ($\Delta t$)	Description
Border Extension (Padding)	~3.33 ms	Boundary padding by filter radius $r$ to prevent edge artifacts
Sobel Gradient Pass	~51 ms (parallel)	Dual-axis spatial gradient calculation ($I_x, I_y$)
Separable Gaussian (5×1D)	~140 ms (parallel)	Multi-channel horizontal/vertical smoothing pass ($I_{xx}, I_{yy}, I_{xy}$)
Keypoint Extraction (NMS)	~11 ms (parallel)	Non-Maximum Suppression (246,652 points @ $k=0.04$, $t=0.05$)
Total Pipeline Execution	~220 ms (parallel)	Full end-to-end execution on 48MP input

---

🗺️ Roadmap & Future Enhancements

• uint8_t YUVA Memory Refactor: Transitioning internal floating-point buffers to integer-aligned uint8_t layouts to cut memory footprints by 75% and unlock AVX2/AVX-512 vectorization.
• Multi-Scale Feature Descriptors: Implementing scale-space pyramids for SIFT and SURF feature detection and matching pipelines.

---

🛠️ Toolchain, Dependencies & Build Guide

🧱 Core Architecture & Dependencies

• Language Standard: Modern C++23
• GUI Framework: Dear ImGui (by Omar Cornut) backed by GLFW
• Image I/O: stb library (by Sean Barrett) for single-header loading/saving
• Parallelization: OpenMP 5.0+ (Multi-threaded processing for all parallelizable image algorithms)
• Graphics API: OpenGL 3.3+ (Core Profile)
• Target Platforms: Windows 11 & Linux (CachyOS / Arch / Ubuntu)

---

🚀 Building from Source

Pixel Studio relies on a clean, vendor-decoupled folder layout (/include, /src, /external). Pre-compiled static libraries and third-party headers reside within /external.

1. Prerequisites & System Packages

Ensure you have a modern C++23 compliant toolchain installed (LLVM/Clang 16+ or GCC 13+).

• Linux (CachyOS / Arch):

   sudo pacman -S base-devel clang gcc glfw-x11 openmp zenity

• Linux (Ubuntu / Debian):

   sudo apt install build-essential clang g++ libglfw3-dev libomp-dev zenity

• Windows:

  MSYS2 environment with clang / gcc, make, and Windows SDK headers.

  Note on OpenMP Support: While Pixel Studio automatically builds and runs in serial fallback mode if OpenMP is omitted, installing OpenMP support is strongly recommended to unleash full multi-threaded performance on multi-core CPUs.

  Note on File System & Assets: Pixel Studio relies on relative project paths upon initialization. Place your test input images inside the defaultDIR/IN/ directory. Exported results target defaultDIR/OUT/ by default unless overridden via the OS-native FileChooser.

---

2. Building on Windows (MSYS2 / Clang / MinGW)

# Clone the repository & then change into project root
git clone https://github.com/iibram/PixelStudio.git
cd PixelStudio

# 1. Compile third-party dependencies once (ImGui & GLAD)
clang++ -std=c++23 -O3 -w -isystem "./external/include" -isystem "./external/include/ImGui" -c external/include/ImGui/*.cpp
clang++ -O3 -w -isystem "./external/include" -c external/include/glad/glad.c

# Move generated objects to vendor lib folder
mv *.o external/lib/

# 2. Compile Windows Application Icon
windres resources.rc -O coff -o icon.o

# 3. Build Release Binary
clang++ -std=c++23 -O3 -march=native -ffast-math \
	-isystem "./external/include" \
	-I"./include" src/*.cpp ./external/lib/*.o icon.o \
	-L"./external/lib" \
	-fopenmp -lomp -lglfw3 -lopengl32 -lgdi32 -limm32 -lcomdlg32 -lole32 -lshell32 \
	-o "./PixelStudio.exe"

# Launch Engine
./PixelStudio.exe

---

3. Building on Linux (Clang or GCC)

# Clone the repository & then change into project root
git clone https://github.com/iibram/PixelStudio.git
cd PixelStudio

# 1. Compile third-party dependencies once (ImGui & GLAD)
clang++ -std=c++23 -O3 -w -isystem "./external/include" -isystem "./external/include/ImGui" -c external/include/ImGui/*.cpp
clang++ -O3 -w -isystem "./external/include" -c external/include/glad/glad.c

# Move generated objects to vendor lib folder
mv *.o external/lib/

# 2. Build Release Binary (using Clang or GCC)
# Using Clang:
clang++ -std=c++23 -O3 -march=native -ffast-math \
    -isystem "./external/include" \
    -I"./include" src/*.cpp ./external/lib/*.o \
    -fopenmp -lglfw -lGL -ldl -lpthread -o "./PixelStudio"

# Alternatively, using GCC:
g++ -std=c++23 -O3 -march=native -ffast-math \
	-isystem "./external/include" \
	-I"./include" src/*.cpp ./external/lib/*.o \
	-fopenmp -lglfw -lGL -ldl -lpthread -o "./PixelStudio"

# Launch Engine
./PixelStudio

---

👤 Author & Project Status

• Author: Ibrahim Ibram
• Status: Active Open-Source Project

Development Note: Pixel Studio is under active evolution. APIs, internal layout IDs, and pipeline methods may be refactored as new multi-scale algorithms (SIFT/SURF) and memory optimizations are integrated.

---

📄 License

This project is licensed under the MIT License – see the LICENSE file for full details.

---