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::{ImageReader, RgbaImage};
 
 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.detect_anti_aliased_pixels,
                 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.detect_anti_aliased_pixels,
                 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.detect_anti_aliased_pixels,
                 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,12 @@ 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 properly
+                    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;
-                    let color =
-                        super::blend_semi_transparent_white(yiq_y, alpha * rgba_a / 255.0) as u8;
+                    // Blend the YIQ Y value with white for output visualization
+                    let color = yiq.blend_with_white(alpha * rgba_a / 255.0) as u8;
 
                     output_image.put_pixel(x, y, Rgba([color, color, color, u8::MAX]));
                 }

src/yiq.rs

@@ -3,8 +3,28 @@ use image::Pixel;
 #[derive(Debug, PartialEq)]
 pub struct Yiq {
     y: f32, // luminance
-    i: f32, // hue of color
-    q: f32, // saturation of color
+    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.
+///
+/// Design considerations from https://github.com/mapbox/pixelmatch/pull/142:
+/// - Non-uniform color (no solid background)
+/// - No large areas of uniform color
+/// - High perceptual variability
+/// - Deterministic computation
+/// - Function of pixel index only
+/// - Avoids common colors (especially white and black)
+/// - Contains no lines or patterns expected in test images
+#[allow(clippy::excessive_precision)]
+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.618033988749895).floor() as u32 % 2) as f32;
+    let b = 48.0 + 159.0 * ((k as f32 / 2.618033988749895).floor() as u32 % 2) as f32;
+    (r, g, b)
 }
 
 impl Yiq {
@@ -18,31 +38,66 @@ 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]);
+    /// 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.
+    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.595_977_99 * r - 0.274_171_6 * g - 0.321_801_89 * 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);
+            // Alpha blending: result = background + (foreground - background) * alpha
+            // When alpha=0: pure background; when alpha=1: pure foreground
+            (
+                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)
+        };
 
-    #[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 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;
 
-        0.211_470_19 * r - 0.522_617_11 * g + 0.311_146_94 * b
+        Self { y, i, q }
     }
 
+    /// Convert RGBA to YIQ without transparency handling.
+    ///
+    /// # Deprecated
+    ///
+    /// This method does not handle transparency correctly. Use [`from_rgba_with_pos`] instead,
+    /// which properly handles transparent and semi-transparent pixels by blending with a
+    /// position-dependent background.
+    #[deprecated(since = "0.7.4", note = "Use from_rgba_with_pos instead for correct transparency handling")]
+    #[allow(dead_code)]
     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);
+        // For i and q, just use opaque values (old behavior)
+        let rgb_channels = rgb.channels();
+        let r = f32::from(rgb_channels[0]);
+        let g = f32::from(rgb_channels[1]);
+        let b = f32::from(rgb_channels[2]);
+        #[expect(clippy::excessive_precision)]
+        let i = 0.595_977_99 * r - 0.274_171_6 * g - 0.321_801_89 * b;
+        #[expect(clippy::excessive_precision)]
+        let q = 0.211_470_19 * r - 0.522_617_11 * g + 0.311_146_94 * b;
 
         Self { y, i, q }
     }
@@ -60,6 +115,10 @@ impl Yiq {
 
         if self.y > other.y { -delta } else { delta }
     }
+
+    pub fn blend_with_white(&self, alpha: f32) -> f32 {
+        255.0 + (self.y - 255.0) * alpha
+    }
 }
 
 #[cfg(test)]
@@ -73,8 +132,16 @@ 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_with_pos(&image::Rgba([0, 0, 0, 255]), 0);
         assert_eq!(expected, actual);
+
+        // Transparent black should blend with background, NOT equal to opaque black
+        let transparent_black = Yiq::from_rgba_with_pos(&image::Rgba([0, 0, 0, 0]), 0);
+        assert_ne!(
+            expected, transparent_black,
+            "Transparent black should not equal opaque black"
+        );
     }
 
     #[test]
@@ -91,4 +158,98 @@ 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);
+
+        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_fully_transparent_pixels_with_different_rgb_compare_equal() {
+        // Fully transparent pixels (alpha=0) should compare equal regardless of RGB values
+        // because they are visually identical (completely invisible)
+        let pos = 42;
+        let transparent_black = Yiq::from_rgba_with_pos(&image::Rgba([0, 0, 0, 0]), pos);
+        let transparent_red = Yiq::from_rgba_with_pos(&image::Rgba([255, 0, 0, 0]), pos);
+        let transparent_white = Yiq::from_rgba_with_pos(&image::Rgba([255, 255, 255, 0]), pos);
+
+        assert_eq!(transparent_black, transparent_red);
+        assert_eq!(transparent_black, transparent_white);
+        assert_eq!(
+            transparent_black.squared_distance(&transparent_red),
+            0.0,
+            "Fully transparent pixels should have zero distance regardless of RGB"
+        );
+    }
+
+    #[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();
@@ -192,3 +195,22 @@ fn test_block_out_area() {
 
     output.close().unwrap();
 }
+
+#[test]
+fn test_transparent_black() {
+    let output = NamedTempFile::new("test_transparent_black.png").unwrap();
+    let mut cmd = Command::new(cargo_bin!("dify"));
+    let assert = cmd
+        .arg(fs::canonicalize("./tests/fixtures/black_transparent.png").unwrap())
+        .arg(fs::canonicalize("./tests/fixtures/black_opaque.png").unwrap())
+        .arg("--output")
+        .arg(output.path().display().to_string());
+
+    assert.assert().code(match consts::OS {
+        "windows" => 7787,
+        "linux" | "macos" => 212,
+        _ => 212,
+    });
+
+    output.close().unwrap();
+}