# 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**.
```python
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](https://pdfs.semanticscholar.org/cb71/56034b6e427ddc9b5da1a4f5fcb10831c9fd.pdf) (2010, Yuriy Kotsarenko, Fernando Ramos)
- [Anti-aliased pixel and intensity slope detector](https://www.researchgate.net/publication/234126755_Anti-aliased_Pixel_and_Intensity_Slope_Detector) (2009, Vytautas Vyšniauskas)
## Install
```bash
python -m pip install pixelmatch
```
## Example usage
### PIL.Image comparison
```python
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
```python
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](https://github.com/whtsky/pixelmatch-py/pull/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](https://github.com/whtsky/pixelmatch-py/pull/81)
### v0.2.1
- feat: add function to compare PIL.Image instances through contrib.PIL.pixelmatch [#42](https://github.com/whtsky/pixelmatch-py/pull/42)
### v0.2.0
- BREAKING CHANGE: remove `options` parameter [#38](https://github.com/whtsky/pixelmatch-py/pull/38)
- docs: use absolute url for images in README
### v0.1.1
- fix: fix bug in fast path [#18](https://github.com/whtsky/pixelmatch-py/pull/18)
### v0.1.0
- Initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/whtsky/pixelmatch-py",
"name": "pixelmatch",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Wu Haotian",
"author_email": "whtsky@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/59/ebc53e64156db78c75c6d7f535e3f80f62c8a8e1545783770f06f528e187/pixelmatch-0.3.0.tar.gz",
"platform": null,
"description": "# pixelmatch-py\n\nA fast pixel-level image comparison library, originally created to compare screenshots in tests.\nNow with additional support of PIL.Image instances\nPython port of https://github.com/mapbox/pixelmatch.\n\nFeatures accurate **anti-aliased pixels detection**\nand **perceptual color difference metrics**.\n\n```python\nfrom pixelmatch import pixelmatch\n\nnum_diff_pixels = pixelmatch(img1, img2, 800, 600, diff, threshold=0.1)\n```\n\nImplements ideas from the following papers:\n\n- [Measuring perceived color difference using YIQ NTSC transmission color space in mobile applications](https://pdfs.semanticscholar.org/cb71/56034b6e427ddc9b5da1a4f5fcb10831c9fd.pdf) (2010, Yuriy Kotsarenko, Fernando Ramos)\n- [Anti-aliased pixel and intensity slope detector](https://www.researchgate.net/publication/234126755_Anti-aliased_Pixel_and_Intensity_Slope_Detector) (2009, Vytautas Vy\u0161niauskas)\n\n## Install\n\n```bash\npython -m pip install pixelmatch\n```\n\n## Example usage\n\n### PIL.Image comparison\n\n```python\nfrom PIL import Image\n\nfrom pixelmatch.contrib.PIL import pixelmatch\n\nimg_a = Image.open(\"a.png\")\nimg_b = Image.open(\"b.png\")\nimg_diff = Image.new(\"RGBA\", img_a.size)\n\n# note how there is no need to specify dimensions\nmismatch = pixelmatch(img_a, img_b, img_diff, includeAA=True)\n\nimg_diff.save(\"diff.png\")\n```\n\n### Raw Image Data Comparison\n\n```python\nfrom pixelmatch import pixelmatch\n\nwidth, height = 1920, 1080\nimg_a = [R1, G1, B1, A1, R2, B2, G2, A2, ...]\nimg_b = [R1, G1, B1, A1, R2, B2, G2, A2, ...]\n\ndata_diff = [0] * len(img_a)\n\nmismatch = pixelmatch(img_a, img_b, width, height, data_diff, includeAA=True)\n```\n\n## API\n\n### pixelmatch(img1, img2, width, height, output, threshold, includeAA, alpha, aa_color, diff_color, diff_mask, fail_fast)\n\n- `img1`, `img2` \u2014 RGBA Image data of the images to compare. **Note:** image dimensions must be equal.\n- `width`, `height` \u2014 Width and height of the images.\n- `output` \u2014 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.\n- `threshold` \u2014 Matching threshold, ranges from `0` to `1`. Smaller values make the comparison more sensitive. `0.1` by default.\n- `includeAA` \u2014 If `true`, disables detecting and ignoring anti-aliased pixels. `false` by default.\n- `alpha` \u2014 Blending factor of unchanged pixels in the diff output. Ranges from `0` for pure white to `1` for original brightness. `0.1` by default.\n- `aa_color` \u2014 The color of anti-aliased pixels in the diff output in `[R, G, B]` format. `[255, 255, 0]` by default.\n- `diff_color` \u2014 The color of differing pixels in the diff output in `[R, G, B]` format. `[255, 0, 0]` by default.\n- `diff_mask` \u2014 Draw the diff over a transparent background (a mask), rather than over the original image. Will not draw anti-aliased pixels (if detected).\n- `fail_fast` - If true, will return after first different pixel.\n\nCompares two images, writes the output diff and returns the number of mismatched pixels.\n\n### contrib.PIL.pixelmatch\n\nCompares 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.\n\n## Example output\n\n| expected | actual | diff |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n|  |  |  |\n|  |  |  |\n|  |  |  |\n|  |  |  |\n\n## Changelog\n\n### v0.3.0\n\n- feat: add fail_fast option [#144](https://github.com/whtsky/pixelmatch-py/pull/144)\n### v0.2.4\n- type: fix typing issues\n- chore: test Python 3.10\n\n### v0.2.3\n\n- feat: make package comply with PEP-561\n\n### v0.2.2\n\n- typing: use `Sequence` instead of `List` for `RGBTuple`\n- build: switch to `poetry_core` [#81](https://github.com/whtsky/pixelmatch-py/pull/81)\n\n### v0.2.1\n\n- feat: add function to compare PIL.Image instances through contrib.PIL.pixelmatch [#42](https://github.com/whtsky/pixelmatch-py/pull/42)\n\n### v0.2.0\n\n- BREAKING CHANGE: remove `options` parameter [#38](https://github.com/whtsky/pixelmatch-py/pull/38)\n- docs: use absolute url for images in README\n\n### v0.1.1\n\n- fix: fix bug in fast path [#18](https://github.com/whtsky/pixelmatch-py/pull/18)\n\n### v0.1.0\n\n- Initial release\n\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "A pixel-level image comparison library.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/whtsky/pixelmatch-py",
"Repository": "https://github.com/whtsky/pixelmatch-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e109766e3cb038be997cef78a29cfd4ec5e9be739b8ea44a09c839a6da8cb55b",
"md5": "135c0b849ce7ac6fd4ec97351ef3deba",
"sha256": "1fe86c50e7d00eb4b4de7b991f8b7ebc12da841ce1e9f7304480ab0f58a2bd81"
},
"downloads": -1,
"filename": "pixelmatch-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "135c0b849ce7ac6fd4ec97351ef3deba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 9155,
"upload_time": "2022-03-23T14:51:33",
"upload_time_iso_8601": "2022-03-23T14:51:33.271493Z",
"url": "https://files.pythonhosted.org/packages/e1/09/766e3cb038be997cef78a29cfd4ec5e9be739b8ea44a09c839a6da8cb55b/pixelmatch-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c59ebc53e64156db78c75c6d7f535e3f80f62c8a8e1545783770f06f528e187",
"md5": "bcb2542e8326820e55232725976c79ff",
"sha256": "d0fa36a593cfcfa2d4b225da9d72c5b5218aef8b0594bc1a91953533c2676099"
},
"downloads": -1,
"filename": "pixelmatch-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "bcb2542e8326820e55232725976c79ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 9142,
"upload_time": "2022-03-23T14:51:35",
"upload_time_iso_8601": "2022-03-23T14:51:35.225311Z",
"url": "https://files.pythonhosted.org/packages/1c/59/ebc53e64156db78c75c6d7f535e3f80f62c8a8e1545783770f06f528e187/pixelmatch-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-03-23 14:51:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "whtsky",
"github_project": "pixelmatch-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pixelmatch"
}
JSON
