ImgCtl

ImgCtl is a high-performance image processing engine and command-line utility built strictly for human perceptual accuracy.

Unlike traditional graphics tools that perform pixel blending and math in non-linear sRGB (leading to darkened blurs, hue shifts, and "dead" color transitions), ImgCtl operates exclusively in the perceptually uniform OKLab and OKLCH color spaces. This ensures that every operation—from a simple resize to complex duotones and glassmorphism—is mathematically flawless and visually natural to the human eye.

---

1. Vision & Core Architecture

• Perceptual-First: All internal blending, gradients, adjustments, and analysis occur in OKLab or OKLCH. sRGB is used solely for standard input decoding and output encoding.
• Zero-Allocation Hot Path: Runtime allocations are strictly forbidden during pixel execution. All temporary image buffers, intermediate convolution buffers, and text boundaries are allocated from a pre-allocated Arena Allocator.
• AST-Optimized Pipeline: CLI commands are compiled into an Abstract Syntax Tree (AST), optimized by automatically reordering O (1) operations (like crop) before O (N) spatial/pixel operations, and executed in a minimal number of cache-coherent passes.
• Modern C++ Engineering: Built on the C++23 baseline, using std::span for safe buffer slicing, standard mathematical library improvements, and generic programming.
• Hardware-Accelerated SIMD & Multithreading: Hot loops are vectorized using OpenMP parallel loops and structured for compiler auto-vectorization (AVX2/AVX-512/NEON), taking advantage of multi-core processors.

---

2. Dependencies & Prerequisites

To build and run ImgCtl, you need a C++23-compliant compiler, CMake 3.25+, and the following development libraries:

• FreeType (font rendering)
• HarfBuzz (text shaping)
• OpenMP (multithreading acceleration)
• Python 3 & Pip (benchmarking suite)

Install the prerequisites using your platform's package manager:

Installation Commands

Debian / Ubuntu (apt)

sudo apt update && sudo apt install -y build-essential cmake libfreetype-dev libharfbuzz-dev libomp-dev python3 python3-pip

Fedora / RHEL (dnf)

sudo dnf install -y gcc-c++ cmake freetype-devel harfbuzz-devel libomp-devel python3 python3-pip

Arch Linux (pacman)

sudo pacman -S --needed base-devel cmake freetype2 harfbuzz openmp python python-pip

macOS (brew)

brew install cmake freetype harfbuzz libomp python3

---

3. Build & Installation Guide

ImgCtl utilizes standard CMake Presets (CMake 3.25+). The build system compiles the main imgctl utility, the unit test binaries, the manpage generator, and the benchmarking tools.

A. Release Build (Recommended for Production)

cmake --preset release
cmake --build --preset release

B. Debug Build (For Development)

The Debug build includes full debug symbols and excludes fast-math optimizations for precise debugging. Sanitizers (Address and Undefined Behavior) are automatically detected and enabled in this build type if supported by your compiler:

cmake --preset debug
cmake --build --preset debug

C. Running Unit Tests

Run tests directly using CTest presets:

ctest --preset release
# or for debug build:
ctest --preset debug

D. Single-Command Workflows (Configure + Build + Test)

Run the full end-to-end pipeline in a single step:

cmake --workflow --preset release
# or for debug build:
cmake --workflow --preset debug

E. Installation

To install the imgctl binary and the generated manpage onto the system:

sudo cmake --install build/release

This copies the binary to /usr/local/bin/ and the manpage (imgctl.1) to /usr/local/share/man/man1/.

---

4. Subcommands & Usage Reference

Full details on command-line subcommands, rendering operations, options, and environmental configurations are exhaustively documented in the system manpage. You can view the complete reference manual by running:

man imgctl

Or view quick help flags directly in your terminal:

imgctl --help
imgctl render --help

---

5. Benchmarking Suite

ImgCtl comes with an exhaustive, pure C++ automated benchmarking suite covering 41 operations across 6 categories (Color Science & Analytics, Spatial Filters, Point Operations, Geometric Transforms, Smart Analysis, and Typography/Effects).

The suite measures throughput (MP/s) and compares execution times across two builds:

1. Naive Optimization Build: Compiled with standard -O3 baseline optimization without SIMD or OpenMP.
2. Fully Optimized Build: Compiled with CMake release presets (-march=native, OpenMP, fast-math).

Running the Benchmarks

Execute the benchmarking suite by providing a sample image:

./tests/bench/run_benchmarks.sh path/to/image.jpg

Output Artifacts

The script outputs results to tests/bench/results/:

• benchmark_report.csv: CSV performance report containing execution times, speedup ratios, and throughput (MP/s).
• naive_results.json & release_results.json: Raw execution data for both configurations.

---

6. License

ImgCtl is distributed under the terms of the MIT License. See LICENSE for details.