zensim

Fast psychovisual image similarity metric. Combines ideas from SSIMULACRA2 and butteraugli — multi-scale SSIM + edge + high-frequency features in XYB color space, with trained weights and AVX2/AVX-512 SIMD throughout.

Quick start

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

let z = Zensim::new(ZensimProfile::latest());
let source = RgbSlice::new(&src_pixels, width, height);
let distorted = RgbSlice::new(&dst_pixels, width, height);
let result = z.compute(&source, &distorted)?;
println!("{}: {:.2}", result.profile(), result.score()); // higher = more similar

With imgref (default feature, supports stride)

use zensim::{Zensim, ZensimProfile};

let source: imgref::ImgRef<rgb::Rgb<u8>> = imgref::Img::new(&src_pixels, width, height);
let distorted: imgref::ImgRef<rgb::Rgb<u8>> = imgref::Img::new(&dst_pixels, width, height);
let z = Zensim::new(ZensimProfile::latest());
let result = z.compute(&source, &distorted)?;

imgref::ImgRef carries width, height, and stride in one type — no separate dimension arguments, and stride-padded buffers work automatically.

RGBA

RGBA images are composited over a checkerboard before comparison, so alpha differences produce visible distortion:

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

let z = Zensim::new(ZensimProfile::latest());
let source = RgbaSlice::new(&src_rgba, width, height);
let distorted = RgbaSlice::new(&dst_rgba, width, height);
let result = z.compute(&source, &distorted)?;

Batch comparison

When comparing one reference against many distorted variants, precompute the reference to skip redundant XYB conversion and pyramid construction:

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

let z = Zensim::new(ZensimProfile::latest());
let source = RgbSlice::new(&ref_pixels, width, height);
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)?;
    println!("score: {:.2}", result.score());
}

Saves ~25% per comparison at 4K, ~34% at 8K (break-even at 3-7 distorted images per reference).

Score semantics

100 = identical. Higher = more similar. Score mapping: 100 - 18 × d^0.7 where d is the per-scale weighted feature distance (compressive — more resolution at the high-quality end where it matters most).

Scores are calibrated from 0 to 100 on our training data (344k synthetic pairs, q5–q100 across 6 codecs). Extreme distortions can produce scores below 0; the mapping is uncalibrated outside the training range.

ZensimResult provides:

The mapping module provides bidirectional interpolation tables between zensim scores and SSIM2, DSSIM, butteraugli, libjpeg quality, and zenjpeg quality — calibrated on 344k synthetic pairs across 6 codecs.

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.

Profiles

Each ZensimProfile variant bundles weights and parameters that affect score output. A given profile produces approximately the same scores across versions, but profiles may be removed in future major versions as the algorithm evolves.

ZensimProfile::latest() returns the most recent profile.

Input requirements

• Color space: All inputs must be sRGB-encoded (gamma ~2.2). This is what you get from standard JPEG, PNG, and WebP decoders. If your pixels are linear-light (gamma 1.0), use PixelFormat::LinearF32Rgba via StridedBytes — zensim will apply the correct transfer function internally.
• Wide gamut: Display P3 and BT.2020 inputs are accepted via ColorPrimaries on StridedBytes — gamut-mapped to sRGB internally. Passing wide-gamut data as sRGB will produce incorrect scores (the metric sees the wrong colors).
• Pixel formats: RgbSlice (sRGB u8), RgbaSlice (sRGB u8 + alpha), imgref::ImgRef (sRGB u8, with stride), StridedBytes (any of: Srgb8Rgb, Srgb8Rgba, Srgb8Bgra, Srgb16Rgba, LinearF32Rgba), or implement the ImageSource trait directly.
• Alpha: RGBA inputs are composited over a checkerboard so alpha differences produce visible distortion. Supports Straight and Opaque alpha modes.
• Dimensions: Both images must be the same width × height, minimum 8×8.

Performance

Pure-computation benchmarks (no I/O), synthetic gradient images, AMD Ryzen 9 7950X 16C/32T (WSL2). All implementations receive pre-allocated pixel buffers.

SSIMULACRA2

Threading: zensim and ssimulacra2-rs use rayon (all cores). C++ libjxl and fast-ssim2 are single-threaded. zensim_st is zensim with .with_parallel(false) for a fair single-threaded comparison.

Even single-threaded, zensim is 3–4x faster than fast-ssim2 and 4x faster than C++ libjxl. Multi-threaded zensim is 12x faster than C++ libjxl at 4K.

Butteraugli

Both butteraugli implementations are single-threaded. butteraugli-rs is the imazen pure-Rust port of libjxl's butteraugli.

Benchmarks are in zensim-bench/ — run with cargo bench -p zensim-bench --bench bench_compare.

Design

• XYB color space — cube root LMS, same perceptual space as ssimulacra2/butteraugli
• Modified SSIM — ssimulacra2's variant: drops the luminance denominator, uses 1 - (mu1-mu2)² directly. Correct for perceptually-uniform values where dark/bright errors should weigh equally.
• 4-scale pyramid — 1×, 2×, 4×, 8× via box downscale (ssimulacra2 uses 6)
• O(1)-per-pixel box blur — 1-pass default with fused SIMD kernels
• 228 trained weights — optimized on 344k synthetic pairs across 6 codecs (mozjpeg, zenjpeg, jpegli, zenwebp, zenavif, zenjxl)
• AVX2/AVX-512 SIMD throughout via archmage, with safe scalar fallback

Feature layout (per channel per scale)

19 features per channel per scale, all scored:

Basic features (13):

Peak features (6):

Total: 4 scales × 3 channels × 19 features = 228 weights. FeatureView provides named access to all features.

Feature flags

Workspace crates

Visual diff images (zensim-regress)

zensim-regress generates amplified difference images and comparison montages for debugging visual regressions:

use zensim_regress::diff_image::*;

// Amplified diff: abs(expected - actual) * amplification_factor
let diff = generate_diff_image(&expected, &actual, 10);

// Side-by-side montage: expected | diff | actual (with border)
let montage = create_comparison_montage(&expected, &actual, 10, 2);

// Raw RGBA byte variants also available
let diff = generate_diff_image_raw(&exp_bytes, &act_bytes, w, h, 10);

Auto-save montages on checksum mismatch with .with_diff_output(), or display directly in sixel-capable terminals (foot, WezTerm, mintty). See zensim-regress/README.md for full API docs.

MSRV

Rust 1.89.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.