pixel-diff

Pixel Diff

Pixel-level comparison of two screenshots, producing a difference visualization image.

When to use

• Compare a Figma design draft with a webpage screenshot
• Detect visual regressions caused by CSS changes
• Track UI changes between versions

Prerequisites

• Install Pillow and numpy：pip install Pillow numpy

Usage

python scripts/pixel-diff.py <image_a> <image_b> --output diff.png [--threshold 5] [--highlight-color red]

Parameters

Parameter	Required	Description
image_a	Yes	Reference image (design draft)
image_b	Yes	Comparison image (webpage screenshot)
--output	No	Difference image output path (default diff.png）
--threshold	No	Pixel difference tolerance 0-100 (default 10, lower is stricter)
--highlight-color	No	Difference marker color (default red）

Output

1. diff.png — Difference visualization image (difference areas marked with semi-transparent red)
2. stdout JSON — Difference statistics:

   {
     "total_pixels": 2073600,
     "diff_pixels": 12450,
     "diff_percentage": 0.60,
     "diff_regions": [
       {"x": 100, "y": 200, "width": 300, "height": 50, "label": "region_1"}
     ]
   }
   

Notes

• The two images must have the same resolution; if they differ, the larger one will be automatically resized
• threshold 10 is suitable for general comparison; setting it to 5 can catch more subtle differences
• Font anti-aliasing differences are usually filtered out below threshold 10