From c3b767ab7d1fe0b0e250262a11c236e5f5bc0cfc Mon Sep 17 00:00:00 2001 From: Justin Chung <20733699+justin13888@users.noreply.github.com> Date: Wed, 10 Jun 2026 17:38:07 -0400 Subject: [PATCH] docs: align v1 public API docs and examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Finalization pass over the v1.2.0 public surface (no signature changes): - README: fix stale `version = "0.1"` install pins (3x) to "1.2". - ms_ssim/iw_ssim: replace broken `[module docs](self)` intra-doc links (private modules — warned under `cargo doc` and unreachable on docs.rs) with an inline scale-count note. - examples/compare + README quick-start: show all 9 metrics (add MS-SSIM, IW-SSIM, PSNR-HVS-M, CIEDE2000); widen the example's print column. --- Cargo.toml | 2 +- README.md | 22 +++++++++++++++++++--- examples/compare.rs | 24 ++++++++++++++++++++++-- src/iw_ssim.rs | 7 ++++--- src/ms_ssim.rs | 7 ++++--- 5 files changed, 50 insertions(+), 12 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index d35b0d8..ae24205 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -108,7 +108,7 @@ image = { version = "0.25", default-features = false, features = ["png", "jpeg", [[example]] name = "compare" -required-features = ["psnr", "ssim", "dssim", "ssimulacra2", "butteraugli"] +required-features = ["psnr", "ssim", "dssim", "ms-ssim", "iw-ssim", "psnr-hvs-m", "ciede2000", "ssimulacra2", "butteraugli"] [package.metadata.docs.rs] # Document every metric (including the C++ ones) on docs.rs, matching the default diff --git a/README.md b/README.md index 8ebc9ed..21e7714 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ C/C++ toolchain at all, disable the defaults and take just the metrics you need: ```toml [dependencies] -iqa = { version = "0.1", default-features = false, features = ["psnr"] } +iqa = { version = "1.2", default-features = false, features = ["psnr"] } ``` ## Quick start @@ -64,6 +64,22 @@ fn main() -> Result<(), Box> { let dssim = iqa::dssim(&reference, &distorted, iqa::DssimOptions::default())?; println!("DSSIM: {dssim:.3}"); + // MS-SSIM — pure Rust; multi-scale SSIM, 1.0 = identical. + let msssim = iqa::msssim(&reference, &distorted, iqa::MsssimOptions::default())?; + println!("MS-SSIM: {msssim:.3}"); + + // IW-SSIM — pure Rust; information-weighted SSIM, 1.0 = identical. + let iwssim = iqa::iwssim(&reference, &distorted, iqa::IwssimOptions::default())?; + println!("IW-SSIM: {iwssim:.3}"); + + // PSNR-HVS-M — pure Rust; DCT-domain PSNR with HVS masking, higher is better. + let psnr_hvs_m = iqa::psnr_hvs_m(&reference, &distorted, iqa::PsnrHvsOptions::default())?; + println!("PSNR-HVS-M: {psnr_hvs_m:.3} dB"); + + // CIEDE2000 — pure Rust; mean ΔE₀₀ color difference, 0.0 = identical, lower is better. + let ciede2000 = iqa::ciede2000(&reference, &distorted, iqa::Ciede2000Options::default())?; + println!("CIEDE2000: {ciede2000:.3}"); + // SSIMULACRA2 — requires the `ssimulacra2` feature; 100 = identical. let ssimulacra2 = iqa::ssimulacra2(&reference, &distorted)?; println!("SSIMULACRA2: {ssimulacra2:.3}"); @@ -218,7 +234,7 @@ metrics you need: ```toml [dependencies] # Pure-Rust subset only — no C/C++ toolchain required. -iqa = { version = "0.1", default-features = false, features = ["psnr"] } +iqa = { version = "1.2", default-features = false, features = ["psnr"] } ``` ### Building the C++ metrics (`ssimulacra2`, `butteraugli`) @@ -240,7 +256,7 @@ library via `pkg-config`: ```toml [dependencies] -iqa = { version = "0.1", default-features = false, features = ["psnr", "ssim", "ssimulacra2", "system-lcms2"] } +iqa = { version = "1.2", default-features = false, features = ["psnr", "ssim", "ssimulacra2", "system-lcms2"] } ``` ```sh diff --git a/examples/compare.rs b/examples/compare.rs index 1d248c4..19bc64e 100644 --- a/examples/compare.rs +++ b/examples/compare.rs @@ -82,6 +82,26 @@ fn main() -> Result<(), Box> { iqa::dssim(&reference, &distorted, iqa::DssimOptions::default()), " (0 = identical, lower is better)", ); + report( + "MS-SSIM (RGB-averaged)", + iqa::msssim(&reference, &distorted, iqa::MsssimOptions::default()), + " (1.0 = identical)", + ); + report( + "IW-SSIM (RGB-averaged)", + iqa::iwssim(&reference, &distorted, iqa::IwssimOptions::default()), + " (1.0 = identical)", + ); + report( + "PSNR-HVS-M (RGB-averaged)", + iqa::psnr_hvs_m(&reference, &distorted, iqa::PsnrHvsOptions::default()), + "dB (higher is better)", + ); + report( + "CIEDE2000 (ΔE₀₀)", + iqa::ciede2000(&reference, &distorted, iqa::Ciede2000Options::default()), + " (0 = identical, lower is better)", + ); report( "SSIMULACRA2", iqa::ssimulacra2(&reference, &distorted), @@ -109,7 +129,7 @@ fn describe(role: &str, path: &OsString, image: &Image) { /// Prints one metric result, or the error explaining why it could not run. fn report(name: &str, result: iqa::Result, unit: &str) { match result { - Ok(score) => println!(" {name:<22} {score:>9.3} {unit}"), - Err(error) => println!(" {name:<22} error: {error}"), + Ok(score) => println!(" {name:<25} {score:>9.3} {unit}"), + Err(error) => println!(" {name:<25} error: {error}"), } } diff --git a/src/iw_ssim.rs b/src/iw_ssim.rs index e844748..d898f9f 100644 --- a/src/iw_ssim.rs +++ b/src/iw_ssim.rs @@ -83,9 +83,10 @@ pub struct IwssimOptions { /// channel layout, or bit depth is rejected by the compiler rather than at /// run time. An alpha channel, if present, is ignored. The score ranges over /// `(-1, 1]`; higher is better, and pixel-identical images score exactly `1.0`. -/// Each image must be at least 11x11 (the size of the Gaussian window); see the -/// [module docs](self) for how the number of pyramid scales adapts to the image -/// size. +/// Each image must be at least 11x11 (the size of the Gaussian window). The +/// metric uses up to five pyramid scales, dropping coarser scales (and +/// renormalizing their weights) for images too small to hold them; all five run +/// at 176x176 and larger, matching the reference. /// /// Unlike SSIM and MS-SSIM, IW-SSIM is **not symmetric**: its weights come from /// a model of the *reference*, so swapping the arguments can change the score. diff --git a/src/ms_ssim.rs b/src/ms_ssim.rs index 7871393..85e6617 100644 --- a/src/ms_ssim.rs +++ b/src/ms_ssim.rs @@ -67,9 +67,10 @@ pub struct MsssimOptions { /// channel layout, or bit depth is rejected by the compiler rather than at /// run time. An alpha channel, if present, is ignored. The score ranges over /// `(-1, 1]`; higher is better, and pixel-identical images score exactly `1.0`. -/// Each image must be at least 11x11 (the size of the Gaussian window); see the -/// [module docs](self) for how the number of pyramid scales adapts to the image -/// size. +/// Each image must be at least 11x11 (the size of the Gaussian window). The +/// metric uses up to five pyramid scales, dropping coarser scales (and +/// renormalizing their weights) for images too small to hold them; all five run +/// at 176x176 and larger, matching the reference. /// /// # Errors ///