pascalorg Image Compare
Compare two images pixel-by-pixel. Returns a diff count, mismatch percentage, and generates a diff image highlighting the differences in red.
When to Use
- Comparing an implementation screenshot against the original design
- Spotting visual regressions between two versions of a page
- Verifying that a UI matches a Figma export
How It Works
- Both images are loaded and resized to match dimensions (uses the smaller of the two)
pixelmatchcompares every pixel and flags differences above a configurable threshold- Returns mismatch stats and writes a diff image showing changes in red
Usage
bash <skill-path>/scripts/image-compare.sh <image1> <image2> [diff-output.png] [threshold]
Arguments:
image1— First image path (required)image2— Second image path (required)diff-output.png— Path to write the diff image (optional, defaults to./diff.png)threshold— Pixel matching threshold 0-1, lower is stricter (optional, defaults to0.1)
Examples:
# Compare a design against implementation
bash <skill-path>/scripts/image-compare.sh design.png screenshot.png
# Compare with custom threshold and output path
bash <skill-path>/scripts/image-compare.sh before.png after.png ./changes.png 0.05
Output
{
"totalPixels": 921600,
"differentPixels": 4523,
"mismatchPercentage": 0.49,
"dimensions": { "width": 1280, "height": 720 },
"diffImage": "./diff.png",
"threshold": 0.1
}
| Field | Type | Description |
|---|---|---|
| totalPixels | Number | Total pixels compared |
| differentPixels | Number | Number of pixels that differ |
| mismatchPercentage | Number | Percentage of pixels that differ |
| dimensions | Object | Width and height used for comparison |
| diffImage | String | Path to the generated diff image |
| threshold | Number | Sensitivity threshold used |
Present Results to User
After comparing, present a summary:
Comparison: design.png vs screenshot.png
Mismatch: 0.49% (4,523 pixels out of 921,600)
Diff image saved to: ./diff.png
The images are nearly identical. Differences are highlighted in red in the diff image.
Interpret the percentage:
- < 0.1% — Essentially identical
- 0.1% - 1% — Minor differences, likely anti-aliasing or sub-pixel rendering
- 1% - 5% — Noticeable differences, worth reviewing
- > 5% — Significant visual changes
Troubleshooting
Different sized images — The script automatically resizes both images to the smaller dimensions. For best results, use images of the same size.
Too many false positives — Increase the threshold (e.g., 0.2). Anti-aliasing differences are common between browsers.