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
Convertbuilder 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
AVPixelFormatspace (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 +SourceFormattraits the kernels are generic over. - Colorimetry-honest — fourteen H.273
ColorMatrixvalues 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.ChromaLocationdrives 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 foru8), and swscaleBICUBLINare all available, with optional gamma-correct (linear-light) and scene-referred averaging. See Resampling.
Quick start
use ;
use Yuv420pFrame;
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), andLinearMode::SceneReferredaverages an unclamped-f32decode to preserve out-of-gamut excursions.
Installation
[]
= "0.8"
Renamed from
colconv. Everything throughcolconv0.2.1 was published under that name, which is now frozen.pixonstarts its own version history at 0.1.0 — it is a new name on crates.io, so the number carries no maturity claim:pixon0.1.0 iscolconv0.2.1's code, with an unchanged API. Migrating is a manifest edit pluss/colconv/pixon/over your imports.
Examples
Runnable, self-contained walkthroughs of every functional area live in
examples/:
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.