Skip to main content

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

Method Returns Notes
Comparison(baseline_png, current_png) Comparison Decode pair once, call methods on demand
Comparison.from_rgba(...) Comparison Pre-decoded RGBA buffers
Comparison.batch(pairs) list[Comparison] Parallel decode
.diff_count(threshold, include_aa) int Pixel mismatch count
.diff_count_capped(max_diffs, ...) int Early-exit count
.ssim() float Structural similarity
.clusters(dilation, merge_gap, ...) ClustersResult Spatial regions of change
.row_alignment(...) RowAlignment Separate a vertical shift from real changes
.aligned_clusters(alignment, ...) ClustersResult Clusters of the changed content, shift left out
.aligned_ssim(alignment) float SSIM over the matched rows only
.aligned_diff_image(alignment, ...) bytes (PNG) Shift-aware diff visualization
.diff_image(...) bytes (PNG) Diff visualization
.current_thumbnail(width, height, ...) bytes (WebP) Thumbnail of current image
.baseline_thumbnail(width, height, ...) bytes (WebP) Thumbnail of baseline image
.size_mismatch bool Whether images had different dimensions

Utilities and batch

Function Input Output Use when
thumbnail PNG bytes bytes (WebP) Single-image thumbnail (no pair needed)
diff_batch list[(baseline, current)] list[DiffResult] Parallel diff across many pairs
diff_count_batch list[(baseline, current)] list[DiffCountResult] Parallel count-only
ssim_batch list[(baseline, current)] list[float] Parallel SSIM
compare_batch list[(baseline, current)] list[CompareResult] Parallel combined metrics

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 changed content
    score = cmp.aligned_ssim(alignment)          # SSIM over the matched rows only
    png = cmp.aligned_diff_image(alignment)      # diff image in current-image coordinates
Field Meaning
aligned False when the pair could not be aligned: too different, or a width change (alignment is vertical only). Every other field is then zero or empty, and every aligned_* method raises.
inserted_rows / deleted_rows Rows the current image gained or lost — the shift itself.
changed_rows Rows present in both images whose content differs.
residual_count Differing pixels inside those changed rows. This is the number to threshold on: it excludes the shift.
bands Where the content below moved, in current-image coordinates, as the diff image draws it. A deleted band is the seam row the removed rows left behind. Band rows can differ from the counts when a region was replaced.

The cluster mask holds the changed content only. Shift bands are the other half of the answer, so read alignment.bands to decide whether to absorb a shift or flag it.

A region replaced by content of a different height, such as a tall chart swapped for a short one, keeps blank rows that both versions share. The Myers diff matches those blank rows inside the region, so the fields above report the change as separate inserted and deleted rows. aligned_diff_image(), aligned_clusters() and bands show such a region as one changed region instead, followed by the rows one side has over the other. The counts and residual_count do not change, so thresholds that read them behave as before. 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.

Metadata

Release files for pixelhog 1.3.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pixelhog 1.3.2
File Size Uploaded Provenance Actions
pixelhog-1.3.2.tar.gz 49.0 kB With provenance Details for pixelhog-1.3.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pixelhog 1.3.2
File Actions
pixelhog-1.3.2-cp312-abi3-win_arm64.whl CPython 3.12 abi3 Windows ARM64 Details for pixelhog-1.3.2-cp312-abi3-win_arm64.whl
pixelhog-1.3.2-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for pixelhog-1.3.2-cp312-abi3-win_amd64.whl
pixelhog-1.3.2-cp312-abi3-musllinux_1_2_x86_64.whl CPython 3.12 abi3 Linux musl 1.2+ x86-64 Details for pixelhog-1.3.2-cp312-abi3-musllinux_1_2_x86_64.whl
pixelhog-1.3.2-cp312-abi3-musllinux_1_2_aarch64.whl CPython 3.12 abi3 Linux musl 1.2+ ARM64 Details for pixelhog-1.3.2-cp312-abi3-musllinux_1_2_aarch64.whl
pixelhog-1.3.2-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.12 abi3 Linux glibc 2.17+ x86-64 Details for pixelhog-1.3.2-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
pixelhog-1.3.2-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.12 abi3 Linux glibc 2.17+ ARM64 Details for pixelhog-1.3.2-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
pixelhog-1.3.2-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for pixelhog-1.3.2-cp312-abi3-macosx_11_0_arm64.whl
pixelhog-1.3.2-cp312-abi3-macosx_10_12_x86_64.whl CPython 3.12 abi3 macOS 10.12+ x86-64 Details for pixelhog-1.3.2-cp312-abi3-macosx_10_12_x86_64.whl

Total release size: 6.0 MB

Release files / pixelhog-1.3.2.tar.gz

Download URL pixelhog-1.3.2.tar.gz
Size 49.0 kB
Tags Source
SHA-256 checksum
How to use checksums
92b8db4eeac0b609969381132518c13e813135384840f1e965d69c55ad683055
BLAKE2b-256 checksum
How to use checksums
e63427da90c201cefc1552c8bd9df77b4230a328cf24cff877bb1a05082d0b57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-win_arm64.whl

Download URL pixelhog-1.3.2-cp312-abi3-win_arm64.whl
Size 624.9 kB
Tags CPython 3.12 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
ec2340eb50a2550a552e34e78b8822a8f87c748c337748baea8ebd95853c0fbc
BLAKE2b-256 checksum
How to use checksums
1fb2564897bb6f035534af984121c05e58726628c9ebe1139aa402da25e756dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-win_amd64.whl

Download URL pixelhog-1.3.2-cp312-abi3-win_amd64.whl
Size 640.2 kB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
ec1d8de81e4175d92cda8bdffcb13d8c819b9790dc32bd8f60faf4a3a324def0
BLAKE2b-256 checksum
How to use checksums
a6377bf00fc07c17b16d43811e3fcd383f0a2bf464783b5808f8c709913cb0cd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-musllinux_1_2_x86_64.whl

Download URL pixelhog-1.3.2-cp312-abi3-musllinux_1_2_x86_64.whl
Size 953.5 kB
Tags CPython 3.12 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
5157b393ef455c3843f9ef24ce01cdfb728dd6cd6d4458f6618c9101870cba50
BLAKE2b-256 checksum
How to use checksums
29ffeb68ebce20cd7eeb843e8d29c6e0d870acdbbece4c48a1aed604a81ee652
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-musllinux_1_2_aarch64.whl

Download URL pixelhog-1.3.2-cp312-abi3-musllinux_1_2_aarch64.whl
Size 893.3 kB
Tags CPython 3.12 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
90eb296530114d72aa4813565496d6c7d76d94831866f2eddb28258161f4351d
BLAKE2b-256 checksum
How to use checksums
2a7fe46b511223fa0c69de12b3d7736dcb7bf2025d01463fca7eb6e8babd80c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL pixelhog-1.3.2-cp312-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 759.6 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
9e0c8fbfb7877744f1ee9863139d9b6cf2871376af0b6f1a2d6e40f8769b85fc
BLAKE2b-256 checksum
How to use checksums
221713f4eadeffe59f6aec0c93b04052166257dafe3bd42587d14397dcf54c5b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL pixelhog-1.3.2-cp312-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 715.3 kB
Tags CPython 3.12 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
5108f96d09931d7d3f8f8677aecf98cd73c2326c46826686f28766f1d1a2be3e
BLAKE2b-256 checksum
How to use checksums
7a665f7eb9b245652a9fab29fb8563f1626a5f54c4135bec18ec89a35ec0816c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-macosx_11_0_arm64.whl

Download URL pixelhog-1.3.2-cp312-abi3-macosx_11_0_arm64.whl
Size 673.5 kB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
777087620d85469825bcb1c0504ebc38f5a283a21162fbc2120e9d8487d0a244
BLAKE2b-256 checksum
How to use checksums
32587549a02cf566f1bbcfecfcd76b1b0f056df74f548fc9f7edd284f1d8da6f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / pixelhog-1.3.2-cp312-abi3-macosx_10_12_x86_64.whl

Download URL pixelhog-1.3.2-cp312-abi3-macosx_10_12_x86_64.whl
Size 680.7 kB
Tags CPython 3.12 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
77c2d1fbef3e02eec263777589dc16a7066b63471cd25a46eac886ce8b72712e
BLAKE2b-256 checksum
How to use checksums
fea42895d8581e8c2c6a2649ba9192d530f4d396d5506630b702dce619da8a23
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for pixelhog 1.3.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for pixelhog-1.3.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page