zensim [](https://github.com/imazen/zensim/actions/workflows/ci.yml) [](https://crates.io/crates/zensim) [](https://lib.rs/crates/zensim) [](https://docs.rs/zensim) [](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) [](#license)

A perceptual image quality score for codec quality targeting: users choose one score, and encoders choose the settings to reach it.

Built on the same psychovisual foundations as SSIMULACRA2 and butteraugli — multi-scale SSIM, edge artifacts, detail loss, and high-frequency features in XYB color space — but with trained weights, fused SIMD kernels, and multi-threaded computation.

Current checkout (2026-09-07): the user-facing control is one target score. codec_target() returns B; D is an explicit fast profile. Negative scores are valid. The benchmark tables below are historical measurements, not a fresh qualification of today's profiles. See the current integration guide for bake identities, actual consumer behavior and the remaining dial requirements.

Interactive chart exploration: https://imazen.github.io/zensim/ — scatter zensim / fast-ssim2 / butteraugli against human MOS across CID22 / KADID / TID / AIC corpora, filter by codec + version, with per-band SROCC tables and step-5 (20-bin) breakdowns.

Historical speed measurements

AMD Ryzen 9 7950X 16C/32T (WSL2), synthetic gradient images, no I/O, pre-allocated buffers. zensim and ssimulacra2-rs use rayon (all cores); C++ libjxl, fast-ssim2, and butteraugli-rs are single-threaded. Enabling rayon for fast-ssim2 and butteraugli-rs made them slower at small sizes due to thread-pool overhead, so they're benchmarked single-threaded. Median of 100 samples via criterion.

SSIMULACRA2 implementations

Butteraugli implementations (single-threaded)

Single-threaded zensim is 4x faster than C++ libjxl SSIMULACRA2. Multi-threaded at 4K: 18x.

Reproduce: cargo bench -p zensim-bench --bench bench_compare (C++ libjxl FFI requires a local libjxl build; set LIBJXL_DIR or let the build script auto-clone it)

Correlation with human perception

Quality targeting requires both perceptual agreement and a useful score range. The tables below preserve the older v0.3/A evaluation; B's dated methodology is in its July record. They do not qualify the current profiles against September's stricter dial requirements. CID22 has also been consulted repeatedly during model selection; it is not an untouched final test. Current split policy and exceptions are in DATA_SPLITS.

# CID22 — expects CID22_validation_set.csv + original/ and compressed/ dirs
cargo run --release -p zensim-validate -- --dataset ./datasets/cid22 --format cid22

# TID2013 — expects mos_with_names.txt + reference_images/ and distorted_images/
cargo run --release -p zensim-validate -- --dataset ./datasets/tid2013 --format tid2013

# KADID-10k — expects dmos.csv + images/
cargo run --release -p zensim-validate -- --dataset ./datasets/kadid10k --format kadid10k

Quick start

[dependencies]
zensim = "0.3"

use zensim::{Zensim, ZensimProfile, RgbSlice};

// Use the common codec-target profile (currently B for SDR):
let z = Zensim::new(ZensimProfile::codec_target());
// Reproducible experiments also pin the dependency, bake and extractor
// revision; selecting a profile name alone does not freeze its bytes.
// Use the absolute-luminance API and BHdr route for HDR content.
// `src_pixels` / `dst_pixels` are `&[[u8; 3]]` — interleaved, sRGB-encoded
// (gamma, NOT linear) 8-bit RGB. `width`/`height` are `usize`. See "Input
// format" below: getting sRGB-vs-linear wrong silently corrupts every score.
let source = RgbSlice::new(&src_pixels, width, height);
let distorted = RgbSlice::new(&dst_pixels, width, height);
// `compute` returns `Result<ZensimResult, zensim::ZensimError>` — the `?`
// propagates a dimension-mismatch / too-small / too-large error.
let result = z.compute(&source, &distorted)?;
println!("score: {:.2}", result.score()); // 100 = identical, higher = better

Also accepts RgbaSlice (composited over a noise background), imgref::ImgRef (with stride), ZenpixelsSource (with zenpixels feature), and StridedBytes for BGRA, 16-bit, linear float, and wide gamut (Display P3, BT.2020) inputs. See docs.rs for the full ImageSource trait.

Input format (read this — wrong input silently corrupts the score)

The score is only meaningful if the pixels you pass match the contract zensim assumes. There is no format auto-detection for the RgbSlice fast path: if you hand it linear bytes where it expects sRGB, or planar bytes where it expects interleaved, it computes a perfectly valid-looking but wrong score — no error is raised. The contract:

• Color encoding: sRGB-encoded (gamma), NOT linear. RgbSlice / RgbaSlice / the Srgb8* and Srgb16Rgba StridedBytes formats all expect display-encoded sRGB values — the bytes a PNG/JPEG decoder gives you. zensim linearizes internally before the XYB conversion. If your data is already linear light, do not feed it as sRGB; use StridedBytes with PixelFormat::LinearF32Rgba (linear 32-bit float RGBA) instead. (Display P3 reuses the sRGB transfer function, so Srgb8* formats linearize it correctly; SDR BT.2020 technically wants BT.1886 — for exact results linearize externally and use LinearF32Rgba. Set primaries via StridedBytes::with_color_primaries.)
• Channel order: interleaved, not planar. RgbSlice takes &[[u8; 3]] laid out R,G,B, R,G,B, … (one [u8; 3] per pixel), RgbaSlice takes &[[u8; 4]] as R,G,B,A, …. Planar input (all R, then all G, then all B) is not accepted by these types — you must interleave it first, or describe it some other way. The [[u8; 3]] / [[u8; 4]] element type also pins it to exactly 3 / 4 bytes per pixel, tightly packed (no per-row padding) — for row padding use StridedBytes (below).
• Dimensions: width and height are usize (not u32). Both RgbSlice::new(data, width, height) and the underlying ImageSource::{width,height} use usize.
• Both images must have identical dimensions, and each must be non-zero. compute returns ZensimError::DimensionMismatch if they differ, ZensimError::ImageTooSmall if either dimension is 0. (Since 0.3.0, sub-64px images down to 1×1 are reflect-padded internally and score normally — only empty inputs are rejected.)

The infallible constructors (RgbSlice::new, RgbaSlice::new, StridedBytes::new) panic if data.len() is too short for width × height (or the stride is invalid). For untrusted sizes use the try_* variants — RgbSlice::try_new(data, width, height) -> Result<RgbSlice, ZensimError> etc. — which return ZensimError::InvalidDataLength / ZensimError::InvalidStride / ZensimError::ImageTooLarge instead of panicking.

Return type and errors

pub fn compute(
    &self,
    source: &impl ImageSource,
    distorted: &impl ImageSource,
) -> Result<ZensimResult, zensim::ZensimError>

ZensimError is a #[non_exhaustive] enum (so match it with a _ arm) — the variants compute can return are DimensionMismatch, ImageTooSmall, and ImageTooLarge (dimensions exceed the configured max_pixels cap — 120 MP by default since #49; tighten it with Zensim::with_max_pixels, or pass with_max_pixels(usize::MAX) to opt out for trusted input — or width × height overflows usize on 32-bit / wasm32). HDR-flagged sources (ImageSource::is_hdr returns true) are refused with HdrInputRequiresPuPath — score HDR via the PU21 front-end (Zensim::compute_pu_linear, fed absolute-luminance linear RGB in cd/m²) instead. On success, ZensimResult::score() is the signed similarity score (identity is 100 and severe damage can score below zero); raw_distance(), approx_ssim2(), approx_dssim(), and approx_butteraugli() are also available (see "What the score means").

Strided / padded rows

When rows are not tightly packed (SIMD-aligned padding, a sub-region crop of a larger buffer, decoder output with row guards), use StridedBytes, where stride is the byte distance between the start of consecutive rows:

use zensim::{StridedBytes, PixelFormat};

// e.g. 8-bit RGB where each row is padded to `row_stride` bytes (≥ width*3):
let src = StridedBytes::new(&bytes, width, height, row_stride, PixelFormat::Srgb8Rgb);
// `try_new(..) -> Result<_, ZensimError>` returns InvalidStride / InvalidDataLength
// instead of panicking. `with_alpha_mode(.., AlphaMode)` / `with_color_primaries(..)`
// set alpha handling and gamut; default alpha mode is `AlphaMode::Unknown`.
let result = z.compute(&src, &dst)?;

With the imgref feature (on by default), imgref::ImgRef<'_, rgb::Rgb<u8>> and ImgRef<'_, rgb::Rgba<u8>> implement ImageSource directly and honor their pixel stride — pass an ImgRef straight to compute. (The element type must be rgb::Rgb<u8> / rgb::Rgba<u8>; the ImgRef stride is in pixels.)

Cancellation

A single compute / compute_with_ref call is not interruptible mid-computation — the zensim metric library exposes no Stop-token parameter, and a single comparison is typically tens of milliseconds (~22 ms at 1080p). Cancellation is at the granularity of your loop: when comparing one reference against many distorted variants (see "Batch comparison"), check your own cancellation flag between compute_with_ref calls. The enough cooperative-cancellation crate is used by the zensim-target codec-targeting CLI (to bound its binary-search loop) and zensim-regress, not by the core metric API.

zenpixels integration

With the zenpixels feature, pass any PixelSlice or PixelBuffer directly:

[dependencies]
zensim = { version = "0.3", features = ["zenpixels"] }

use zensim::{Zensim, ZensimProfile, ZenpixelsSource};

let source = ZenpixelsSource::try_from_slice(&pixel_slice)?;
let distorted = ZenpixelsSource::try_from_slice(&other_slice)?;
let result = Zensim::new(ZensimProfile::codec_target()).compute(&source, &distorted)?;

Format mapping is automatic: RGBX/BGRX becomes opaque, premultiplied alpha is un-premultiplied, color primaries are forwarded. HDR (PQ, HLG) and grayscale are rejected with UnsupportedFormat.

Target-score CLI (zensim-target)

The zensim-target standalone workspace is the runtime side of the "user-facing quality dial" goal. Given an input image and a target zensim score, it picks the codec quality knob via binary search:

cargo run --release --manifest-path zensim-target/Cargo.toml --bin zensim-target -- \
    input.png --target 70 --codec zenjpeg --profile codec-target --output out.jpg

The CLI and library default to codec-target (currently B). Use --profile tuner-v4 to reproduce the earlier CLI default. JPEG, WebP, AVIF and PNG are enabled by default; JXL encode/decode requires --features zenjxl before --. The historical May 18 demo matrix at benchmarks/zensim_target_demo_2026-05-18.md: reported 33 / 36 cells within ±1.5 score units, median 5 iterations. Those are dated demo results; inspect today's returned converged and achieved score rather than assuming the target was reached.

zensim-target is AGPL-3.0-only because it links the AGPL zen codec crates; the core zensim library stays MIT/Apache.

What the score means

100 = identical; higher = more similar. Negative values represent severe degradation and must remain visible. Byte-identical inputs short-circuit to 100; that does not prove a model's near-identity behavior. A monotone output spline preserves raw ordering and cannot repair a raw codec-quality inversion. The historical JND-at-60 convention below is not a universal perceptual guarantee for current profiles; see the score contract.

Each ZensimResult also provides approximate translations to other metrics:

The mapping module has bidirectional interpolation tables — including JPEG quality. These are median values from 344k synthetic pairs across 6 codecs (source: zensim/src/mapping.rs):

JPEG quality mapping accuracy is ±7 quality units MAE — individual images vary widely.

Regression testing

zensim-regress tracks pixel output across platforms and dependency updates. Hash-based checksums for fast exact matches; perceptual comparison with forensic evidence when hashes diverge. Amplified diff images, error classification, architecture-specific tolerances, CI manifests, and HTML reports.

use zensim_regress::checksums::{ChecksumManager, CheckResult};

let mgr = ChecksumManager::new("tests/checksums".as_ref());
let result = mgr.check_pixels("resize", "bicubic", "200x200",
    &pixels, width, height, None).unwrap();
assert!(result.passed(), "{result}");

Run with UPDATE_CHECKSUMS=1 to create baselines. See the zensim-regress guide for the full workflow.

Batch comparison

Compare one reference against many distorted variants. Precomputing the reference skips redundant XYB conversion and pyramid construction — saves ~25% per comparison at 4K.

let precomputed = z.precompute_reference(&source)?;
for dst_pixels in &distorted_images {
    let dst = RgbSlice::new(dst_pixels, width, height);
    let result = z.compute_with_ref(&precomputed, &dst)?;
}

How it works

The extractor computes the features declared by the selected bake, scored by trained weights. The original 228-feature vocabulary included:

• SSIM (mean, L2, L4 pooling) — structural similarity in XYB, using ssimulacra2's modified formula (no luminance denominator)
• Edge artifacts (mean, L2, L4) — ringing, banding, blockiness
• Detail loss (mean, L2, L4) — blur, smoothing, texture destruction
• MSE in XYB color space
• High-frequency features — energy loss, magnitude loss, energy gain
• Peak features — per-feature max and L8-pooled (near-worst-case)

Computed in XYB (cube-root LMS) with O(1)-per-pixel box blur and fused AVX2/AVX-512 SIMD kernels via archmage. Safe scalar fallback on all platforms.

Profiles

Each ZensimProfile bundles weights and score-mapping parameters. A profile name is not a frozen model: pin the bake and extraction revision when reproducing scores. Current checkout mapping, checked September 7:

Exact filenames, hashes, serving limitations and evaluation records are in the integration guide.

ZensimProfile::codec_target() and latest_preview() both return B — the canonical production codec-target the zen codecs dial against (the deprecated latest() also returns B). A (the prior default, the v47 MLP) is now #[deprecated] and lives behind the default-on deprecated-profiles feature — build with --no-default-features to drop it. For dynamically loaded candidates, zensim::BakeScorer borrows a parsed model and serves the complete head/spline/ensemble/corruption composition; evaluation uses that same surface. Static custom profiles remain available through ZensimProfile::Custom and ProfileParams::builder(). Results are deterministic for the same input on the same architecture; cross-architecture scores (AVX2 vs scalar vs AVX-512) may differ by small ULP.

D dial-era v2 (2026-09-05). D's bake changed from d_sdr_add156_dense_dial_2026-08-31.bin to d_sdr_add156_id100_negrich_dial_2026-09-05.bin. The forward pass is byte-identical (both strip to the same weight bytes), so rank and speed do not move — pooled SROCC is bit-identical on 11 of 14 canonical corpora and within a monotone remap's tie residue on the other three (kadid −1.3e-7, live +5.8e-7, tid +7.9e-6); CID22 is 0.863380 before and after. What changes is the dial: a perfect copy now reads 100.000 instead of 96.116, the dial-grid top moves 96.05 → 99.38 (p95 95.28 → 95.52) and the bottom −12.20 → −57.17 (p5 9.52 → 8.83), reach 108.25 → 156.55, and the deepest negative-tail probe row −100.0 → −213.1 — negative scores work further out, which is the product contract, not a regression. No grid cell out-scores identity, before or after (0 of 4,424). Stored zensim-d dial values predate this and must be re-read, not rescaled — the remap is a PCHIP spline, not an affine. Details + gates: benchmarks/d_ship_flip_2026-09-05.md.

ZensimProfile::PreviewV0_1 / PreviewV0_2 (the linear profiles that shipped in 0.2.7) are RETAINED as first-class, non-deprecated, selectable variants — the 0.3.0 line reverted their removal (commit 493c91cd) to preserve semver compatibility with 0.2.7; see the CHANGELOG [Unreleased] Restored entry. B is the current deterministic-linear default for SDR content.

The historical PreviewV0_4 / PreviewV0_5* SOTA-trail variants, A_Phone, and LinearBounded live in the zensim-experimental crate (not published), each rebuilt through the Custom extension point — e.g. Zensim::new(zensim_experimental::preview_v0_5_tuner_v4()). zenpredict (the MLP runtime) is MIT/Apache-2.0 — no AGPL transitive obligation on default builds.

Feature flags

Downloading evaluation datasets

To reproduce the SROCC numbers above, you need the three human-rated datasets. All are freely available for research use.

TID2013 — ponomarenko.info/tid2013.htm

25 reference images, 3,000 distorted (24 distortion types × 5 levels). Download the RAR archive, extract so you have mos_with_names.txt, reference_images/, and distorted_images/ in the same directory.

N. Ponomarenko et al., "Image database TID2013: Peculiarities, results and perspectives," Signal Processing: Image Communication, 2015. DOI: 10.1016/j.image.2014.10.009

KADID-10k — database.mmsp-kn.de/kadid-10k-database.html

81 reference images, 10,125 distorted (25 distortion types × 5 levels). Download from OSF. Expected structure: dmos.csv and images/ directory in the same parent.

H. Lin, V. Hosu, D. Saupe, "KADID-10k: A Large-scale Artificially Distorted IQA Database," QoMEX 2019. DOI: 10.1109/QoMEX.2019.8743252

CID22 — cloudinary.com/labs/cid22

49 validation reference images, 4,292 distorted (6 codecs, medium-to-lossless quality). Download the validation set. Expected structure: CID22_validation_set.csv, original/, and compressed/ in the same directory. CC BY-SA 4.0.

Jon Sneyers et al., "CID22: A Large-Scale Subjective Quality Assessment for Lossy Image Compression," 2024.

Workspace

MSRV

Rust 1.93.0 (2024 edition).

License

MIT OR Apache-2.0

AI-Generated Code Notice

Developed with Claude (Anthropic). Not all code manually reviewed. Review critical paths before production use.

Image tech I maintain

_{¹ pure-Rust, #![forbid(unsafe_code)] codecs, as of 2026}

General Rust awesomeness

zenbench · archmage · magetypes · enough · whereat · cargo-copter · zenutils

Open source · @imazen · @lilith · lib.rs/~lilith

Candidate models for research and serving

Use zensim::BakeScorer for a caller-owned zenpredict::Model. It reuses prediction state and returns the complete model score, including configured heads, splines, blends and corruption gates. compute scores SDR pixels and returns the score with its features; compute_hdr uses the explicit HDR encoding; score_features scores admitted cached rows. The user still controls one target score. Model metadata and disposition are model-author settings.

For rectangle steering, prepare_steering(&source, bin) binds SDR input; prepare_steering_hdr(&source, encoding, bin) binds native PQ, HLG or absolute linear HDR input. Both reuse the reference and retain basic/peak signals from the scoring extraction for subsequent map assembly. The HDR route preserves declared primaries and native precision; it currently refuses fractional sampling and unsupported feature families. These are input/implementation contracts, not evidence that an SDR-trained model is calibrated for HDR. The optional with_finite_moment_refinement(true) improves finite L2/L4/L8 removal estimates using binned base-image moments; it preserves scalar scores and additive density. It is disabled by default and adds preparation cost; see the measured runtime and qualification. See the accuracy evidence and updated preparation cost before enabling it. Map coverage and small TRAIN checks do not qualify native encoder improvements.

New candidates must be evaluated through this same Rust surface. See the workflow, feature identity and evaluation contract. The serve_custom_bake example loads models without leaked bytes or a static loader. Formula revision is validated; candidate pixel scoring refuses if the process's SSIM luminance form differs from the bake's revision (ZENSIM_FORMULA_REV).