Color Pipeline

How OpenGPEX manages color spaces across the entire image lifecycle — from import through compositing to export — using a centralized strategy matrix that ensures zero color drift and full ICC profile round-trip fidelity.

Architecture: Centralized Strategy Routing

All color-space decisions are concentrated in a single ColorPipeline.ts strategy matrix. Format handlers, compositors, and renderers query this matrix and execute instructions — they never make autonomous color decisions.

Source File → [FORMAT_COLOR_STRATEGY] → detectedCS → [IMPORT_PIPELINE] → Frame.colorSpace
                                                                              │
                                                                    ┌─────────┴─────────┐
                                                                    ▼                   ▼
                                                            [WORKING_PIPELINE]    sourceBlob?
                                                            composite/display         │
                                                            /export                   ▼
                                                                              compositeFrame + encode
                                                                              (unified 8-bit path)

Core Design Principles

1. Single source of truth — Modify one strategy entry to change behavior globally
2. Only two runtime values — Frame.colorSpace is always 'srgb' or 'display-p3'
3. Handlers are pure executors — They switch/case on strategy instructions, zero if/else judgment
4. Renderer-agnostic — Color management is pipeline logic, not tied to Canvas 2D / WebGL / WebGPU

Two-Layer Strategy System

Layer 1: Format Strategy (by file format)

Decides how to read color metadata and whether to retain the original source blob:

Layer 2: Color Space Strategy (by detected color space)

Decides what happens to pixels at each pipeline stage:

Wide-Gamut (Display P3) Support

OpenGPEX natively supports Display P3 as a working color space:

• Import: P3 source files set Frame.colorSpace = 'display-p3' directly; AdobeRGB/ProPhoto are matrix-converted to P3 at import time (one-shot, ~4ms/1080p)
• Composite: Canvas 2D context created with { colorSpace: 'display-p3' } — zero per-layer conversion overhead
• Display: Auto-detects P3 hardware via color-gamut: p3 media query; falls back to sRGB + matrix clamp on non-P3 displays
• Export: P3 pixels encoded directly + ICC Profile embedded (PNG/JPEG/WebP/AVIF/TIFF)

Import-Time Conversion (Choice A)

AdobeRGB/ProPhoto pixels are converted to P3 once during decode(), not at composite time. This means:

• Zero composite overhead — No per-layer, per-frame conversion during editing
• Full export fidelity — sourceBlob preserves the original file for lossless round-trip
• Simple architecture — Compositing only ever sees sRGB or P3 pixels

Export Color Management

All export follows the unified single-path architecture: compositeFrame (8-bit) → files.encode → download. Color decisions are made inline with no separate routing or strategy resolution.

Export Decisions

Two color-related decisions are made at export time:

ICC Embed Three-Layer Model

Layer 1: Format capability      (BMP/GIF → never; PNG/JPEG/WebP/AVIF/TIFF → allowed)
Layer 2: Strategy default        (sRGB: true; P3: true — matches Photoshop/Lightroom)
Layer 3: User override           (export UI checkbox, if provided)

Color Pipeline Infrastructure

Matrix Conversion Engine

Pure TypeScript 3×3 linear matrix transforms (zero external dependencies):

TRC (Transfer Curve) Handling

• sRGB ↔ linear conversion via pre-computed LUT (~2ms/4K)
• Linear-light compositing for physically-correct blend modes
• Filter TRC auto-insertion (blur executes in linear, auto-converts back)

ICC Profile Support

Format × Color Space Matrix (Summary)

Comparison with Desktop Applications

Known Limitations & Future

Last updated: 2026-08-08