butteraugli-oxide

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

What is Butteraugli?

Butteraugli is a psychovisual image quality metric that estimates the perceived difference between two images. Unlike simple metrics like PSNR or MSE, butteraugli models human vision to produce scores that correlate well with subjective quality assessments.

The metric is based on:

• Opsin dynamics: Models photosensitive chemical responses in the retina
• XYB color space: A hybrid opponent/trichromatic color representation
• Visual masking: How image features hide or reveal differences
• Multi-scale analysis: Examines differences at multiple frequency bands

Quality Thresholds

Usage

Add to your Cargo.toml:

[dependencies]
butteraugli-oxide = "0.1"

Input Formats

Two input APIs are provided:

Both APIs require:

• Channel order: RGB (red, green, blue)
• Layout: Row-major, interleaved (see below)
• Minimum size: 8×8 pixels

The sRGB function internally applies gamma decoding before comparison.

Pixel Layout

Data is row-major, interleaved RGB:

Index:  0   1   2   3   4   5   6   7   8  ...
Data:  [R0, G0, B0, R1, G1, B1, R2, G2, B2, ...]
        └─pixel 0─┘  └─pixel 1─┘  └─pixel 2─┘

For a 3×2 image:

Row 0: [R00, G00, B00, R01, G01, B01, R02, G02, B02]
Row 1: [R10, G10, B10, R11, G11, B11, R12, G12, B12]

Memory: [R00, G00, B00, R01, G01, B01, R02, G02, B02, R10, G10, B10, ...]
         └────────────── row 0 ──────────────────┘  └──── row 1 ────...

To access pixel at (x, y): index = (y * width + x) * 3

Basic Example

use butteraugli_oxide::{compute_butteraugli, ButteraugliParams};

// Load two RGB images (u8, 3 bytes per pixel, row-major order)
let original: &[u8] = &[/* original image RGB data */];
let compressed: &[u8] = &[/* compressed image RGB data */];
let width = 640;
let height = 480;

// Compare images
let params = ButteraugliParams::default();
let result = compute_butteraugli(original, compressed, width, height, &params)
    .expect("valid image data");

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

if result.score < 1.0 {
    println!("Images appear identical!");
} else if result.score < 2.0 {
    println!("Minor visible differences");
} else {
    println!("Significant visible differences");
}

// Optional: access per-pixel difference map
if let Some(diffmap) = result.diffmap {
    let max_diff = (0..height)
        .flat_map(|y| (0..width).map(move |x| diffmap.get(x, y)))
        .fold(0.0f32, f32::max);
    println!("Maximum local difference: {:.4}", max_diff);
}

Linear RGB Example (HDR/16-bit)

use butteraugli_oxide::{compute_butteraugli_linear, ButteraugliParams, srgb_to_linear};

// Convert 16-bit image to linear f32
let original_16bit: &[u16] = &[/* 16-bit RGB data */];
let original_linear: Vec<f32> = original_16bit.iter()
    .map(|&v| v as f32 / 65535.0)  // Assuming already linear
    .collect();

// Or convert 8-bit sRGB manually
let original_srgb: &[u8] = &[/* sRGB data */];
let original_linear: Vec<f32> = original_srgb.iter()
    .map(|&v| srgb_to_linear(v))
    .collect();

let result = compute_butteraugli_linear(&original_linear, &compressed_linear, width, height, &ButteraugliParams::default())
    .expect("valid image data");

Custom Parameters

use butteraugli_oxide::ButteraugliParams;

let params = ButteraugliParams::new()
    .with_hf_asymmetry(1.5)      // Penalize new artifacts more than blurring
    .with_xmul(1.0)              // X channel multiplier (1.0 = neutral)
    .with_intensity_target(250.0); // HDR display brightness in nits

Helper Functions

use butteraugli_oxide::{score_to_quality, butteraugli_fuzzy_class};

// Convert score to 0-100 quality percentage
let quality = score_to_quality(1.5);  // ~62.5%

// Get fuzzy classification (2.0 = perfect, 1.0 = ok, 0.0 = bad)
let class = butteraugli_fuzzy_class(1.5);  // ~1.25

Features

• simd (default): Enable SIMD optimizations via the wide crate

Performance

This implementation uses SIMD operations where available for gaussian blur and other compute-intensive operations. Performance is comparable to the C++ implementation for typical image sizes.

Accuracy

The implementation includes 195 synthetic test cases validated against the C++ libjxl butteraugli. Reference values are captured from C++ and hard-coded for regression testing without requiring FFI bindings at runtime.

Comparison with Other Crates

API Comparison with C++ libjxl

XYB Color Space Note

Butteraugli's internal XYB is NOT the same as jpegli's XYB.

This crate does NOT accept XYB input directly because there are multiple incompatible XYB definitions. Always provide RGB input and let butteraugli perform its own internal conversion.

References

• Original butteraugli repository
• JPEG XL (libjxl) - Contains the reference implementation
• Butteraugli paper

AI-Generated Code Notice

This crate was developed with significant assistance from Claude (Anthropic). While the code has been tested against the C++ libjxl butteraugli implementation and passes 195 synthetic test cases with exact numerical parity, not all code has been manually reviewed or human-audited.

Before using in production:

• Review critical code paths for your use case
• Run your own validation against expected outputs
• Consider the test suite coverage for your specific requirements

License

BSD-3-Clause, same as the original libjxl implementation.