docs: align v1 public API docs and examples

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

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<dyn std::error::Error>> {
     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

examples/compare.rs

@@ -82,6 +82,26 @@ fn main() -> Result<(), Box<dyn Error>> {
         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<Srgb8>) {
 /// Prints one metric result, or the error explaining why it could not run.
 fn report(name: &str, result: iqa::Result<f64>, 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}"),
     }
 }

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.

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
 ///