Crate fast_ssim2 

fast-ssim2

Fast SIMD-accelerated implementation of SSIMULACRA2, a perceptual image quality metric.

Quick Start

The simplest way to compare two images:

use fast_ssim2::compute_ssimulacra2;
use imgref::ImgVec;

// Load your images (8-bit sRGB)
let source: ImgVec<[u8; 3]> = load_image("source.png");
let distorted: ImgVec<[u8; 3]> = load_image("distorted.png");

let score = compute_ssimulacra2(source.as_ref(), distorted.as_ref())?;
// score: 100 = identical, 90+ = imperceptible, <50 = significant degradation

Score Interpretation

Score	Quality
100	Identical (no difference)
90+	Imperceptible difference
70-90	Minor, subtle difference
50-70	Noticeable difference
<50	Significant degradation

Supported Input Formats

With imgref feature (recommended for most users)

Type	Color Space	Notes
ImgRef<[u8; 3]>	sRGB	Standard 8-bit RGB images
ImgRef<[u16; 3]>	sRGB	16-bit RGB (HDR workflows)
ImgRef<[f32; 3]>	Linear RGB	Already linearized data
ImgRef<u8>	sRGB grayscale	Expanded to R=G=B
ImgRef<f32>	Linear grayscale	Expanded to R=G=B

Convention: Integer types assume sRGB gamma encoding. Float types assume linear RGB.

Without features (using yuvxyb types)

use fast_ssim2::compute_ssimulacra2;
use yuvxyb::{Rgb, TransferCharacteristic, ColorPrimaries};
use std::num::NonZeroUsize;

let data: Vec<[f32; 3]> = vec![[0.5, 0.5, 0.5]; 64 * 64];
let w = NonZeroUsize::new(64).unwrap();
let h = NonZeroUsize::new(64).unwrap();
let source = Rgb::new(data.clone(), w, h,
    TransferCharacteristic::SRGB, ColorPrimaries::BT709)?;
let distorted = Rgb::new(data, w, h,
    TransferCharacteristic::SRGB, ColorPrimaries::BT709)?;

let score = compute_ssimulacra2(source, distorted)?;
// compute_ssimulacra2 accepts yuvxyb::Rgb, yuvxyb::LinearRgb, and more

Batch Comparisons (2x Faster)

When comparing multiple images against the same reference (e.g., evaluating different compression levels), precompute the reference data once:

use fast_ssim2::Ssimulacra2Reference;
use yuvxyb::{Rgb, TransferCharacteristic, ColorPrimaries};
use std::num::NonZeroUsize;

// Create test data
let data: Vec<[f32; 3]> = vec![[0.5, 0.5, 0.5]; 64 * 64];
let w = NonZeroUsize::new(64).unwrap();
let h = NonZeroUsize::new(64).unwrap();
let source = Rgb::new(data.clone(), w, h,
    TransferCharacteristic::SRGB, ColorPrimaries::BT709)?;

// Precompute reference data (~50% of the work)
let reference = Ssimulacra2Reference::new(source)?;

// Compare multiple distorted versions efficiently
let distorted = Rgb::new(data, w, h,
    TransferCharacteristic::SRGB, ColorPrimaries::BT709)?;
let score = reference.compare(distorted)?;

Custom Input Types

Implement ToLinearRgb to support your own image types:

use fast_ssim2::{ToLinearRgb, LinearRgbImage, srgb_u8_to_linear};

struct MyImage {
    pixels: Vec<[u8; 3]>,
    width: usize,
    height: usize,
}

impl ToLinearRgb for MyImage {
    fn to_linear_rgb(&self) -> LinearRgbImage {
        let data: Vec<[f32; 3]> = self.pixels.iter()
            .map(|[r, g, b]| [
                srgb_u8_to_linear(*r),
                srgb_u8_to_linear(*g),
                srgb_u8_to_linear(*b),
            ])
            .collect();
        LinearRgbImage::new(data, self.width, self.height)
    }
}

Helper functions for sRGB conversion:

• srgb_u8_to_linear - 8-bit lookup table (fastest)
• srgb_u16_to_linear - 16-bit conversion
• srgb_to_linear - General f32 conversion

SIMD Configuration

SIMD is enabled by default via the archmage crate, providing cross-platform acceleration on x86_64 (AVX2, AVX-512), AArch64 (NEON), and WASM (SIMD128).

Backend	Speed	Platforms
Scalar	1.0× (baseline)	All
Simd (default)	2-3×	x86_64, AArch64, WASM

To explicitly select a backend:

use fast_ssim2::{compute_ssimulacra2_with_config, Ssimulacra2Config};

let score = compute_ssimulacra2_with_config(
    source,
    distorted,
    Ssimulacra2Config::scalar(), // or ::simd()
)?;

Features

Feature	Default	Description
imgref		Support for imgref image types
rayon		Parallel computation

Requirements

• Minimum image size: 8×8 pixels
• MSRV: 1.89.0

Structs

Blur

Structure handling image blur with selectable implementation.

LinearRgbImage

Internal linear RGB image representation.

Ssimulacra2Config

Configuration for SSIMULACRA2 computation.

Ssimulacra2Reference

Precomputed SSIMULACRA2 reference data for fast repeated comparisons.

Enums

SimdImpl

SIMD implementation backend for all operations (blur, XYB conversion, SSIM computation).

Ssimulacra2Error

Errors which can occur when attempting to calculate a SSIMULACRA2 score from two input images.

Traits

ToLinearRgb

Trait for converting image types to linear RGB.

Functions

compute_frame_ssimulacra2Deprecated

Computes the SSIMULACRA2 score with default configuration (safe SIMD).

compute_frame_ssimulacra2_with_configDeprecated

Computes the SSIMULACRA2 score with custom implementation configuration.

compute_ssimulacra2

Computes the SSIMULACRA2 score from any input type implementing ToLinearRgb.

compute_ssimulacra2_with_config

Computes the SSIMULACRA2 score with custom configuration from ToLinearRgb inputs.

srgb_to_linear

Convert sRGB (gamma-encoded) value to linear.

srgb_u8_to_linear

Convert 8-bit sRGB value to linear f32.

srgb_u16_to_linear

Convert 16-bit sRGB value to linear f32.