pixon 0.8.0

SIMD-dispatched color conversion for the FFmpeg AVPixelFormat space: one-call decode of validated source frames to RGB / RGBA / Luma / HSV, fused resampling while converting, colorimetry-honest matrices and chroma siting, no_std-friendly.
Documentation

SIMD-dispatched color-conversion kernels covering the FFmpeg AVPixelFormat space, with a Sink-based API so consumers pick which derived outputs (RGB / Luma / HSV / custom) they want without paying for the ones they don't.

What it is

pixon is a header-light, no_std-friendly color-conversion library for video pipelines:

  • One-call decode — the Convert builder turns a validated source frame into any subset of RGB / RGBA / Luma / HSV with zero redundant parameters, an optional fused resize, and a single fallible call. See Quick start.
  • SIMD-dispatched — every kernel ships NEON, SSE4.1, AVX2, AVX-512, and wasm-simd128 backends plus a scalar fallback, selected once at startup (no per-row branching). The scalar path is the reference implementation every other tier is equivalence-tested against.
  • Sink-based output — pick exactly which derived outputs a frame produces (RGB, RGBA, Luma, HSV, …); unused kernels don't compile, so binaries don't carry dead code.
  • FFmpeg-coverage — source-format markers track the FFmpeg AVPixelFormat space (YUV planar / semi-planar / packed / 4:4:4 packed, Y-series, V210, RGB 8/10/16/F16/F32, GBR, Gray, XYZ, Bayer, PAL8 / Mono). Pair pixon with mediaframe for the pixel-data + SourceFormat traits the kernels are generic over.
  • Colorimetry-honest — fourteen H.273 ColorMatrix values decode, including the non-affine ICtCp, IPT-C2, SMPTE ST 2085 and chroma-derived variants; the ones pixon has no decode for are refused at the door (ColorSpec::kernel_matrix) rather than converted as BT.709. ChromaLocation drives siting-aware chroma upsampling (center / co-sited, top / bottom variants included), and SMPTE ST 428-1 primaries can be interpreted per FFmpeg's tabulated values or as true CIE XYZ.
  • Fused resampling — downscale while converting in a single pass: a resampler splices into the convert pipeline at the earliest stage that realizes its averaging domain, so the frame is binned once and converted once. Box-coverage (cv2.INTER_AREA), separable filter kernels (PIL-byte-exact for u8), and swscale BICUBLIN are all available, with optional gamma-correct (linear-light) and scene-referred averaging. See Resampling.

Quick start

use pixon::{ColorMatrix, ColorSpec, Convert, DynamicRange, PixelFormat};
use pixon::frame::Yuv420pFrame;

fn decode(y: &[u8], u: &[u8], v: &[u8], w: u32, h: u32) -> Result<Vec<u8>, pixon::Error> {
    let frame = Yuv420pFrame::new(y, u, v, w, h, w, w / 2, w / 2);
    let spec = ColorSpec::resolve(PixelFormat::Yuv420p, DynamicRange::Limited, ColorMatrix::Bt709);

    let mut rgb = vec![0u8; 1280 * 720 * 3];
    Convert::from(&frame)      // dimensions + format come from the frame
        .spec(spec)            // one colorimetric truth; per-format knobs derive from it
        .resize(1280, 720)     // optional fused downscale
        .rgb(&mut rgb)         // attach any subset of outputs
        .run()?;               // the only fallible call
    Ok(rgb)
}

The outputs Convert writes, any subset at once:

setter buffer sources
rgb packed 8-bit RGB, w * h * 3 bytes every source
rgba packed 8-bit RGBA, w * h * 4 bytes every source (opaque α where it has none)
luma one 8-bit plane, w * h bytes every source
hsv three 8-bit planes every source (the setter rides the yuv-planar feature)
rgb_u16 packed u16 RGB, w * h * 3 samples at RgbU16Source::RGB_U16_DEPTHS every source with a u16 face: the high-bit YUV, YUVA, gray, GBR, packed RGB and float formats, the legacy packed RGB formats, Pal8, mono and XYZ12

rgb_u16 is the native-depth face: a 10-bit picture's samples come back in 0..=1023, and a legacy packed RGB picture's each at its channel's own width (RgbDepths, 5/6/5 for Rgb565). It is what an HDR picture is decoded through before hdr::SdrMapping::map_rgb16 maps it at the precision it has. On a source with no u16 face it does not compile.

Convert is the golden path for every supported source format. When you need streaming, a custom sink, custom output geometry, or Bayer, drop one tier down: assemble a MixedSinker and drive it with the matching {format}_to walker — the same machinery Convert runs on. (The per-row kernel functions are internal as of 0.2.)

Resampling

When a sink is configured with a resampler (instead of the default NoopResampler), pixon plans the resample once and fuses it into the convert walk — the source is binned/filtered and converted to the chosen outputs in one pass, never materializing an intermediate full-resolution frame. Resampling requires the alloc (or std) tier.

Pick a resampler by the convention you calibrate against:

resampler convention notes
NoopResampler — identity (the default)
AreaResampler cv2.INTER_AREA exact integer box-coverage spans, fractional ratios; downscale-only
FilteredResampler<K> PIL Image.resize separable kernel K; the u8 path is byte-exact to Pillow
Bicublin swscale BICUBLIN cubic luma + bilinear chroma

Filter kernels (K: FilterKernel): Triangle (PIL BILINEAR), CatmullRom (PIL BICUBIC), Lanczos3 (PIL LANCZOS), Lanczos4, Mitchell, CubicBSpline, Gaussian, BlackmanSinc, Spline16 / Spline36 / Spline64, OpenCvCubic (cv2.INTER_CUBIC), and SwscaleBicubic.

The averaging domain controls where in the pipeline the binning happens, trading speed for colorimetric correctness:

  • AveragingDomain::Encoded (default) — average in the encoded (gamma) space, the cv2/swscale convention; fastest.
  • AveragingDomain::Linear — decode to linear light, average, re-encode (gamma-correct resize). The transfer function is caller-configurable (TransferFunction::{Srgb, Bt1886, Gamma22, …}, defaulting per the source's color matrix), and LinearMode::SceneReferred averages an unclamped-f32 decode to preserve out-of-gamut excursions.

Installation

[dependencies]
pixon = "0.8"

Renamed from colconv. Everything through colconv 0.2.1 was published under that name, which is now frozen. pixon starts its own version history at 0.1.0 — it is a new name on crates.io, so the number carries no maturity claim: pixon 0.1.0 is colconv 0.2.1's code, with an unchanged API. Migrating is a manifest edit plus s/colconv/pixon/ over your imports.

Examples

Runnable, self-contained walkthroughs of every functional area live in examples/:

cargo run --example quickstart        # the Tier-0 golden call
cargo run --example formats_tour      # one call, every source family
cargo run --example multi_output      # rgb + rgba + luma + hsv in one pass
cargo run --example colorimetry       # matrices, ranges, ST 428-1
cargo run --example chroma_siting     # every ChromaLocation honored
cargo run --example resize_area       # fused INTER_AREA downscale
cargo run --example resize_filtered   # filter kernels, upscale included
cargo run --example tier1_resampling  # linear-light averaging + BICUBLIN
cargo run --example tier1_sinker      # manual MixedSinker + walker
cargo run --example bayer_demosaic    # raw pipeline: WB + CCM + demosaic

Feature flags

Capability tiers (additive):

flag role
none (--no-default-features) no_std + no_alloc
alloc no_std + alloc (pulls libm for the scalar path)
std (default) std

Format-family gates (opt out of kernels you don't ship):

flag enables
frame (default) umbrella — every family below
yuv-planar YUV planar 4:0:0 / 4:2:0 / 4:2:2 / 4:4:4 (8/10/12/14/16-bit)
yuv-semi-planar NV-family (NV12 / NV16 / NV21 / NV24 / NV42)
yuva YUVA 4:2:0 / 4:2:2 / 4:4:4 (auto-enables yuv-planar)
yuv-packed packed YUV (UYVY / YUYV / 4:1:1)
yuv-444-packed packed YUV 4:4:4 (AYUV64 / VUYA / Y410 / Y412 / XV30 / XV36)
y2xx Y2-family packed 4:2:2 (Y210 / Y212 / Y216 / V210)
v210 V210 packed 4:2:2 (10-bit, 6-pixels-per-block)
rgb packed RGB 8/16-bit (RGB / RGBA / BGR / BGRA / RGB48 / RGBA64)
rgb-float packed RGB f16 / f32
rgb-legacy legacy packed RGB (RGB565 / RGB555 / RGB444 + BGR variants)
gbr planar GBR / GBRA (8-bit, high-bit, f16, f32)
gray gray Y8 / Y16 / YF16 / YF32 / YA8 / YA16
bayer Bayer 8/16-bit (RGGB / GRBG / GBRG / BGGR)
xyz XYZ 12-bit (DCDM / DCP)
mono 1-bit mono + PAL8 palette

Each family gate forwards to the matching mediaframe/<family> so the source-format markers and Frame types compile in lockstep.

License

pixon is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

See LICENSE for the full text, or https://www.gnu.org/licenses/gpl-3.0.html.

Copyright (C) 2026 FinDIT Studio authors.