pixelhog

Fast visual regression primitives for Python, implemented in Rust.

pixelhog compares screenshots in two complementary ways:

• diff: exact pixel-level differences (with anti-alias handling), optional diff image output
• ssim: perceptual similarity score in [0.0, 1.0]

It also provides spatial clustering (where on the page did things change), early-exit checks, and WebP thumbnail generation — all accessible through a stateful Comparison object that decodes images once and exposes methods on demand.

Install (local dev)

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install -U pip maturin
maturin develop --release

Quickstart

from pixelhog import Comparison, thumbnail

cmp = Comparison(baseline_png, current_png)

count = cmp.diff_count()                     # pixel mismatch count
score = cmp.ssim()                           # perceptual similarity
png   = cmp.diff_image()                     # diff visualization (PNG bytes)
thumb = cmp.current_thumbnail(width=200)     # lossless WebP thumbnail

# Spatial clustering — where did things change?
result = cmp.clusters(dilation=8, merge_gap=60)
for cluster in result.clusters:
    print(cluster.bbox.x, cluster.bbox.y, cluster.bbox.width, cluster.bbox.height)

# Early exit — fail fast if too many diffs
capped = cmp.diff_count_capped(max_diffs=1000)

# Standalone thumbnail (lossless WebP, Lanczos3 downscale, top-crop)
thumb = thumbnail(current_png, width=200, height=150)

API at a glance

Comparison

Utilities and batch

Row alignment (vertical shifts)

A panel grows by a pixel, a banner is inserted, a list gains a row — everything below moves down. A top-aligned pixel diff then flags most of the page and SSIM reports large dissimilarity, even though nothing else changed. row_alignment() hashes each pixel row and runs a budgeted Myers diff over the hashes.

cmp = Comparison(baseline_png, current_png)
alignment = cmp.row_alignment()

if alignment.aligned:
    print(alignment.inserted_rows, alignment.deleted_rows, alignment.residual_count)
    for band in alignment.bands:
        print(band.kind, band.y, band.rows)      # "inserted" / "deleted", current-image rows

    clusters = cmp.aligned_clusters(alignment)   # clusters of the residual only
    score = cmp.aligned_ssim(alignment)          # SSIM over the matched rows only
    png = cmp.aligned_diff_image(alignment)      # diff image in current-image coordinates

The cluster mask holds the residual only. Shift bands are the other half of the answer, so read alignment.bands to decide whether to absorb a shift or flag it. An alignment belongs to the pair it was computed from; passing it to another Comparison raises. Tune the bail-out with max_edit_ratio (default 0.25) and max_edit_rows (default 2048).

Behavior

• Comparison decodes PNG bytes once at construction; methods compute on demand.
• Comparison.from_rgba(...) accepts pre-decoded RGBA buffers (zero-copy).
• Smaller images are padded to the larger dimensions with transparent pixels.
• SSIM uses 11×11 uniform windows with reflect padding; falls back to global for tiny images.
• Clustering uses morphological dilation + two-pass CCL with optional aligned-bbox merge.
• Row alignment hashes rows and runs a budgeted Myers diff over the hashes. It is vertical only: a width change makes a pair unalignable.

Correctness and tests

The test suite is designed to validate both algorithm fidelity and practical product behavior.

• Rust unit/integration tests cover:
  • identical/completely different/partial-diff images
  • threshold behavior
  • different-size padding behavior
  • SSIM behavior (identical, slight change, large change, small-image fallback)
• Canonical pixelmatch fixture tests use the official Mapbox test set:
  • 8 fixture pairs with exact expected mismatch counts
  • expected diff image comparison against golden outputs
  • decoded RGBA byte equality checks to ensure pixel-perfect output matching
• Python integration tests cover:
  • high-level API contracts and error behavior
  • tall-page and subtle-change scenarios
  • cross-validation against a pure-Python reference implementation
    • pixel diff counts must match exactly
    • SSIM must stay within tolerance

Run the full correctness suite:

# Rust core only
cargo test -p pixelhog

# Full suite including Python integration tests
cargo test
uv run --python 3.12 --with maturin --with pytest --with pillow bash -lc \
  "maturin develop --release && pytest -q"

Benchmarks

The repo includes both Criterion benches and pipeline breakdown tools.

• cargo bench runs Criterion API benchmarks (PNG-bytes entry points).
• Breakdown binaries in examples/ measure where time goes:
  • breakdown.rs: decode vs core diff vs encode vs API call
  • ssim_breakdown.rs: decode/pad vs core SSIM vs API call
  • combined_estimate.rs: separate calls vs combined single-decode flow

Run:

cargo bench -p pixelhog
cargo run -p pixelhog --release --example breakdown
cargo run -p pixelhog --release --example ssim_breakdown
cargo run -p pixelhog --release --example combined_estimate

For screenshot-style workloads, the practical guidance is:

• diff_count is cheaper than diff when you do not need an artifact.
• compare(..., return_diff=False) avoids duplicate decode work when you need both diff-count and SSIM.

Development

# Rust tests (includes canonical Mapbox fixture tests)
cargo test

# Python extension + tests
uv run --python 3.12 --with maturin --with pytest --with pillow bash -lc \
  "maturin develop --release && pytest -q"

# Lint/format/type-check
uv run --python 3.12 --with ruff ruff format --check .
uv run --python 3.12 --with ruff ruff check .
uv run --python 3.12 --with ty --with pytest --with pillow ty check . --python .venv

License

This repository is MIT licensed. See LICENSE.

Algorithm attribution for pixelmatch is documented in THIRD_PARTY_NOTICES.md.