pixelmatch-py

A fast pixel-level image comparison library, originally created to compare screenshots in tests. Now with additional support of PIL.Image instances Python port of https://github.com/mapbox/pixelmatch.

Features accurate anti-aliased pixels detection and perceptual color difference metrics.

from pixelmatch import pixelmatch

num_diff_pixels = pixelmatch(img1, img2, 800, 600, diff, threshold=0.1)

Implements ideas from the following papers:

• Measuring perceived color difference using YIQ NTSC transmission color space in mobile applications (2010, Yuriy Kotsarenko, Fernando Ramos)
• Anti-aliased pixel and intensity slope detector (2009, Vytautas Vyšniauskas)

Install

python -m pip install pixelmatch

Example usage

PIL.Image comparison

from PIL import Image

from pixelmatch.contrib.PIL import pixelmatch

img_a = Image.open("a.png")
img_b = Image.open("b.png")
img_diff = Image.new("RGBA", img_a.size)

# note how there is no need to specify dimensions
mismatch = pixelmatch(img_a, img_b, img_diff, includeAA=True)

img_diff.save("diff.png")

Raw Image Data Comparison

from pixelmatch import pixelmatch

width, height = 1920, 1080
img_a = [R1, G1, B1, A1, R2, B2, G2, A2, ...]
img_b = [R1, G1, B1, A1, R2, B2, G2, A2, ...]

data_diff = [0] * len(img_a)

mismatch = pixelmatch(img_a, img_b, width, height, data_diff, includeAA=True)

API

pixelmatch(img1, img2, width, height, output, threshold, includeAA, alpha, aa_color, diff_color, diff_mask, fail_fast)

• img1, img2 — RGBA Image data of the images to compare. Note: image dimensions must be equal.
• width, height — Width and height of the images.
• output — Image data to write the diff to, or None if don't need a diff image. Note that all three images need to have the same dimensions.
• threshold — Matching threshold, ranges from 0 to 1. Smaller values make the comparison more sensitive. 0.1 by default.
• includeAA — If true, disables detecting and ignoring anti-aliased pixels. false by default.
• alpha — Blending factor of unchanged pixels in the diff output. Ranges from 0 for pure white to 1 for original brightness. 0.1 by default.
• aa_color — The color of anti-aliased pixels in the diff output in [R, G, B] format. [255, 255, 0] by default.
• diff_color — The color of differing pixels in the diff output in [R, G, B] format. [255, 0, 0] by default.
• diff_mask — Draw the diff over a transparent background (a mask), rather than over the original image. Will not draw anti-aliased pixels (if detected).
• fail_fast - If true, will return after first different pixel.

Compares two images, writes the output diff and returns the number of mismatched pixels.

contrib.PIL.pixelmatch

Compares two images, writes the output diff and returns the number of mismatched pixels. Exact same API as pixelmatch.pixelmatch except for the important fact that it takes instances of PIL.Image for image parameters (img1, img2, and output) and the width/size need not be specified.

Example output

expected	actual	diff

Changelog

v0.4.0

• BREAKING CHANGE: remove pixelmatch.contrib.PIL.from_PIL_to_raw_data and pixelmatch.contrib.PIL.to_PIL_from_raw_data #181 (@brianhelba)
• BREAKING CHANGE: pixelmatch.contrib.PIL.pixelmatch now uses a fast path for byte-identical images; when output is provided and diff_mask=False, grayscale diff output values can differ from previous versions (typically up to +/-1 per channel due to PIL rounding) #181 (@brianhelba)
• perf: improve pixelmatch.contrib.PIL.pixelmatch performance (about 90x for identical images with diff_mask=False, about 150x with diff_mask=True) #181 (@brianhelba)

v0.3.1

• fix: remove use of deprecated Pillow function #178 (@brianhelba)
• chore: drop EOL Python versions (3.7-3.9), add support for 3.10-3.14 #171

v0.3.0

• feat: add fail_fast option #144

v0.2.4

• type: fix typing issues
• chore: test Python 3.10

v0.2.3

• feat: make package comply with PEP-561

v0.2.2

• typing: use Sequence instead of List for RGBTuple
• build: switch to poetry_core #81

v0.2.1

• feat: add function to compare PIL.Image instances through contrib.PIL.pixelmatch #42

v0.2.0

• BREAKING CHANGE: remove options parameter #38
• docs: use absolute url for images in README

v0.1.1

• fix: fix bug in fast path #18

v0.1.0

• Initial release