Ranga

रंग (Sanskrit: color, hue) — Core image processing library for Rust

Ranga provides shared image processing primitives for the AGNOS creative suite, eliminating duplicate color math, blending, conversion, and filter implementations across rasa (image editor), tazama (video editor), and aethersafta (compositor).

Pure Rust core — no C FFI. SIMD acceleration via std::arch, GPU compute via wgpu.

Features

Area	Capabilities
Color spaces	sRGB, linear RGB, HSL, CIE XYZ, CIE Lab*, Oklab, Oklch, Display P3, BT.2020, CMYK
Pixel buffers	`PixelBuffer` with 6 formats, zero-copy `PixelView`, `BufferPool`
Blend modes	12 Porter-Duff modes with SSE2/AVX2/NEON SIMD (2x throughput)
Conversion	BT.601, BT.709, BT.2020, NV12, RGB8↔RGBA8, ARGB8↔RGBA8, RgbaF32↔RGBA8
Filters	24+ filters: blur, sharpen, hue shift, color balance, 3D LUT, vignette, noise, median, bilateral, vibrance
Compositing	Layer masks, dissolve/fade/wipe transitions, gradients, positioned composite (RGBA8 + ARGB8)
Transforms	Crop, resize (nearest/bilinear/bicubic), affine, perspective, flip
Color science	Delta-E (CIE76/94/2000), color temperature, ICC v2/v4 profiles, Oklab/Oklch
Spectral	SPD, CIE 1931 CMFs, standard illuminants, CRI, inverse CCT (via prakash)
Histograms	Luminance, per-channel RGB, chi-squared, equalization, auto-levels
GPU compute	wgpu shaders for blend, filters, noise, transitions, crop/resize/flip, `GpuChain` batched dispatch
Hardware	GPU detection via ai-hwaccel 0.23.3, VRAM/utilization-aware offload

Quick Start

[dependencies]
ranga = "0.24"

use ranga::pixel::{PixelBuffer, PixelFormat};
use ranga::filter;
use ranga::convert;

// Create an RGBA buffer
let mut buf = PixelBuffer::zeroed(1920, 1080, PixelFormat::Rgba8);

// Apply filters
filter::brightness(&mut buf, 0.1)?;
filter::contrast(&mut buf, 1.2)?;
filter::gaussian_blur(&buf, 3)?;

// Convert to YUV for video encoding
let yuv = convert::rgba_to_yuv420p(&buf)?;

Color Science

use ranga::color::*;

// sRGB → CIE Lab
let lab: CieLab = Srgba { r: 128, g: 64, b: 200, a: 255 }.into();

// Delta-E color distance
let distance = delta_e_ciede2000(&lab, &CieLab { l: 50.0, a: 0.0, b: 0.0 });

// Display P3 → sRGB
let (r, g, b) = p3_to_linear_srgb(0.8, 0.3, 0.5);

// Color temperature
let [r, g, b] = color_temperature(3200.0); // warm light

GPU Compute

use ranga::gpu::{GpuContext, gpu_blend, gpu_gaussian_blur};
use ranga::blend::BlendMode;

let ctx = GpuContext::new()?;
gpu_blend(&ctx, &src, &mut dst, BlendMode::Multiply, 0.8)?;
let blurred = gpu_gaussian_blur(&ctx, &buf, 5)?;

Zero-Copy Integration

use ranga::pixel::{PixelView, PixelFormat};

// Borrow existing buffer from rasa/tazama/aethersafta — no copy
let view = PixelView::new(&existing_bytes, 1920, 1080, PixelFormat::Rgba8)?;

Feature Flags

Flag	Default	Description
`simd`	Yes	SSE2/AVX2/NEON acceleration for blend operations
`gpu`	No	wgpu compute shaders with `GpuChain` batched dispatch
`hwaccel`	No	GPU detection via ai-hwaccel 0.23.3
`parallel`	No	Rayon row-parallel blur
`spectral`	No	Physically-based color science via prakash (SPD, CIE CMFs, illuminants)
`full`	No	All features

Performance

Benchmarks at 1080p (1920x1080) on the host machine:

Operation	Time
Blend row (1920px, SIMD)	2.9 µs
Blend row (1920px, scalar)	5.7 µs
Invert	1.0 ms
Grayscale	2.2 ms
Gaussian blur (r=3)	~50 ms
RGBA→YUV420p BT.601	2.1 ms
Color temperature	5.3 ns
Delta-E CIEDE2000	109 ns

Run benchmarks: cargo bench or cargo bench --all-features

Documentation

Guides

Architecture Overview — module map, data flow, design principles
Performance Guide — CPU/GPU crossover, SIMD tiers, benchmarking
Testing Guide — test matrix, coverage, fuzzing, CI
Troubleshooting — common build and runtime issues
Migration Guide — adopting ranga in rasa/tazama/aethersafta

Feature Guides

Color Science — color spaces, Delta-E, ICC, temperature
Blend Modes — 12 modes, SIMD, GPU, positioned composite
Filters — 24+ filters with usage patterns and performance tips
Transforms — crop, resize, affine, flip
Compositing — layer masks, transitions, fill operations
GPU Compute — wgpu shaders, pipeline caching, async readback
Pixel Buffers — formats, views, pool, conversion

Reference

API Reference — rustdoc for all public items
Threat Model — security trust boundaries
Architecture Decisions: 001, 002, 003, 004

Minimum Supported Rust Version

Rust 1.89 (edition 2024).

License

AGPL-3.0-only

ranga 0.24.3