tjdistler_iqa/
lib.rs

1//! Fast image quality assessment library
2//!
3//! This crate provides implementations of common image quality metrics:
4//! - SSIM (Structural Similarity Index)
5//! - MS-SSIM (Multi-Scale SSIM)
6//! - PSNR (Peak Signal-to-Noise Ratio)
7//! - MSE (Mean Squared Error)
8//!
9//! # Examples
10//!
11//! ## Basic usage with convenience functions
12//!
13//! ```no_run
14//! use tjdistler_iqa::{ssim, psnr, mse, ms_ssim};
15//!
16//! let reference = vec![0u8; 256 * 256];
17//! let distorted = vec![0u8; 256 * 256];
18//!
19//! let ssim_value = ssim(&reference, &distorted, 256, 256)?;
20//! let psnr_value = psnr(&reference, &distorted, 256, 256)?;
21//! let mse_value = mse(&reference, &distorted, 256, 256)?;
22//! let ms_ssim_value = ms_ssim(&reference, &distorted, 256, 256)?;
23//! # Ok::<(), tjdistler_iqa::IqaError>(())
24//! ```
25//!
26//! ## Advanced usage with builders
27//!
28//! ```no_run
29//! use tjdistler_iqa::{Ssim, ImageQualityAssessment};
30//!
31//! let reference = vec![0u8; 256 * 256];
32//! let distorted = vec![0u8; 256 * 256];
33//!
34//! let ssim = Ssim::builder()
35//!     .k1(0.01)
36//!     .k2(0.03)
37//!     .gaussian(true)
38//!     .build();
39//!
40//! let result = ssim.assess(&reference, &distorted, 256, 256)?;
41//! println!("SSIM: {}", result.value);
42//! # Ok::<(), tjdistler_iqa::IqaError>(())
43//! ```
44//!
45//! ## Model-based repeated comparisons (optimized)
46//!
47//! For scenarios where you need to compare multiple distorted images against the same reference,
48//! use the pre-computed models for significant performance improvements:
49//!
50//! ```no_run
51//! use tjdistler_iqa::{SsimModel, MsSsimModel};
52//!
53//! let reference = vec![0u8; 256 * 256];
54//! let distorted1 = vec![0u8; 256 * 256];
55//! let distorted2 = vec![10u8; 256 * 256];
56//! let distorted3 = vec![20u8; 256 * 256];
57//!
58//! // Pre-compute reference data once
59//! let ssim_model = SsimModel::new(&reference, 256, 256)?;
60//! let ms_ssim_model = MsSsimModel::new(&reference, 256, 256)?;
61//!
62//! // Fast comparisons (40-50% faster than regular functions)
63//! let ssim1 = ssim_model.compare(&distorted1)?;
64//! let ssim2 = ssim_model.compare(&distorted2)?;
65//! let ssim3 = ssim_model.compare(&distorted3)?;
66//!
67//! let ms_ssim1 = ms_ssim_model.compare(&distorted1)?;
68//! let ms_ssim2 = ms_ssim_model.compare(&distorted2)?;
69//! let ms_ssim3 = ms_ssim_model.compare(&distorted3)?;
70//!
71//! println!("SSIM: {:.4}, {:.4}, {:.4}", ssim1, ssim2, ssim3);
72//! println!("MS-SSIM: {:.4}, {:.4}, {:.4}", ms_ssim1, ms_ssim2, ms_ssim3);
73//! # Ok::<(), tjdistler_iqa::IqaError>(())
74//! ```
75
76#![warn(missing_docs)]
77#![warn(missing_debug_implementations)]
78
79/// Error types for image quality assessment operations
80pub mod error;
81/// MS-SSIM (Multi-Scale SSIM) implementation
82pub mod ms_ssim;
83/// Pre-computed MS-SSIM model for efficient repeated comparisons
84pub mod ms_ssim_model;
85/// MSE (Mean Squared Error) implementation
86pub mod mse;
87/// PSNR (Peak Signal-to-Noise Ratio) implementation
88pub mod psnr;
89/// SSIM (Structural Similarity Index) implementation
90pub mod ssim;
91/// Pre-computed SSIM model for efficient repeated comparisons
92pub mod ssim_model;
93
94pub use error::{IqaError, Result};
95pub use ms_ssim::{ms_ssim, MsSsim, MsSsimBuilder};
96pub use ms_ssim_model::{MsSsimModel, MsSsimModelBuilder};
97pub use mse::{mse, Mse};
98pub use psnr::{psnr, Psnr};
99pub use ssim::{ssim, Ssim, SsimBuilder};
100pub use ssim_model::{SsimModel, SsimModelBuilder};
101
102/// Result of an image quality assessment
103#[derive(Debug, Clone, Copy, PartialEq)]
104pub struct ImageQualityResult {
105    /// The computed quality metric value
106    pub value: f64,
107}
108
109impl ImageQualityResult {
110    /// Create a new result with the given value
111    pub fn new(value: f64) -> Self {
112        Self { value }
113    }
114}
115
116impl fmt::Display for ImageQualityResult {
117    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
118        write!(f, "{}", self.value)
119    }
120}
121
122/// Trait for image quality assessment algorithms
123pub trait ImageQualityAssessment {
124    /// Assess the quality between a reference and distorted image
125    ///
126    /// # Arguments
127    ///
128    /// * `reference` - The reference image data (grayscale, 8-bit)
129    /// * `distorted` - The distorted image data (grayscale, 8-bit)
130    /// * `width` - Image width in pixels
131    /// * `height` - Image height in pixels
132    ///
133    /// # Returns
134    ///
135    /// The quality assessment result or an error
136    fn assess(
137        &self,
138        reference: &[u8],
139        distorted: &[u8],
140        width: usize,
141        height: usize,
142    ) -> Result<ImageQualityResult>;
143}
144
145use std::fmt;
tjdistler_iqa/lib.rs

tjdistler_iqa/
lib.rs
