pixelmatch

Warnings

• breaking `pixelmatch.contrib.PIL.pixelmatch` now uses a fast path for byte-identical images. When an `output` image is provided and `diff_mask=False`, grayscale diff output values can differ slightly (typically up to +/-1 per channel due to PIL rounding) compared to previous versions. This primarily affects the exact pixel values of the generated diff image, not the mismatch count.
  Fix: Review your test expectations if you rely on precise grayscale values in the diff output when `diff_mask=False` and images are nearly identical. No action needed if you primarily use the mismatch count or `diff_mask=True`.
• breaking Support for older Python versions (3.7-3.9) has been dropped.
  Fix: Ensure your project runs on Python 3.10 or newer.
• gotcha The primary `pixelmatch` function (for raw image data) and the PIL-contributed `pixelmatch` function expect input images to have identical dimensions. If dimensions differ, an error will be raised or unexpected results may occur.
  Fix: Always ensure `img1` and `img2` have the same width and height before passing them to `pixelmatch`.
• gotcha For raw image data comparison, the `pixelmatch` function expects RGBA image data (e.g., a byte array where pixels are represented as [R, G, B, A, R, G, B, A, ...]). Incorrect data format will lead to wrong comparisons or errors.
  Fix: Ensure raw image data is in the expected RGBA byte array format.
• gotcha The `pixelmatch` (pure Python) package is significantly slower than its C++-bound alternative, `pybind11-pixelmatch`, especially for large images or frequent comparisons. While `pixelmatch` is a pure Python port, `pybind11-pixelmatch` offers superior performance for performance-critical applications.
  Fix: For highly performant image comparison, consider using `pybind11-pixelmatch` instead, which is a separate package with a C++ backend. Be aware that its API might differ slightly.

Install

• pip install pixelmatch Install stable version
• pip install pixelmatch pillow Install with Pillow for PIL.Image support

Imports

• pixelmatch

  from pixelmatch import pixelmatch

  For comparing raw RGBA image data (byte arrays).
• pixelmatch

  from pixelmatch.contrib.PIL import pixelmatch

  For comparing PIL.Image instances.

Quickstart

This example demonstrates how to compare two PIL.Image instances, highlight their differences, and get the count of mismatched pixels. It creates two dummy images, introduces a single pixel difference, and then uses `pixelmatch` to compare them. The `img_diff` object will contain the visual representation of the differences.

from PIL import Image
from pixelmatch.contrib.PIL import pixelmatch
import io

def create_dummy_image(width, height, color):
    img = Image.new('RGBA', (width, height), color)
    return img

# Create two identical images
img1 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image
img2 = create_dummy_image(100, 100, (255, 0, 0, 255)) # Red image

# Make a slight difference in img2
img2.putpixel((10, 10), (0, 0, 255, 255)) # Blue pixel at (10,10)

img_diff = Image.new('RGBA', img1.size)

mismatch = pixelmatch(img1, img2, img_diff, threshold=0.1, includeAA=True)

print(f"Number of mismatched pixels: {mismatch}")

# Save the diff image (optional, for visualization)
# To run this, you'd need actual file paths or use BytesIO
# with open('diff.png', 'wb') as f:
#    img_diff.save(f, format='PNG')
# print("Diff image saved as diff.png")