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, Rgb, TransferCharacteristic, ColorPrimaries};

let data: Vec<[f32; 3]> = vec![[0.5, 0.5, 0.5]; 64 * 64];
let source = Rgb::new(data.clone(), 64, 64,
    TransferCharacteristic::SRGB, ColorPrimaries::BT709)?;
let distorted = Rgb::new(data, 64, 64,
    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, Rgb, TransferCharacteristic, ColorPrimaries};

// Create test data
let data: Vec<[f32; 3]> = vec![[0.5, 0.5, 0.5]; 64 * 64];
let source = Rgb::new(data.clone(), 64, 64,
    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, 64, 64,
    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.

Frame

Represents a raw video frame

LinearRgb

Contains an RGB image in a linearized color space.

LinearRgbImage

Internal linear RGB image representation.

Plane

One data plane of a frame.

Rgb

Contains an RGB image.

Ssimulacra2Config

Configuration for SSIMULACRA2 computation.

Ssimulacra2Reference

Precomputed SSIMULACRA2 reference data for fast repeated comparisons.

Yuv

Contains a YCbCr image in a color space defined by YuvConfig.

YuvConfig

Contains the configuration data for a YCbCr image.

Enums

ColorPrimaries

Indicates the chromaticity coordinates of the source colour primaries as specified in Table 2 in terms of the CIE 1931 definition of x and y as specified by ISO 11664-1.

MatrixCoefficients

Describes the matrix coefficients used in deriving luma and chroma signals from the green, blue and red or X, Y and Z primaries.

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.

TransferCharacteristic

Either indicates the reference opto-electronic transfer characteristic function of the source picture as a function of a source input linear optical intensity input Lc with a nominal real-valued range of 0 to 1 or indicates the inverse of the reference electro-optical transfer characteristic function as a function of an output linear optical intensity Lo with a nominal real-valued range of 0 to 1.

Traits

Pixel

A type that can be used as a pixel type.

ToLinearRgb

Trait for converting image types to linear RGB.

Functions

compute_frame_ssimulacra2

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

compute_frame_ssimulacra2_with_config

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.