PixelFlow

High-Performance Composable Image Processing Engine & Web Studio

PixelFlow is an enterprise-grade image processing pipeline system, Typer CLI, FastAPI microservice, and interactive Web Studio built for Python 3.12+. Engineered for speed, safety, and composability, PixelFlow executes 54+ native operations across computational photography, document scanning (CamScanner suite), cinematic color grading, biometric visa composition, and vector annotation with immutable NumPy arrays and strict Pydantic v2 validation.

• 54+ Built-in Operations: Comprehensive catalog covering geometry, spatial filters, edge detection, CLAHE enhancement, 3-way color wheels, cinematic LUTs, face blurring, AI background removal, and vector watermarking.
• PixelFlow Studio (Web GUI): Modern, responsive web studio featuring a dark OLED aesthetic, Bento Grid workflow launchpad, 0ms hardware-accelerated preview, Curtain Before/After comparison, and Zero-UI focus mode.
• CamScanner Document Suite: Automatic document deskew, 4-corner perspective warping, shadow removal, magic color whitening, signature extraction, PII masking (ID/IBAN redaction), and vector stamps.
• Biometric Photo & Visa Composer: Automated multi-up print layouts for ICAO 35x45mm (Schengen, Turkish ID/Passport) and US Visa 50x50mm specifications with cut guides.
• Squoosh-Grade Export Optimizer: Live compression comparison across WEBP, JPEG, and PNG formats with dynamic size savings estimation.
• Multi-Page PDF Processing: Seamless PDF-to-image extraction, page manipulation (split, rotate, reorder), and multipage PDF re-compilation.
• Strict Type & Schema Safety: Fully typed with Pydantic v2 parameter models, mypy --strict compliance, and line-aware YAML syntax validation.
• High-Throughput Concurrency: Multi-core batch processing via ProcessPoolExecutor with Rich CLI progress visualization, alongside an asynchronous FastAPI service with request-ID distributed tracing.

• PixelFlow
  • Highlights
  • Table of Contents
  • System Architecture
  • Installation
  • PixelFlow Studio (Web Interface)
  • CLI Quickstart
    • 1. Generate Sample Assets
    • 2. Validate Pipeline Definitions
    • 3. Execute a Pipeline on a Single Image
    • 4. Multi-Worker Batch Processing
    • 5. Inspect Registered Operations
  • REST API Reference
    • Endpoints
    • API Usage Examples
  • Pipeline Specification
    • YAML Syntax Example
  • Operation Catalog
    • Document & Office Suite
    • Color, Tone & Grading
    • Cinematic & Creative Filters
    • AI, Retouch & Detection
    • Geometry & Transforms
    • Spatial Filters & Smoothing
    • Edge Detection & Morphology
    • Overlay, Stamp & Watermark
  • Creating Custom Operations
  • Performance Benchmarks
  • Development & Quality Assurance
  • License

                    +------------------------------------------+
                    |          PixelFlow Studio (Web)          |
                    |   Bento Launchpad | 0ms Preview | Wheels |
                    +--------------------+---------------------+
                                         |
                       REST / Multipart  |  CLI Commands
                                         v
+--------------------------------------------------------------------------+
|                            PixelFlow Core                                |
|                                                                          |
|  +--------------------+  +--------------------+  +--------------------+  |
|  |   Pipeline Engine  |  | Operation Registry |  |   Pydantic Models  |  |
|  | (YAML/JSON Loader) |  |   (54+ Handlers)   |  |   (Strict Schema)  |  |
|  +--------------------+  +--------------------+  +--------------------+  |
|                                                                          |
|  +--------------------+  +--------------------+  +--------------------+  |
|  |     Image I/O      |  |  Batch Multi-Core  |  |  Structured Logs   |  |
|  | (NumPy/OpenCV/PDF) |  | (ProcessPoolExec)  |  | (JSON with Req-ID) |  |
|  +--------------------+  +--------------------+  +--------------------+  |
+--------------------------------------------------------------------------+

• Python 3.11+ (Python 3.12 recommended)
• uv (recommended) or standard pip

git clone https://github.com/your-org/pixelflow.git
cd pixelflow
uv sync --all-extras

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[all]"

PixelFlow ships with a built-in, zero-dependency browser application optimized for creative and office workflows.

uv run uvicorn pixelflow.api.app:create_app --factory --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000 in your web browser.

• Zero-Latency Visual Feedback: Tone and exposure adjustments (brightness, contrast, vibrance, saturation) apply instant client-side CSS filter transformations (0ms response) while debouncing the full-precision OpenCV/NumPy pipeline run with automatic in-flight request cancellation (AbortController).
• Curtain & Split Comparison: Compare original and processed assets with an interactive draggable curtain split-view or dual-viewport split mode.
• 3-Way Color Wheels: Professional Lift, Gamma, and Gain controls with master luminance sliders.
• Squoosh-Style Optimizer: Interactive modal for comparing real-time image compression ratios across WebP, JPEG, and PNG formats.
• Multi-Page Document Manager: Reorder, rotate, split, and merge multi-page PDF documents directly in the browser.
• Biometric Card Studio: Generate ready-to-print passport and visa sheets with cut-line overlays.
• Command Palette & Themes: Press Ctrl+K for instant command search. Supports Tokyo Night, DaVinci Gold, Cyberpunk, and Titanium OLED themes.

The PixelFlow CLI (pixelflow) is powered by Typer and provides commands for execution, validation, batch processing, and inspection.

Create synthetic test documents and photographic assets:

uv run python examples/generate_samples.py

Verify syntax, operation availability, and parameter bounds with line-number error reporting:

uv run pixelflow validate examples/document-cleanup.yaml

uv run pixelflow run examples/document-cleanup.yaml examples/assets/sample_document.png \
  --output examples/assets/cleaned_document.png \
  --verbose

Apply a watermark and thumbnail resize:

uv run pixelflow run examples/thumbnail-with-watermark.yaml examples/assets/sample_photo.png \
  --output examples/assets/thumb_photo.png

Process an entire directory of images concurrently using worker processes:

uv run pixelflow batch examples/thumbnail-with-watermark.yaml examples/assets \
  --output-dir examples/output \
  --workers 4

List all available operations or inspect parameter requirements:

# List all 54 registered operations
uv run pixelflow ops list

# Inspect detailed schema and parameters for an operation
uv run pixelflow ops describe magic_color
uv run pixelflow ops describe perspective_warp

PixelFlow exposes a production-ready FastAPI service with OpenAPI specification, health endpoints, and request tracing.

curl -s -X POST http://127.0.0.1:8000/v1/process \
  -H "X-Request-ID: req-001" \
  -F "image=@examples/assets/sample_document.png;type=image/png" \
  -F "pipeline=<examples/document-cleanup.yaml" \
  --output output_cleaned.png

curl -s -X POST http://127.0.0.1:8000/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"pipeline": "name: test\nversion: \"1.0\"\nsteps:\n  - op: brightness_contrast\n    params:\n      brightness: 0.1\n      contrast: 1.2"}'

Pipelines are declared in YAML or JSON. Each pipeline must include name, version, and an ordered list of steps. Every step specifies the target operation (op), an optional descriptive name, and required or optional params.

name: professional-document-scan
version: "1.0"
steps:
  # 1. Correct perspective skew
  - op: deskew
    name: auto_align_text
    params:
      max_angle: 45.0

  # 2. CamScanner magic color filter
  - op: magic_color
    name: enhance_paper_and_ink
    params:
      mode: magic
      whiten_strength: 0.85
      sharpen_strength: 1.2

  # 3. Clean paper shadows
  - op: shadow_removal
    name: remove_lighting_gradients
    params:
      kernel_size: 31

  # 4. Official company seal overlay
  - op: stamp
    name: apply_official_stamp
    params:
      text: "APPROVED"
      kind: circular
      color: [180, 20, 20]
      x: 420
      y: 650

PixelFlow includes 54 built-in operations across 8 functional domains:

PixelFlow is modular and extensible. To implement a custom operation:

1. Subclass OperationParams using Pydantic fields.
2. Subclass ImageOperation[YourParams].
3. Decorate with @register_operation("your_operation_name").

from typing import cast
import numpy as np
from pydantic import Field
from pixelflow.core.operation import ImageArray, ImageOperation, OperationParams
from pixelflow.core.registry import register_operation


class ColorThresholdParams(OperationParams):
    cutoff: int = Field(default=128, ge=0, le=255, description="Luminance threshold cutoff.")


@register_operation("invert_above")
class InvertAboveOperation(ImageOperation[ColorThresholdParams]):
    params_model = ColorThresholdParams

    def _execute(self, image: ImageArray) -> ImageArray:
        result = np.where(image >= self.params.cutoff, 255 - image, image)
        return cast(ImageArray, result.astype(image.dtype))

Once defined or imported, invert_above becomes instantly accessible across YAML pipelines, CLI commands, REST endpoints, and the Web Studio.

Tested on 32 synthetic 640x480 RGB images running the 4-step examples/document-cleanup.yaml pipeline across multiple worker processes (ProcessPoolExecutor):

Measured on a 720x480 image (Decode + Execution + Encode):

Run code formatting, type checking, test suites, and Docker builds:

# Code formatting and lint checks (ruff, black, isort)
make lint

# Static type analysis with mypy strict mode
uv run mypy src/pixelflow

# Run full test suite with coverage
make test

# Build container image
make docker

PixelFlow is released under the MIT License.