Add docs

ChrisRega · ChrisRega · Aug 18, 2025 · Aug 3, 2025 · Aug 3, 2025 · Aug 3, 2025
commit 708e57cda71fad077c196ec7a45eeb532a2e2d86
diff --git a/src/hybrid.rs b/src/hybrid.rs
@@ -183,6 +183,18 @@ pub fn rgb_hybrid_compare(first: &RgbImage, second: &RgbImage) -> Result<Similar
     internal_yuv_hybrid_compare(&first_channels, &second_channels)
 }
 
+/// Comparing structure via MSSIM on Y channel, comparing color-diff-vectors on U and V summing the squares
+/// first_channels and second_channels are arrays, each containing 3 `GrayImage`s
+/// - The first GrayImage contains the Y values - similarity(ssim, y)
+/// - The second GrayImage contains the U values - similarity(rms, u)
+/// - The third GrayImage contains the V values - similarity(rms, v)
+/// Please mind that the SimilarityImage does _not_ contain plain RGB here
+/// - The red channel contains 1. - similarity(ssim, y)
+/// - The green channel contains 1. - similarity(rms, u)
+/// - The blue channel contains 1. - similarity(rms, v)
+/// This leads to a nice visualization of color and structure differences - with structural differences (meaning gray mssim diffs) leading to red rectangles
+/// and and the u and v color diffs leading to color-deviations in green, blue and cyan
+/// All-black meaning no differences
 #[cfg(feature = "yuv_compare")]
 pub fn yuv_hybrid_compare(first_channels: &[GrayImage; 3], second_channels: &[GrayImage; 3]) -> Result<Similarity, CompareError> {
     if (first_channels[0].dimensions() != second_channels[0].dimensions())

diff --git a/src/lib.rs b/src/lib.rs
@@ -81,6 +81,7 @@ mod ssim;
 #[cfg(not(feature="yuv_compare"))]
 mod utils;
 
+/// Provides some utilities to make yuv image management and conversion easier.
 #[cfg(feature="yuv_compare")] // Exposes rgb/yuv conversions and split to yuv publicly, others were left to be pub crate or private
 pub mod utils;
 

diff --git a/src/utils.rs b/src/utils.rs
@@ -67,8 +67,11 @@ pub(crate) fn blend_alpha(image: &RgbaImage, color: Rgb<u8>) -> RgbImage {
     buffer
 }
 
+/// Holds methods to split an RgbImage into arrays of channels
 pub trait Decompose {
+    /// Returns an array containing 3 `GrayImage`s where each channel represents [r, g, b]
     fn split_channels(&self) -> [GrayImage; 3];
+    /// Converts an image to yuv then returns an array containing 3 `GrayImage`s where each channel represents [y, u, v]
     fn split_to_yuv(&self) -> [GrayImage; 3];
 }