tjdistler-iqa

A fast image quality assessment library for Rust, ported from Tom Distler's C implementation. This library provides efficient implementations of common image quality metrics with performance that matches or exceeds the original C version.

日本語版

Features

• High Performance: Optimized implementations using parallel processing
• Multiple Metrics: SSIM, MS-SSIM, PSNR, and MSE
• Easy to Use: Simple API with sensible defaults
• Customizable: Builder pattern for advanced configuration
• Pure Rust: No external C dependencies for normal use
• Cross-platform: Works on Linux, macOS, and Windows

Performance

Benchmarks on Apple M4 Pro (256x256 images):

Installation

Add this to your Cargo.toml:

[dependencies]
tjdistler-iqa = "1.2.0"

Quick Start

use tjdistler_iqa::{ssim, psnr, mse, ms_ssim};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load your images (grayscale, 8-bit)
    let width = 256;
    let height = 256;
    let reference = vec![0u8; width * height];
    let distorted = vec![0u8; width * height];
    
    // Calculate metrics
    let ssim_value = ssim(&reference, &distorted, width, height)?;
    let psnr_value = psnr(&reference, &distorted, width, height)?;
    let mse_value = mse(&reference, &distorted, width, height)?;
    let ms_ssim_value = ms_ssim(&reference, &distorted, width, height)?;
    
    println!("SSIM: {}", ssim_value);
    println!("PSNR: {} dB", psnr_value);
    println!("MSE: {}", mse_value);
    println!("MS-SSIM: {}", ms_ssim_value);
    
    Ok(())
}

Advanced Usage

Custom SSIM Parameters

use tjdistler_iqa::{Ssim, ImageQualityAssessment};

let ssim = Ssim::builder()
    .k1(0.01)              // Default: 0.01
    .k2(0.03)              // Default: 0.03
    .gaussian(true)        // Default: true (Gaussian window)
    .scale(2)              // Default: auto-calculated
    .build();

let result = ssim.assess(&reference, &distorted, width, height)?;
println!("Custom SSIM: {}", result.value);

Custom MS-SSIM Parameters

use tjdistler_iqa::{MsSsim, ImageQualityAssessment};

let ms_ssim = MsSsim::builder()
    .gaussian(true)        // Use Gaussian window
    .scales(5)             // Number of scales
    .build();

let result = ms_ssim.assess(&reference, &distorted, width, height)?;
println!("Custom MS-SSIM: {}", result.value);

High-Performance Batch Processing (New in 1.2.0)

For scenarios where you need to compare multiple images against the same reference image, use the computation model API for significant performance improvements:

use tjdistler_iqa::{SsimModel, MsSsimModel};

// Create models with pre-computed reference image data
let ssim_model = SsimModel::new(&reference, width, height)?;
let ms_ssim_model = MsSsimModel::new(&reference, width, height)?;

// Compare multiple images efficiently
for distorted_image in &distorted_images {
    let ssim_score = ssim_model.compare(distorted_image)?;
    let ms_ssim_score = ms_ssim_model.compare(distorted_image)?;
    println!("SSIM: {}, MS-SSIM: {}", ssim_score, ms_ssim_score);
}

Performance improvements for batch processing:

• SSIM: ~1.5x faster for 10 comparisons
• MS-SSIM: ~5.6x faster for 5 comparisons

Metrics Description

SSIM (Structural Similarity Index)

Measures the structural similarity between two images. Values range from -1 to 1, where 1 indicates perfect similarity.

MS-SSIM (Multi-Scale SSIM)

An extension of SSIM that operates on multiple scales, making it more robust to viewing distance variations.

PSNR (Peak Signal-to-Noise Ratio)

Measures the ratio between the maximum possible signal power and corrupting noise power. Higher values (in dB) indicate better quality.

MSE (Mean Squared Error)

Calculates the average squared difference between pixels. Lower values indicate better quality (0 means identical images).

Examples

See the examples directory for more usage examples:

• basic.rs - Simple usage of all metrics
• custom_ssim.rs - Advanced SSIM configuration
• model_demo.rs - High-performance batch processing demonstration

Run examples with:

cargo run --example basic
cargo run --example custom_ssim
cargo run --example model_demo

Building from Source

# Clone the repository
git clone https://github.com/ideamans/rust-tjdistler-iqa.git
cd rust-tjdistler-iqa

# Build
cargo build --release

# Run tests
cargo test

# Run benchmarks (requires C library for comparison)
make benchmark

Minimum Supported Rust Version

This crate requires Rust 1.70.0 or later.

License

BSD 3-Clause License. See LICENSE for details.

Acknowledgments

This library is a Rust port of the IQA (Image Quality Assessment) library originally developed by Tom Distler.

Original C implementation: https://sourceforge.net/projects/iqa/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Before contributing:

1. Run cargo fmt to format your code
2. Run cargo clippy to check for common issues
3. Ensure all tests pass with cargo test
4. Add tests for new functionality