feat: add support for ignore regions

- Added --ignore flag to skip specific image areas (x,y,w,h)
- Implemented region-aware comparison loop
- Updated README with usage examples

Author: maskedsyntax

README.md

@@ -0,0 +1,62 @@
+# image-diff
+
+![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-blue)
+![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)
+
+**image-diff** is a high-performance CLI tool designed for visual regression testing and dataset validation. It provides structural and pixel-level comparison of images with instant terminal-native previews.
+
+## Features
+
+- **Blazing Fast:** Parallel directory processing using Rust's Rayon.
+- **Terminal Previews:** View diff heatmaps directly in your terminal using ANSI half-blocks.
+- **Dual Metrics:** Reports both raw Pixel Similarity and Structural Similarity (SSIM).
+- **Directory Diffing:** Recursively compare folders of images with summary reporting.
+- **CI/CD Ready:** Support for JSON output and semantic exit codes.
+
+## Installation
+
+Ensure you have Rust installed, then clone and build:
+
+```bash
+git clone https://github.com/cachevector/image-diff
+cd image-diff
+cargo build --release
+```
+
+The binary will be available at `./target/release/image-diff`.
+
+## Usage
+
+### Compare two images
+```bash
+image-diff baseline.png screenshot.png --preview --output diff.png
+```
+
+### Compare directories recursively
+```bash
+image-diff ./goldens/ ./screenshots/ --threshold 0.1
+```
+
+### Automation & CI/CD
+Fail the build if any differences are found and output machine-readable results:
+```bash
+image-diff a.png b.png --json --fail-on-diff
+```
+
+### Ignore dynamic regions
+Ignore parts of the image that change frequently (like timestamps):
+```bash
+image-diff a.png b.png --ignore 0,0,100,50 --ignore 500,500,200,100
+```
+
+## CLI Options
+
+| Option | Description | Default |
+| :--- | :--- | :--- |
+| `-t, --threshold` | Sensitivity for pixel comparison (0.0 to 1.0) | `0.1` |
+| `-p, --preview` | Render a low-res diff heatmap in the terminal | `false` |
+| `-o, --output` | Path to save the high-res diff overlay image | `None` |
+| `-i, --ignore` | Ignore region in `x,y,w,h` format | `[]` |
+| `--json` | Output machine-readable results in JSON format | `false` |
+| `--fail-on-diff` | Return exit code 1 if differences are detected | `false` |

src/compare.rs

@@ -14,11 +14,26 @@ pub struct DiffResult {
     pub diff_image: Option<ImageBuffer<Rgba<u8>, Vec<u8>>>,
 }
 
+#[derive(Serialize, Clone, Debug)]
+pub struct Region {
+    pub x: u32,
+    pub y: u32,
+    pub width: u32,
+    pub height: u32,
+}
+
+impl Region {
+    pub fn contains(&self, x: u32, y: u32) -> bool {
+        x >= self.x && x < self.x + self.width && y >= self.y && y < self.y + self.height
+    }
+}
+
 pub fn compare_images(
     path_a: &Path,
     path_b: &Path,
     threshold: f32,
     generate_diff: bool,
+    ignore_regions: &[Region],
 ) -> Result<DiffResult> {
     let img_a = image::open(path_a)?;
     let img_b = image::open(path_b)?;
@@ -57,10 +72,16 @@ pub fn compare_images(
 
     for y in 0..max_height {
         for x in 0..max_width {
+            let is_ignored = ignore_regions.iter().any(|r| r.contains(x, y));
+
             let pixel_a = rgba_a.get_pixel(x, y);
             let pixel_b = rgba_b.get_pixel(x, y);
 
-            let dist = color_distance(pixel_a, pixel_b);
+            let dist = if is_ignored {
+                0.0 // Treat as identical
+            } else {
+                color_distance(pixel_a, pixel_b)
+            };
 
             let is_different = dist > (threshold as f64);
 
@@ -70,9 +91,10 @@ pub fn compare_images(
                     buffer.put_pixel(x, y, Rgba([255, 0, 255, 255]));
                 }
             } else if let Some(ref mut buffer) = diff_buffer {
-                let r = (pixel_a[0] as f32 * 0.1) as u8;
-                let g = (pixel_a[1] as f32 * 0.1) as u8;
-                let b = (pixel_a[2] as f32 * 0.1) as u8;
+                let factor = if is_ignored { 0.02 } else { 0.1 };
+                let r = (pixel_a[0] as f32 * factor) as u8;
+                let g = (pixel_a[1] as f32 * factor) as u8;
+                let b = (pixel_a[2] as f32 * factor) as u8;
                 buffer.put_pixel(x, y, Rgba([r, g, b, 255]));
             }
         }

src/dir.rs

@@ -1,4 +1,4 @@
-use crate::compare::{compare_images, DiffResult};
+use crate::compare::{compare_images, DiffResult, Region};
 use anyhow::Result;
 use indicatif::{ProgressBar, ProgressStyle};
 use rayon::prelude::*;
@@ -24,6 +24,7 @@ pub fn compare_directories(
     dir_a: &Path,
     dir_b: &Path,
     threshold: f32,
+    ignore_regions: &[Region],
 ) -> Result<Vec<DirDiffItem>> {
     let files_a: Vec<PathBuf> = WalkDir::new(dir_a)
         .into_iter()
@@ -46,7 +47,7 @@ pub fn compare_directories(
             let status = if !path_b.exists() {
                 DirDiffStatus::MissingInB
             } else {
-                match compare_images(&path_a, &path_b, threshold, false) {
+                match compare_images(&path_a, &path_b, threshold, false, ignore_regions) {
                     Ok(res) => DirDiffStatus::Match(res),
                     Err(e) => DirDiffStatus::Error(e.to_string()),
                 }

src/main.rs

@@ -7,6 +7,22 @@ use clap::Parser;
 use colored::*;
 use std::path::PathBuf;
 
+use crate::compare::Region;
+use std::str::FromStr;
+
+impl FromStr for Region {
+    type Err = anyhow::Error;
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let parts: Vec<u32> = s.split(',')
+            .map(|p| p.parse::<u32>())
+            .collect::<std::result::Result<Vec<_>, _>>()?;
+        if parts.len() != 4 {
+            return Err(anyhow::anyhow!("Region must be in format x,y,width,height"));
+        }
+        Ok(Region { x: parts[0], y: parts[1], width: parts[2], height: parts[3] })
+    }
+}
+
 #[derive(Parser, Debug)]
 #[command(author, version, about, long_about = None)]
 struct Args {
@@ -35,6 +51,10 @@ struct Args {
     /// Output results in JSON format
     #[arg(long)]
     json: bool,
+
+    /// Ignore regions in format x,y,width,height (can be used multiple times)
+    #[arg(short, long, value_delimiter = ' ')]
+    ignore: Vec<Region>,
 }
 
 fn main() -> Result<()> {
@@ -53,6 +73,7 @@ fn run_file_diff(args: &Args) -> Result<()> {
         &args.path_b,
         args.threshold,
         args.output.is_some() || args.preview,
+        &args.ignore,
     )?;
 
     if args.json {
@@ -86,7 +107,7 @@ fn run_file_diff(args: &Args) -> Result<()> {
 }
 
 fn run_dir_diff(args: &Args) -> Result<()> {
-    let items = dir::compare_directories(&args.path_a, &args.path_b, args.threshold)?;
+    let items = dir::compare_directories(&args.path_a, &args.path_b, args.threshold, &args.ignore)?;
 
     let mut diff_count = 0;