whtsky / pixelmatch-py

A fast pixel-level image comparison library, originally created to compare screenshots in tests.

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.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

pixelmatch-py's Issues

0.3.0: pytest fails in all units with `cannot identify image file`

I'm packaging your module as an rpm package so I'm using the typical PEP517 based build, install and test cycle used on building packages from non-root account.

• python3 -sBm build -w --no-isolation
• because I'm calling build with --no-isolation I'm using during all processes only locally installed modules
• install .whl file in </install/prefix> using 'installer` module
• run pytest with $PYTHONPATH pointing to sitearch and sitelib inside </install/prefix>
• build is performed in env which is cut off from access to the public network (pytest is executed with -m "not network")

List of installed modules in build env:

Package            Version
------------------ -------
build              1.0.3
cppclean           0.13
distro             1.9.0
dnf                4.18.2
exceptiongroup     1.1.3
gpg                1.23.2
importlib_metadata 7.0.1
iniconfig          2.0.0
installer          0.7.0
libdnf             0.72.0
olefile            0.47
packaging          23.2
pillow             10.2.0
pluggy             1.3.0
poetry-core        1.9.0
py-cpuinfo         9.0.0
pyproject_hooks    1.0.0
pytest             8.0.0
pytest-benchmark   4.0.0
python-dateutil    2.8.2
six                1.16.0
tomli              2.0.1
wheel              0.42.0
zipp               3.17.0

Please let me know if you need more details or want me to perform some diagnostics.

OpenCV image support

This library supports only PIL type of image. It would be nice to add OpenCV support so that the main input function would take as input NumPy arrays. Also, it seems like the width and the height of images could be determined inside the package rather than outside. I would be willing to write PR, but it won't be sooner than in three weeks

Test failures

On NixOS during the build process of the packages we get two error.

============================= test session starts ==============================
platform linux -- Python 3.9.9, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
benchmark: 3.2.2 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /build/pixelmatch-py
plugins: benchmark-3.2.2, mypy-0.8.1
collected 28 items                                                             

test_pixelmatch.py .F....................                                [ 78%]
pixelmatch/__init__.py .                                                 [ 82%]
pixelmatch/core.py .                                                     [ 85%]
pixelmatch/types.py .                                                    [ 89%]
pixelmatch/utils.py F                                                    [ 92%]
pixelmatch/contrib/__init__.py .                                         [ 96%]
pixelmatch/contrib/PIL.py .                                              [100%]

=================================== FAILURES ===================================
_________________________________ test session _________________________________
mypy exited with status 1.
------------------------------ Captured log call -------------------------------
DEBUG    filelock:_api.py:154 Attempting to acquire lock 140737197711808 on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:158 Lock 140737197711808 acquired on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:188 Attempting to release lock 140737197711808 on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:191 Lock 140737197711808 released on /build/tmph8bqrjul.lock
_____________________________ pixelmatch/utils.py ______________________________
30: error: Incompatible types in assignment (expression has type "int", variable has type "Union[Literal[1], Literal[0]]")
81: error: Incompatible types in assignment (expression has type "int", variable has type "Union[Literal[1], Literal[0]]")
------------------------------ Captured log call -------------------------------
DEBUG    filelock:_api.py:154 Attempting to acquire lock 140737206904960 on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:158 Lock 140737206904960 acquired on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:188 Attempting to release lock 140737206904960 on /build/tmph8bqrjul.lock
DEBUG    filelock:_api.py:191 Lock 140737206904960 released on /build/tmph8bqrjul.lock
===================================== mypy =====================================
Found 2 errors in 1 file (checked 7 source files)
=========================== short test summary info ============================
FAILED test_pixelmatch.py::mypy-status
FAILED pixelmatch/utils.py::mypy
======================== 2 failed, 26 passed in 43.42s =========================

Could you please take a look? Thanks

No module named 'pixelmatch.contrib'; 'pixelmatch' is not a package

I have this error

...pixelmatch.py", line 3, in <module>
    from pixelmatch.contrib.PIL import pixelmatch
ModuleNotFoundError: No module named 'pixelmatch.contrib'; 'pixelmatch' is not a package

when I run the following code:

from PIL import Image

from pixelmatch.contrib.PIL import pixelmatch

img_a = Image.open("1.png")
img_b = Image.open("2.png")
img_diff = Image.new("RGBA", img_a.size)

mismatch = pixelmatch(img_a, img_b, img_diff, includeAA=True)

img_diff.save("diff.png")

My pip list:

$ pip list
Package          Version
---------------- ---------
async-generator  1.10
attrs            22.1.0
certifi          2022.9.14
cffi             1.15.1
h11              0.13.0
idna             3.4
numpy            1.23.3
outcome          1.2.0
pandas           1.4.4
Pillow           9.2.0
pip              22.0.4
pixelmatch       0.3.0
pycparser        2.21
PySocks          1.7.1
python-dateutil  2.8.2
pytz             2022.2.1
selenium         4.4.3
setuptools       58.1.0
six              1.16.0
sniffio          1.3.0
sortedcontainers 2.4.0
trio             0.21.0
trio-websocket   0.9.2
urllib3          1.26.12
wsproto          1.2.0

Python Version:
Python 3.9.13 (tags/v3.9.13:6de2ca5, May 17 2022, 16:36:42) [MSC v.1929 64 bit (AMD64)] on win32

Add a Boolean version

I was wondering if adding a boolean version of the pixelmatch method would be a good idea.

For my current project, due to the images being the same but in different formats/variations, pixel match has been really good at helping me sus out matching. But when all I'm looking for is a zero, the extra time it takes isn't needed.

So if a method was added that would do the exact same thing but, instead of adding one to a counter, just returned false right away.

from PIL import Image

from pixelmatch.contrib.PIL import dopixelsmatch

img_a = Image.open("a.png")
img_b = Image.open("b.png")

if dopixelsmatch(img_a, img_b):
    #Do something

使用里面参数写错了

使用里面写错了，都用了 img_a

data_a = pil_to_flatten_data(img_a)
data_b = pil_to_flatten_data(img_a)

support for pixelmatching directly on PIL.Image objects

I can see that this project has no dependencies currently, and this would add Pillow. But chances are people will already be using Pillow to manipulate their image data, so I think the impact would be minimal.

I would be willing to write a PR that implements this.

It takes lots of time more than the version of npm

I tested with a large image ,such as ( 1080 *2340).

It takes almost 5 seconds when the version in npm (https://github.com/mapbox/pixelmatch) only finished within 1 second.

Make options pythonic

Currently this library supports options in the form of a dictionary, however, this is quite unpythonic in my opinion and hinders the use of this library. I propose that you allow for **kwargs instead of requiring the passing in of a dictionary.

I'm willing to write a PR

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

File: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error near version ht