Transparent is not white

Reference:
- #32
- mapbox/pixelmatch#142

Author: jihchi

benches/benchmark.rs

@@ -1,6 +1,6 @@
 use criterion::{Criterion, criterion_group, criterion_main};
 use dify::diff;
-use image::{RgbaImage, io::Reader as ImageReader};
+use image::{RgbaImage, ImageReader};
 
 fn get_image(path: &str) -> RgbaImage {
     ImageReader::open(path)
@@ -29,12 +29,13 @@ fn criterion_benchmark(c: &mut Criterion) {
 
         b.iter(|| {
             diff::get_results(
-                &left_image,
-                &right_image,
+                left_image.clone(),
+                right_image.clone(),
                 default_run_params.threshold,
                 default_run_params.do_not_check_dimensions,
                 default_run_params.blend_factor_of_unchanged_pixels,
                 &default_run_params.output_image_base,
+                &default_run_params.block_out_areas,
             )
         })
     });
@@ -45,12 +46,13 @@ fn criterion_benchmark(c: &mut Criterion) {
 
         b.iter(|| {
             diff::get_results(
-                &left_image,
-                &right_image,
+                left_image.clone(),
+                right_image.clone(),
                 default_run_params.threshold,
                 default_run_params.do_not_check_dimensions,
                 default_run_params.blend_factor_of_unchanged_pixels,
                 &default_run_params.output_image_base,
+                &default_run_params.block_out_areas,
             )
         })
     });
@@ -61,12 +63,13 @@ fn criterion_benchmark(c: &mut Criterion) {
 
         b.iter(|| {
             diff::get_results(
-                &left_image,
-                &right_image,
+                left_image.clone(),
+                right_image.clone(),
                 default_run_params.threshold,
                 default_run_params.do_not_check_dimensions,
                 default_run_params.blend_factor_of_unchanged_pixels,
                 &default_run_params.output_image_base,
+                &default_run_params.block_out_areas,
             )
         })
     });

src/diff.rs

@@ -64,8 +64,12 @@ pub fn get_results(
             {
                 DiffResult::BlockedOut(x, y)
             } else {
-                let left_pixel = Yiq::from_rgba(left_pixel);
-                let right_pixel = Yiq::from_rgba(right_pixel);
+                // Calculate linear position for position-dependent background blending
+                // This ensures transparent and opaque versions of the same color compare as different
+                // Use saturating arithmetic to handle theoretically very large images
+                let pos = y.saturating_mul(width).saturating_add(x) as usize;
+                let left_pixel = Yiq::from_rgba_with_pos(left_pixel, pos);
+                let right_pixel = Yiq::from_rgba_with_pos(right_pixel, pos);
                 let delta = left_pixel.squared_distance(&right_pixel);
 
                 if delta.abs() > threshold {
@@ -99,10 +103,14 @@ pub fn get_results(
             DiffResult::Identical(x, y) | DiffResult::BelowThreshold(x, y) => {
                 if let Some(alpha) = blend_factor_of_unchanged_pixels {
                     let left_pixel = left_image.get_pixel(x, y);
-                    let yiq_y = Yiq::rgb2y(&left_pixel.to_rgb());
+                    // Use position-aware YIQ conversion to handle transparency correctly
+                    // Use saturating arithmetic to handle theoretically very large images
+                    let pos = y.saturating_mul(width).saturating_add(x) as usize;
+                    let yiq = Yiq::from_rgba_with_pos(left_pixel, pos);
                     let rgba_a = left_pixel.channels()[3] as f32;
+                    // Blend the YIQ Y value with white for output visualization
                     let color =
-                        super::blend_semi_transparent_white(yiq_y, alpha * rgba_a / 255.0) as u8;
+                        super::blend_semi_transparent_white(yiq.y, alpha * rgba_a / 255.0) as u8;
 
                     output_image.put_pixel(x, y, Rgba([color, color, color, u8::MAX]));
                 }

src/yiq.rs

@@ -2,11 +2,42 @@ use image::Pixel;
 
 #[derive(Debug, PartialEq)]
 pub struct Yiq {
-    y: f32, // luminance
+    pub y: f32, // luminance
     i: f32, // hue of color
     q: f32, // saturation of color
 }
 
+/// Calculate background color components for blending transparent pixels.
+/// Uses position-dependent colors (like pixelmatch) to ensure transparent
+/// and opaque versions of the same color compare as different.
+///
+/// Based on: https://github.com/mapbox/pixelmatch/pull/142
+///
+/// # Design Principles (from pixelmatch)
+/// 1. Background should NOT be a uniform color
+/// 2. Background should NOT contain large areas of uniform color
+/// 3. Background should have perceptual variability
+/// 4. Background should be deterministic
+/// 5. Background color should be easy to compute
+/// 6. Background should NOT contain "common colors" (white/black)
+/// 7. Background should NOT contain lines
+/// 8. Background should not contain anything we'd expect in test images
+///
+/// # Magic Numbers Explained
+/// - **48.0**: Base value - ensures minimum color value, avoiding pure black
+/// - **159.0**: Range multiplier (48 + 159 = 207, staying below 255)
+///   - Provides large color variability while avoiding white/black/saturated colors
+/// - **1.616, 2.612**: Irrational coefficients for color pattern periods
+///   - Carefully chosen to prevent pattern from degenerating into lines
+///   - Extra digits preserve irrationality for very large images
+///   - These values create a checkerboard-like pattern that repeats
+fn background_color(k: usize) -> (f32, f32, f32) {
+    let r = 48.0 + 159.0 * ((k % 2) as f32);
+    let g = 48.0 + 159.0 * ((k as f32 / 1.616).floor() as u32 % 2) as f32;
+    let b = 48.0 + 159.0 * ((k as f32 / 2.612).floor() as u32 % 2) as f32;
+    (r, g, b)
+}
+
 impl Yiq {
     #[allow(clippy::many_single_char_names, clippy::excessive_precision)]
     pub fn rgb2y(rgb: &image::Rgb<u8>) -> f32 {
@@ -18,31 +49,48 @@ impl Yiq {
         0.298_895_31 * r + 0.586_622_47 * g + 0.114_482_23 * b
     }
 
-    #[allow(clippy::many_single_char_names, clippy::excessive_precision)]
-    fn rgb2i(rgb: &image::Rgb<u8>) -> f32 {
-        let rgb = rgb.channels();
-        let r = f32::from(rgb[0]);
-        let g = f32::from(rgb[1]);
-        let b = f32::from(rgb[2]);
-
-        0.595_977_99 * r - 0.274_171_6 * g - 0.321_801_89 * b
+    /// Convert RGBA to YIQ (legacy method - uses position 0 for backward compatibility).
+    /// For comparing images with transparency, use `from_rgba_with_pos` instead.
+    #[allow(dead_code)]
+    pub fn from_rgba(rgba: &image::Rgba<u8>) -> Self {
+        Self::from_rgba_with_pos(rgba, 0)
     }
 
-    #[allow(clippy::many_single_char_names, clippy::excessive_precision)]
-    fn rgb2q(rgb: &image::Rgb<u8>) -> f32 {
-        let rgb = rgb.channels();
-        let r = f32::from(rgb[0]);
-        let g = f32::from(rgb[1]);
-        let b = f32::from(rgb[2]);
+    /// Convert RGBA to YIQ with position-dependent background blending for transparent pixels.
+    /// This ensures transparent and opaque versions of the same color compare as different.
+    ///
+    /// # Arguments
+    /// * `rgba` - The RGBA pixel to convert
+    /// * `pos` - Linear position (pixel index) for background color calculation
+    pub fn from_rgba_with_pos(rgba: &image::Rgba<u8>, pos: usize) -> Self {
+        let rgba_channels = rgba.channels();
+        let r = f32::from(rgba_channels[0]);
+        let g = f32::from(rgba_channels[1]);
+        let b = f32::from(rgba_channels[2]);
+        let a = f32::from(rgba_channels[3]);
 
-        0.211_470_19 * r - 0.522_617_11 * g + 0.311_146_94 * b
-    }
+        let (r_final, g_final, b_final) = if a < 255.0 {
+            // Blend with position-dependent background for transparent/semi-transparent pixels
+            let alpha = a / 255.0;
+            let (bg_r, bg_g, bg_b) = background_color(pos);
+            (
+                bg_r + (r - bg_r) * alpha,
+                bg_g + (g - bg_g) * alpha,
+                bg_b + (b - bg_b) * alpha,
+            )
+        } else {
+            // Fully opaque - use RGB values as-is
+            (r, g, b)
+        };
 
-    pub fn from_rgba(rgba: &image::Rgba<u8>) -> Self {
-        let rgb = rgba.to_rgb();
-        let y = Self::rgb2y(&rgb);
-        let i = Self::rgb2i(&rgb);
-        let q = Self::rgb2q(&rgb);
+        // Convert the blended RGB to YIQ
+        // Standard YIQ conversion coefficients - precision is intentional
+        #[expect(clippy::excessive_precision)]
+        let y = 0.298_895_31 * r_final + 0.586_622_47 * g_final + 0.114_482_23 * b_final;
+        #[expect(clippy::excessive_precision)]
+        let i = 0.595_977_99 * r_final - 0.274_171_6 * g_final - 0.321_801_89 * b_final;
+        #[expect(clippy::excessive_precision)]
+        let q = 0.211_470_19 * r_final - 0.522_617_11 * g_final + 0.311_146_94 * b_final;
 
         Self { y, i, q }
     }
@@ -73,8 +121,13 @@ mod tests {
             i: 0.0,
             q: 0.0,
         };
-        let actual = Yiq::from_rgba(&image::Rgba([0, 0, 0, 0]));
+        // Fully opaque black should have zero YIQ
+        let actual = Yiq::from_rgba(&image::Rgba([0, 0, 0, 255]));
         assert_eq!(expected, actual);
+
+        // Transparent black should blend with background, NOT equal to opaque black
+        let transparent_black = Yiq::from_rgba(&image::Rgba([0, 0, 0, 0]));
+        assert_ne!(expected, transparent_black, "Transparent black should not equal opaque black");
     }
 
     #[test]
@@ -91,4 +144,82 @@ mod tests {
         };
         assert_eq!(a.squared_distance(&b), 0.0);
     }
+
+    #[test]
+    fn test_issue_32_transparent_vs_opaque_black() {
+        // Issue #32: Transparent black (#00000000) and opaque black (#000000FF)
+        // should NOT compare as equal since they appear different visually.
+        let opaque_black = Yiq::from_rgba_with_pos(&image::Rgba([0, 0, 0, 255]), 0);
+        let transparent_black = Yiq::from_rgba_with_pos(&image::Rgba([0, 0, 0, 0]), 0);
+
+        // These should NOT have a squared_distance of 0.0 (they should be different)
+        // This test will FAIL before the fix and PASS after
+        assert_ne!(
+            opaque_black.squared_distance(&transparent_black),
+            0.0,
+            "Transparent black and opaque black should have different YIQ values"
+        );
+    }
+
+    #[test]
+    fn test_semi_transparent_pixels() {
+        // Semi-transparent pixels (alpha between 0 and 255) should be handled
+        // by blending with the background color
+        let opaque = Yiq::from_rgba_with_pos(&image::Rgba([100, 50, 25, 255]), 0);
+        let semi_transparent = Yiq::from_rgba_with_pos(&image::Rgba([100, 50, 25, 128]), 0);
+        let transparent = Yiq::from_rgba_with_pos(&image::Rgba([100, 50, 25, 0]), 0);
+
+        // All three should have different YIQ values due to different blending
+        assert_ne!(opaque.y, semi_transparent.y);
+        assert_ne!(opaque.y, transparent.y);
+        assert_ne!(semi_transparent.y, transparent.y);
+    }
+
+    #[test]
+    fn test_position_dependent_background() {
+        // Same transparent color at different positions should have different
+        // YIQ values due to position-dependent background blending
+        let transparent_red_pos0 = Yiq::from_rgba_with_pos(&image::Rgba([255, 0, 0, 0]), 0);
+        let transparent_red_pos1 = Yiq::from_rgba_with_pos(&image::Rgba([255, 0, 0, 0]), 1);
+
+        assert_ne!(
+            transparent_red_pos0, transparent_red_pos1,
+            "Same transparent color at different positions should differ"
+        );
+    }
+
+    #[test]
+    fn test_opaque_pixels_position_independent() {
+        // Opaque pixels should NOT be affected by position
+        let opaque_red_pos0 = Yiq::from_rgba_with_pos(&image::Rgba([255, 0, 0, 255]), 0);
+        let opaque_red_pos1 = Yiq::from_rgba_with_pos(&image::Rgba([255, 0, 0, 255]), 100);
+
+        assert_eq!(
+            opaque_red_pos0, opaque_red_pos1,
+            "Opaque pixels should be position-independent"
+        );
+    }
+
+    #[test]
+    fn test_various_colors_with_transparency() {
+        // Test that transparency handling works for different colors
+        let color_rgb = [
+            [255, 0, 0],    // red
+            [0, 255, 0],    // green
+            [0, 0, 255],    // blue
+            [255, 255, 255], // white
+        ];
+
+        // All transparent colors should differ from their opaque equivalents
+        for rgb in color_rgb {
+            let transparent = Yiq::from_rgba_with_pos(&image::Rgba([rgb[0], rgb[1], rgb[2], 0]), 0);
+            let opaque = Yiq::from_rgba_with_pos(&image::Rgba([rgb[0], rgb[1], rgb[2], 255]), 0);
+
+            assert_ne!(
+                transparent, opaque,
+                "Transparent {:?} should differ from opaque",
+                rgb
+            );
+        }
+    }
 }

tests/e2e.rs

@@ -42,10 +42,11 @@ fn test_left_does_not_exist() {
 Caused by:
     {} (os error 2)
 "#,
-        left.display().to_string(),
+        left.display(),
         match consts::OS {
             "windows" => "The system cannot find the file specified.",
-            "linux" | "macos" | _ => "No such file or directory",
+            "linux" | "macos" => "No such file or directory",
+            _ => "Unknown error",
         }
     ));
 }
@@ -64,10 +65,11 @@ fn test_right_does_not_exist() {
 Caused by:
     {} (os error 2)
 "#,
-        right.display().to_string(),
+        right.display(),
         match consts::OS {
             "windows" => "The system cannot find the file specified.",
-            "linux" | "macos" | _ => "No such file or directory",
+            "linux" | "macos" => "No such file or directory",
+            _ => "Unknown error",
         }
     ));
 }
@@ -101,7 +103,8 @@ fn test_different_image() {
 
     assert.assert().code(match consts::OS {
         "windows" => 7787,
-        "linux" | "macos" | _ => 106,
+        "linux" | "macos" => 106,
+        _ => 106,
     });
 
     output.close().unwrap();