Pixelmatch for Humans and AI - Fast pixel-level image comparison library for MoonBit/WASM.

Port of mapbox/pixelmatch to MoonBit.

• YIQ color space for perceptual color difference
• Anti-aliasing detection
• Configurable threshold
• Diff image generation
• AI-friendly diff reports with automatic shape hints
• Simple and fast API

moon add mizchi/pixelmatch

let img1 = @pixelmatch.Image::new(100, 100)
let img2 = @pixelmatch.Image::new(100, 100)

// Fill images with pixel data...

// Simple comparison
let diff_count = @pixelmatch.pixelmatch_simple(img1, img2, 0.1)

// Full comparison with options
let options = @pixelmatch.Options::default()
let output = @pixelmatch.Image::new(100, 100)
let diff_count = @pixelmatch.pixelmatch(img1, img2, Some(output), options)

// Get match ratio (0.0 to 1.0)
let ratio = @pixelmatch.match_ratio(img1, img2, options)

// Generate AI-friendly diff report
let report = @pixelmatch.diff_report(img1, img2, options)
println(report.to_compact())             // Minimal tokens for AI
println(report.to_compact_with_hints())  // With shape hints (recommended)
println(report.to_text())                // Verbose for humans
println(report.to_json())                // Structured JSON

The to_compact() method generates a minimal-token format optimized for AI:

diff:100/2500(96%match)
..........
.XX.......
.XX.......
..........
..........
..........
..........
..........
..........
..........
regions:5,5,10x10

Format:

• Line 1: diff:count/total(match%)
• Lines 2-11: 10x10 binary heatmap (. = no diff, X = diff)
• Last line: regions:x,y,WxH;... (semicolon-separated)

The to_compact_with_hints() method adds automatic shape detection:

diff:952/2500(61%match)
..........
..XXXXXX..
.XXXXXXXX.
.XXXXXXXX.
.XXX..XXX.
.XXX...XXX
.XXXX.XXX.
.XXXXXXXX.
..XXXXXX..
..........
regions:5,5,41x41
hints:HAS_HOLE: shape may have empty center (ring/donut/frame)

Available hints:

Result: 90% accuracy

Result: 60% → 95% accuracy with hints

For complex shapes, use grid_size=20:

let report = diff_report(img1, img2, options, grid_size=20)

Recommendation: Use to_compact_with_hints() for best accuracy/token ratio.

PNG encode/decode dominates the pipeline (97% on WASM, 99% on JS). Optimizing the codec (e.g., native zlib C FFI) has far more impact than pixelmatch itself in E2E scenarios.

GPU compute becomes faster than Rayon+prefilter only when buffers are already on GPU (no upload cost). With per-frame upload, CPU always wins.

Detailed crossover (5% diff, dispatch only vs Rayon+prefilter):

size          pixels   rayon+pf   gpu_dispatch
256x256       0.07MP       55µs       1329µs   ← Rayon 24x faster
1024x1024     1.05MP      306µs       1350µs   ← Rayon 4.4x faster
1920x1080     2.07MP      674µs       1355µs   ← Rayon 2.0x faster
2048x2048     4.19MP     2682µs       1354µs   ← GPU wins (2.0x)
3840x2160     8.29MP     2179µs       1510µs   ← GPU wins (1.4x)
4000x4000    16.00MP     3988µs       2790µs   ← GPU wins (1.4x)

The crossover above assumes diff count only (4-byte atomic counter readback). If you need a per-pixel diff heatmap, the readback cost changes drastically:

Effective GPU time with heatmap readback (dispatch only, prealloc):

1920x1080:  dispatch 1.35ms + heatmap readback 1.7ms = ~3.0ms  (vs Rayon 674µs → Rayon wins)
3840x2160:  dispatch 1.51ms + heatmap readback 6.5ms = ~8.0ms  (vs Rayon 2179µs → Rayon wins)

Heatmap readback erases GPU's compute advantage at all tested sizes. Practical strategies:

1. Two-stage pipeline: GPU dispatch for fast diff-count triage (4B readback). Only generate heatmaps on CPU (Rayon) for the few pairs with diff > 0. In typical VRT, 90%+ of pairs are identical.
2. GPU-side rendering: Keep heatmap on GPU as a texture and render directly (WebGPU in browser). Zero readback cost.
3. Partial readback: Read back only a grid summary (e.g., 64x36 block counts = 9KB) instead of per-pixel data.

• Use pixelmatch_fast — automatically picks the best implementation per target
• WASM is the fastest portable target — 1.5-2.5x faster than JS across all benchmarks
• Native C FFI is 15-30x faster than WASM for pixelmatch itself (15µs vs 225µs @200x200 identical)
• E2E bottleneck is PNG codec, not pixelmatch — encode/decode is 97%+ of pipeline time on WASM
• Row prefilter skips identical rows with fast memcmp — up to 25x for nearly-identical images
• Rust Rayon + prefilter is the fastest CPU option at 5.8x over single-threaded
• GPU (wgpu) wins at 4MP+ with pre-allocated buffers for diff-count only, but heatmap readback negates the advantage
• Best batch VRT architecture: GPU for triage (diff/no-diff), CPU Rayon for heatmap on flagged pairs

Run benchmarks: just bench (MoonBit) / just bench-rs (Rust)

Compare two images and return the number of different pixels.

Simple comparison without anti-aliasing detection.

Recommended for most use cases. Unified API that dispatches to the fastest implementation per target:

• Native: C FFI with hardware memcmp + LLVM auto-vectorized YIQ delta
• JS/WASM: Row-level prefilter (memcmp-style skip)

Simple comparison with row-level prefilter. Skips identical rows using fast comparison.

C FFI optimized comparison. Called internally by pixelmatch_fast on native target.

Calculate match ratio (0.0 = completely different, 1.0 = identical).

Generate comprehensive diff report with statistics, heatmap, and regions.

Apache-2.0