PxOps

PxOps 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), PxOps 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 PxOps, 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

PxOps is built using CMake 3.25+. The build system compiles the main pxops utility, the unit test binaries, the manpage generator, and the benchmarking tools.

A. Release Build (Recommended for Production)

The Release build applies aggressive compiler optimizations, native instruction tuning, fast-math approximations, and parallel loop enablement:

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)

Compiler Optimization Flags Applied:

• -O3 / -DNDEBUG: Maximum optimization and assertions disabled.
• -march=native: Target the host machine's specific CPU instruction set (enabling AVX2, FMA, etc.).
• -fopenmp: Parallel loops activation.
• Fast-Math Flags: -ffinite-math-only -fno-math-errno -freciprocal-math for vectorization speedups in floating-point operations.

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 system's compiler and packages:

mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build . -j$(nproc)

C. Installation

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

cd build
sudo make install

This copies the binary to /usr/local/bin/ and the manpage (pxops.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 pxops

Or view quick help flags directly in your terminal:

pxops --help
pxops render --help

---

5. Benchmarking Suite

PxOps comes with an automated benchmarking suite that compiles and runs operations under two configurations to measure compiler vectorization, OpenMP multithreading, and hardware flag optimization:

1. Naive Optimization Build: Compiled with standard -O3 optimization but without target-specific SIMD instruction sets (-march=native), fast-math approximations, or OpenMP parallel loops.
2. Fully Optimized Build: Compiled with release flags, OpenMP parallelization, fast-math, and target-specific native optimization.

Running the Benchmarks

1. Install graphing Python packages:

   pip install -r tests/bench/requirements.txt

2. Execute the benchmarking suite on the default image or pass a custom image path:

   # Run with default image
   ./tests/bench/run_benchmarks.sh
   
   # Run with custom image
   ./tests/bench/run_benchmarks.sh path/to/my_image.jpg

Output Artifacts

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

• naive_results.json & release_results.json: Raw execution times for each pipeline step.
• vectorization_report.txt: Compiler diagnostic report showing vectorization success.
• comparison_chart.png: Logarithmic execution time comparison chart (lower is better) comparing the naive vs. release builds.
• execution_time_chart.png: Breakdown of optimized execution times for each operation.

---

6. License

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