Pure Rust implementation of Google's butteraugli perceptual image quality metric from libjxl.

Butteraugli estimates the perceived difference between two images using a model of human vision. Unlike simple pixel-wise metrics (PSNR, MSE), butteraugli accounts for:

• Opsin dynamics: Photosensitive chemical responses in the retina
• XYB color space: Hybrid opponent/trichromatic representation
• Visual masking: How image features hide or reveal differences
• Multi-scale analysis: UHF, HF, MF, LF frequency bands

cargo install butteraugli-cli

# Compare two images
butteraugli original.png compressed.jpg
# Output: Butteraugli score: 1.2345

# Quality rating
butteraugli -q original.png compressed.jpg

# JSON output
butteraugli --json original.png compressed.jpg

# Save difference heatmap
butteraugli --diffmap diff.png original.png compressed.jpg

# Just the score
butteraugli --quiet original.png compressed.jpg

butteraugli --intensity-target 250 hdr_orig.png hdr_comp.png  # HDR (250 nits)
butteraugli --hf-asymmetry 1.5 original.png compressed.jpg    # Penalize ringing > blur
butteraugli --help

[dependencies]
butteraugli = "0.9"

Both APIs support stride (padding) and require minimum 8x8 images.

use butteraugli::{butteraugli, ButteraugliParams, Img, RGB8};

let original: Vec<RGB8> = load_image();
let compressed: Vec<RGB8> = load_compressed();

let img1 = Img::new(original, width, height);
let img2 = Img::new(compressed, width, height);

let result = butteraugli(img1.as_ref(), img2.as_ref(), &ButteraugliParams::default())?;

println!("Score: {:.4}", result.score);

let params = ButteraugliParams::default().with_compute_diffmap(true);
let result = butteraugli(img1.as_ref(), img2.as_ref(), &params)?;

if let Some(diffmap) = result.diffmap {
    let max_diff = diffmap.buf().iter().fold(0.0f32, |a, &b| a.max(b));
    println!("Maximum local difference: {:.4}", max_diff);
}

result.score is the max-norm distance — the historical butteraugli score used for <1.0 = good, >2.0 = bad thresholds. result.pnorm_3 is the libjxl 3-norm aggregation reported by butteraugli_main --pnorm and used in the Cloudinary CID22 paper — useful for codec rate-distortion sweeps where averaging tail and bulk distortion is more informative than max alone. Both are produced in a single fused reduction pass and available regardless of whether compute_diffmap was enabled (no extra allocation).

println!("max-norm:  {:.4}", result.score);     // or result.max_norm()
println!("3-norm:    {:.4}", result.pnorm_3);
println!("p=4 norm:  {:?}", result.pnorm(4.0)); // requires compute_diffmap=true

The CLI exposes the 3-norm via butteraugli --pnorm; JSON output always includes a pnorm_3 field.

let params = ButteraugliParams::new()
    .with_hf_asymmetry(1.5)        // Penalize artifacts > blur
    .with_intensity_target(250.0)  // HDR display (nits)
    .with_compute_diffmap(true);

• internals: Expose internal modules for testing/benchmarking (unstable API)
• unsafe-performance: Unchecked indexing in hot loops (~6% fewer instructions, pre-validated ranges)

SIMD-accelerated via archmage with runtime dispatch:

No C dependencies. Safe Rust by default (unsafe-performance is opt-in).

Benchmarked on AMD Ryzen 9 7950X (Zen 4), sRGB-only PNGs (no ICC profiles), mozjpeg q100 vs q50, 5 iterations per image:

Multi-threaded gains are larger because Rust parallelizes blur and Malta filter passes via rayon, while butteraugli_main shows no effective threading benefit on these image sizes.

Validated against libjxl's butteraugli_main on sRGB photographs (no ICC profiles or gAMA/cHRM chunks) across multiple sizes and JPEG quality levels:

All test pairs: < 0.001% relative difference vs libjxl butteraugli_main. Residual differences are FMA rounding noise from hardware fused multiply-add instructions.

ICC profiles: This crate assumes sRGB input. libjxl's butteraugli_main applies ICC profile and gAMA/cHRM transforms via its CMS before scoring. Images with non-sRGB ICC profiles (Adobe RGB, Display P3, ProPhoto RGB) will produce different scores between the two implementations. Strip ICC profiles or convert to sRGB before comparing.

Butteraugli's internal "XYB" is not the same color space as JPEG XL / jpegli XYB. Key differences:

• Matrix coefficients: Different opsin absorbance weights (e.g., row 2 is [0.02, 0.02, 0.205] vs jpegli's [0.243, 0.205, 0.552])
• Nonlinearity: Log-based Gamma function (FastLog2f), not cube root
• Dynamic adaptation: Blurs the input, computes per-pixel sensitivity ratios, and modulates the opsin-transformed signal — jpegli XYB has no equivalent step
• Biases: Large additive biases (~1.76, ~1.76, ~12.23) vs jpegli's small bias (~0.0038)

Always provide RGB input (sRGB u8 or linear f32); butteraugli handles the conversion internally. Pre-converted XYB cannot be used because the dynamic sensitivity adaptation requires raw linear RGB.

• JPEG XL reference implementation (libjxl) — canonical source for butteraugli
• Butteraugli paper

Note: The archived google/butteraugli repository is a standalone fork with little in common with the current butteraugli in libjxl. It should not be used as a reference. This crate ports from libjxl's lib/extras/butteraugli.cc.

cargo fmt --all -- --check
cargo clippy --lib --tests -- -D warnings
cargo test --lib
cargo test --test conformance

Developed with Claude (Anthropic). Validated against C++ libjxl butteraugli_main with < 0.0003% difference on real photographs.

BSD-3-Clause (same as libjxl)