pixelmatch-fast 1.1.0

High-performance Python port of mapbox/pixelmatch for perceptual image comparison

pixelmatch-fast

High-performance Python port of mapbox/pixelmatch for perceptual image comparison

Pixelmatch is a tool that automatically highlights differences between two images while ignoring anti-aliasing artifacts.

For more information about pixelmatch capabilities and examples, see the mapbox/pixelmatch repository.

This project tries to stay up to date with the current pixelmatch version (currently matches with v7.1.0).

Similar Projects

This project is similar to pixelmatch-py. The key difference is that pixelmatch-fast is much faster by leveraging numpy for array operations and numba for JIT compilation.

Use pixelmatch-py if you want a clean port with very little dependencies, use pixelmatch-fast if you need high performance.

Installation

Install the package:

pip install pixelmatch-fast

CLI Usage

$ pixelmatch --help

Usage: pixelmatch [OPTIONS] IMG1 IMG2

  Compare two images pixel-by-pixel and visualize differences.

Options:
  --version              Show the version and exit.
  -o, --output PATH      Path to save diff image (PNG format)
  -t, --threshold FLOAT  Matching threshold (0 to 1); smaller is more
                         sensitive  [default: 0.1]
  --include-aa           Count anti-aliased pixels as different
  -a, --alpha FLOAT      Opacity of original image in diff output  [default:
                         0.1]
  --aa-color TEXT        Color of anti-aliased pixels (R,G,B)  [default:
                         255,255,0]
  --diff-color TEXT      Color of different pixels (R,G,B)  [default: 255,0,0]
  --diff-color-alt TEXT  Alternative diff color for darkened pixels (R,G,B)
  --diff-mask            Draw diff over transparent background
  --help                 Show this message and exit.

Example (using test images from the mapbox/pixelmatch repository):

$ pixelmatch 1a.png 1b.png -o diff.png
Mismatched pixels: 106

The CLI exits with code 0 if images match and 1 if they differ (i.e., one or more mismatched pixels).

Library Usage

from pixelmatch import pixelmatch

# Compare two images and get mismatch count
num_diff = pixelmatch(
    "image1.png",
    "image2.png",
    diff_path="diff.png",  # Optional: save diff image
)

print(f"Found {num_diff} mismatched pixels")

Development

Install with dev dependencies (pytest, ruff):

pip install -e .[dev]

Run tests:

pytest tests/

Run tests with coverage (disables numba JIT compilation):

NUMBA_DISABLE_JIT=1 pytest tests/ --cov

Check code quality:

ruff check
ruff format --check

Install pre-commit hook (runs ruff automatically before commits):

cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

The CI workflow automatically runs tests both with and without numba enabled, ensuring both the optimized and fallback code paths are tested.

License

MIT