RustScreenDiffAI

RustScreenDiffAI is a Rust CLI pixel-diff engine for screenshot regression checks. It compares two images pixel by pixel, calculates the changed-pixel percentage, and returns a clear PASS or FAIL verdict against a configurable threshold.

Why This Exists

Visual regressions are easiest to miss when screens look “mostly fine.” RustScreenDiffAI provides a deterministic, script-friendly image comparison step that can be used in QA workflows, CI jobs, screenshot tests, and digital signage review pipelines.

Features

• Compares two PNG or image files using the Rust image crate.
• Validates that both screenshots have identical dimensions.
• Counts changed pixels exactly.
• Calculates diff percentage from total pixels.
• Supports configurable pass/fail threshold.
• Emits terminal output for manual review.
• Emits JSON output for automation.
• Handles identical images, partial diffs, full diffs, and dimension mismatch errors.

Installation

git clone https://github.com/SUDARSHANCHAUDHARI/RustScreenDiffAI.git
cd RustScreenDiffAI
cargo build --release

The binary is created at:

target/release/screendiff

Optional local install:

cargo install --path .

Usage

# Compare two screenshots with the default 1% threshold
screendiff compare before.png after.png

# Allow up to 5% difference
screendiff compare before.png after.png --threshold 0.05

# Emit JSON
screendiff compare before.png after.png --json

# Write a visual diff image with changed pixels highlighted in magenta
screendiff compare before.png after.png --diff-output diff.png

Included Example

The repository includes two tiny PPM fixtures:

screendiff compare examples/before.ppm examples/after.ppm --threshold 0.10

screendiff compare examples/before.ppm examples/after.ppm --diff-output diff.png

Real output:

ScreenDiff Report
Before: examples/before.ppm
After: examples/after.ppm
Total Pixels: 16
Diff Pixels: 1
Diff: 6.25%
Threshold: 10.00%
Verdict: PASS

How It Works

1. Load both images.
2. Verify dimensions match.
3. Compare every pixel pair.
4. Count changed pixels.
5. Calculate diff_percent = diff_pixels / total_pixels.
6. Optionally write a diff image where changed pixels are magenta and unchanged pixels come from the baseline image.
7. Return PASS when diff_percent <= threshold; otherwise return FAIL.

Example Output

ScreenDiff Report
Before:        before.png
After:         after.png
Total Pixels:  10000
Diff Pixels:   42
Diff:          0.42%
Threshold:     1.00%
Verdict:       PASS

Threshold Guidance

Threshold	Typical Use
0.00	Exact pixel match required
0.01	Default, allows up to 1% changed pixels
0.05	Looser check for anti-aliasing or dynamic content

Development

cargo fmt --check
cargo clippy -- -D warnings
cargo test
cargo build --release

The integration tests cover zero diff, full diff, one-pixel changes, threshold behavior, dimension mismatch, CLI output, and visual diff image generation.

Project Structure

src/
  cli.rs          Command-line interface
  diff/           Pixel comparison engine
  report.rs       Verdict and report output
tests/
  integration_test.rs

Project Docs

• Architecture
• Roadmap
• Maintainer notes
• Content plan

Release Status

Current production release: v1.1.0

The v1.1.0 release was verified with formatting, clippy, tests, optimized release build, and cargo package.

License

MIT. See LICENSE.

Developer

Built by Sudarshan Chaudhari under SudarshanTechLabs.