Pixelmatch

https://github.com/whtsky/pixelmatch-py
Admin
Pixelmatch is a fast pixel-level image comparison library with anti-aliased pixel detection and...
Tokens:5,546
Snippets:36
Trust Score:9.6
License:ISC
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pixelmatch-py

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

Install the library using pip. This command is used to add the pixelmatch package to your Python environment.

```bash
python -m pip install pixelmatch
```

--------------------------------

### Install pixelmatch using pip

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Install the pixelmatch library from PyPI using pip. This is the standard method for adding the library to your Python environment.

```bash
pip install pixelmatch
```

--------------------------------

### Compare PIL.Image Instances

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

Compares two PIL.Image objects and saves the difference to a new image file. Ensure PIL is installed and images are loaded correctly. Anti-aliased pixels are included in the 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")
```

--------------------------------

### Basic pixelmatch Usage

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

A basic example of using the pixelmatch function with raw image data, specifying dimensions and a threshold for comparison.

```python
from pixelmatch import pixelmatch

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

--------------------------------

### Pytest Visual Regression Test Setup

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Set up a Pytest fixture for visual regression testing by defining snapshot directory, comparison threshold, and maximum allowed differing pixels. This function compares actual screenshots against stored baselines.

```python
import pytest
from pathlib import Path
from PIL import Image
from pixelmatch.contrib.PIL import pixelmatch

SNAPSHOTS_DIR = Path("tests/snapshots")
THRESHOLD = 0.05
MAX_DIFF_PIXELS = 0  # zero tolerance for differences

def compare_screenshot(actual: Image.Image, snapshot_name: str) -> int:
    """
    Compare actual screenshot against stored baseline.
    Saves a diff image on failure for visual inspection.
    """
    baseline_path = SNAPSHOTS_DIR / f"{snapshot_name}.png"

    # First run: save baseline if it doesn't exist
    if not baseline_path.exists():
        actual.save(baseline_path)
        return 0

    baseline = Image.open(baseline_path)
    diff = Image.new("RGBA", actual.size)
    mismatch = pixelmatch(actual, baseline, diff, threshold=THRESHOLD)

    if mismatch > MAX_DIFF_PIXELS:
        diff.save(SNAPSHOTS_DIR / f"{snapshot_name}_diff.png")

    return mismatch
```

--------------------------------

### Compare PIL Images with pixelmatch.contrib.PIL

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Compares PIL.Image objects directly, handling RGBA conversion internally. An output PIL.Image can be provided to visualize differences. Supports custom options for sensitivity and color highlighting.

```python
from PIL import Image
from pixelmatch.contrib.PIL import pixelmatch

# Open images from disk
img_a = Image.open("screenshot_before.png")
img_b = Image.open("screenshot_after.png")

# Create an output diff image of the same size
img_diff = Image.new("RGBA", img_a.size)

# Basic comparison
mismatch = pixelmatch(img_a, img_b, img_diff)
print(f"Mismatched pixels: {mismatch}")

# Save the visual diff
img_diff.save("diff.png")

# With custom options: more sensitive threshold, custom colors
img_diff2 = Image.new("RGBA", img_a.size)
mismatch = pixelmatch(
    img_a, img_b, img_diff2,
    threshold=0.05,
    includeAA=False,
    alpha=0.5,
    aa_color=(0, 192, 0),      # green for anti-aliased pixels
    diff_color=(255, 0, 255),  # magenta for differing pixels
    diff_mask=False,
)
img_diff2.save("diff_custom.png")

# Diff mask: transparent background, only show changed pixels
img_mask = Image.new("RGBA", img_a.size)
mismatch = pixelmatch(img_a, img_b, img_mask, diff_mask=True)
img_mask.save("diff_mask.png")

# No output image — just count mismatches
mismatch_count = pixelmatch(img_a, img_b)
print(f"Total differences: {mismatch_count}")

# Fail-fast: stop at first difference (useful for quick existence check)
has_diff = pixelmatch(img_a, img_b, fail_fast=True)
print(f"Images differ: {has_diff == 1}")  # Images differ: True

# Identical images: always returns 0
assert pixelmatch(img_a, img_a) == 0

```

--------------------------------

### Compare Raw RGBA Image Data with pixelmatch

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Compares two images represented as flat RGBA byte sequences. Requires image dimensions and an output buffer for differences. Customize comparison with options like threshold, anti-aliasing, and diff colors.

```python
from pixelmatch import pixelmatch

# Images are flat lists of RGBA values: [R, G, B, A, R, G, B, A, ...]
width, height = 4, 2

# 4x2 image: solid red
img1 = [
    255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,
    255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,
]

# 4x2 image: one pixel changed to blue at position (1,0)
img2 = [
    255, 0, 0, 255,  0, 0, 255, 255,  255, 0, 0, 255,  255, 0, 0, 255,
    255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,  255, 0, 0, 255,
]

# Output buffer (same size as input images)
diff = [0] * len(img1)

# Basic comparison with default threshold (0.1)
num_diff = pixelmatch(img1, img2, width, height, diff)
print(f"Different pixels: {num_diff}")  # Different pixels: 1

# With custom options
num_diff = pixelmatch(
    img1, img2, width, height, diff,
    threshold=0.05,        # more sensitive
    includeAA=False,       # detect and ignore anti-aliased pixels (default)
    alpha=0.1,             # unchanged pixels shown at 10% opacity in diff
    aa_color=(255, 255, 0),  # anti-aliased pixels shown in yellow
    diff_color=(255, 0, 0),  # differing pixels shown in red
    diff_mask=False,       # draw diff over faded original (not transparent mask)
    fail_fast=False,       # count all differences (don't stop at first)
)
print(f"Different pixels: {num_diff}")  # Different pixels: 1

# fail_fast mode: returns 1 immediately on first detected difference
result = pixelmatch(img1, img2, width, height, fail_fast=True)
print(f"Has differences: {result == 1}")  # Has differences: True

# diff_mask mode: only differing pixels drawn, background is transparent
diff_mask_buf = [0] * len(img1)
pixelmatch(img1, img2, width, height, diff_mask_buf, diff_mask=True)

```

--------------------------------

### Pytest Test Case for Homepage Visual Regression

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Implement a Pytest test case to capture the homepage screenshot, compare it against the baseline using `compare_screenshot`, and assert that there are no visual differences.

```python
def test_homepage_visual_regression(browser_page):
    screenshot = browser_page.screenshot()  # returns PIL.Image
    mismatch = compare_screenshot(screenshot, "homepage")
    assert mismatch == 0, f"Visual regression: {mismatch} pixels differ"
```

--------------------------------

### Compare Raw Image Data

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

Compares raw RGBA image data arrays. Requires image dimensions to be specified. The difference is written to a provided data array.

```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)
```

--------------------------------

### pixelmatch (Raw Image Data)

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

Compares two raw RGBA image data arrays, writes the diff to an output array, and returns the number of mismatched pixels. Supports various options for customization.

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

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

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **img1** (array) - RGBA Image data of the first image.
- **img2** (array) - RGBA Image data of the second image. Note: image dimensions must be equal.
- **width** (int) - Width of the images.
- **height** (int) - Height of the images.
- **output** (array) - 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** (float) - Optional. Matching threshold, ranges from `0` to `1`. Smaller values make the comparison more sensitive. `0.1` by default.
- **includeAA** (bool) - Optional. If `true`, disables detecting and ignoring anti-aliased pixels. `false` by default.
- **alpha** (float) - Optional. 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** (list) - Optional. The color of anti-aliased pixels in the diff output in `[R, G, B]` format. `[255, 255, 0]` by default.
- **diff_color** (list) - Optional. The color of differing pixels in the diff output in `[R, G, B]` format. `[255, 0, 0]` by default.
- **diff_mask** (bool) - Optional. 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** (bool) - Optional. If true, will return after first different pixel.

### Request Example
```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)
```

### Response
#### Success Response (200)
- **mismatch** (int) - The number of mismatched pixels.
```

--------------------------------

### contrib.PIL.pixelmatch (PIL.Image Instances)

Source: https://github.com/whtsky/pixelmatch-py/blob/master/README.md

Compares two PIL.Image instances, writes the diff to a PIL.Image instance, and returns the number of mismatched pixels. This function has the same API as the raw image data version but handles PIL.Image objects directly.

```APIDOC
## contrib.PIL.pixelmatch(img1, img2, output, includeAA)

### Description
Compares two PIL.Image instances, 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.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **img1** (PIL.Image.Image) - The first PIL.Image instance to compare.
- **img2** (PIL.Image.Image) - The second PIL.Image instance to compare. Note: image dimensions must be equal.
- **output** (PIL.Image.Image) - PIL.Image instance to write the diff to. Note that _all three images_ need to have the same dimensions.
- **includeAA** (bool) - Optional. If `true`, disables detecting and ignoring anti-aliased pixels. `false` by default.

### Request Example
```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")
```

### Response
#### Success Response (200)
- **mismatch** (int) - The number of mismatched pixels.
```

--------------------------------

### pixelmatch.contrib.PIL.pixelmatch — PIL.Image Comparison

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Compares two `PIL.Image` instances directly without manually managing raw pixel data. It automatically converts images to RGBA internally. The `output` image (if provided) must be a pre-created RGBA `PIL.Image` of the same size. Width and height do not need to be specified.

```APIDOC
## pixelmatch.contrib.PIL.pixelmatch

### Description
Compares two `PIL.Image` instances directly without manually managing raw pixel data. Automatically converts images to RGBA internally. The `output` image (if provided) must be a pre-created RGBA `PIL.Image` of the same size. Width and height do not need to be specified.

### Parameters
- **img1** (PIL.Image.Image) - Required - The first image object.
- **img2** (PIL.Image.Image) - Required - The second image object.
- **output** (PIL.Image.Image, optional) - An RGBA `PIL.Image` object of the same size to draw the diff onto. If not provided, only the mismatch count is returned.
- **threshold** (float, optional) - Sensitivity threshold for pixel difference (0.0 to 1.0). Defaults to 0.1.
- **includeAA** (bool, optional) - Whether to detect and ignore anti-aliased pixels. Defaults to True.
- **alpha** (float, optional) - Opacity of unchanged pixels in the diff image (0.0 to 1.0). Defaults to 0.1.
- **aa_color** (tuple[int, int, int], optional) - Color to use for anti-aliased pixels in the diff image. Defaults to (255, 255, 0).
- **diff_color** (tuple[int, int, int], optional) - Color to use for differing pixels in the diff image. Defaults to (255, 0, 0).
- **diff_mask** (bool, optional) - If True, only differing pixels are drawn, with a transparent background. Defaults to False.
- **fail_fast** (bool, optional) - If True, the function returns immediately upon finding the first difference. Defaults to False.

### Return Value
- (int) - The count of mismatched pixels. If `output` is not provided and `fail_fast` is False, returns the total mismatch count. If `fail_fast` is True, returns 1 if any difference is found, 0 otherwise.
```

--------------------------------

### Pytest Test Case for Button Hover State Visual Regression

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Implement a Pytest test case to test the visual regression of a button's hover state. It captures a screenshot after hovering, compares it, and asserts that the number of differing pixels is within an acceptable tolerance.

```python
def test_button_hover_state(browser_page):
    browser_page.hover("#submit-btn")
    screenshot = browser_page.screenshot()
    mismatch = compare_screenshot(screenshot, "button_hover")
    assert mismatch <= 10, f"Too many differing pixels: {mismatch}"
```

--------------------------------

### Handle PIL API Output Size Mismatch Errors

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Catch ValueError when using the PIL-based pixelmatch API if the output image size does not match the input image sizes. Ensure the diff image has the same dimensions as the input images.

```python
# PIL API: output must be same size as inputs
img_a = Image.open("a.png")  # e.g. 800x600
img_b = Image.open("b.png")  # e.g. 800x600
wrong_output = Image.new("RGBA", (100, 100))  # wrong size

try:
    pil_pixelmatch(img_a, img_b, wrong_output)
except ValueError as e:
    print(f"Error: {e}")
```

--------------------------------

### pixelmatch.pixelmatch — Raw RGBA Image Comparison

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Compares two images provided as flat 1D sequences of RGBA values. It returns the count of differing pixels and can optionally write a diff image to an output buffer. All three images (img1, img2, output) must have the same dimensions.

```APIDOC
## pixelmatch.pixelmatch

### Description
Compares two images provided as flat 1D sequences of RGBA values (`[R, G, B, A, R, G, B, A, ...]`). Returns the count of differing pixels and optionally writes a diff image to an output buffer. All three images (img1, img2, output) must have the same dimensions.

### Parameters
- **img1** (list[int]) - Required - Flat RGBA byte sequence for the first image.
- **img2** (list[int]) - Required - Flat RGBA byte sequence for the second image.
- **width** (int) - Required - Width of the images.
- **height** (int) - Required - Height of the images.
- **diff** (list[int], optional) - Buffer to write the diff image to. Must be the same size as input images.
- **threshold** (float, optional) - Sensitivity threshold for pixel difference (0.0 to 1.0). Defaults to 0.1.
- **includeAA** (bool, optional) - Whether to detect and ignore anti-aliased pixels. Defaults to True.
- **alpha** (float, optional) - Opacity of unchanged pixels in the diff image (0.0 to 1.0). Defaults to 0.1.
- **aa_color** (tuple[int, int, int], optional) - Color to use for anti-aliased pixels in the diff image. Defaults to (255, 255, 0).
- **diff_color** (tuple[int, int, int], optional) - Color to use for differing pixels in the diff image. Defaults to (255, 0, 0).
- **diff_mask** (bool, optional) - If True, only differing pixels are drawn, with a transparent background. Defaults to False.
- **fail_fast** (bool, optional) - If True, the function returns immediately upon finding the first difference. Defaults to False.

### Return Value
- (int) - The count of differing pixels. If `fail_fast` is True, returns 1 if any difference is found, 0 otherwise.
```

--------------------------------

### Handle Raw API Image Data Size Errors

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Catch ValueError when using the raw pixelmatch API if image data length does not match the specified width and height. Verify data integrity and dimensions.

```python
# Raw API: width/height inconsistent with data length raises ValueError
img1 = [255, 0, 0, 255] * 8   # 32 bytes
img2 = [0, 0, 255, 255] * 8
try:
    pixelmatch(img1, img2, 10, 10)  # 10*10*4 = 400, but len=32
except ValueError as e:
    print(f"Error: {e}")  # Error: ('Image data size does not match width/height.', 32, 400)
```

--------------------------------

### Handle Raw API Image Size Mismatch Errors

Source: https://context7.com/whtsky/pixelmatch-py/llms.txt

Catch ValueError when using the raw pixelmatch API if input images have different dimensions. Ensure images are pre-processed to match sizes.

```python
from pixelmatch import pixelmatch
from pixelmatch.contrib.PIL import pixelmatch as pil_pixelmatch
from PIL import Image

# Raw API: size mismatch raises ValueError
img1 = [255, 0, 0, 255] * 4   # 1x4 image (16 bytes)
img2 = [0, 0, 255, 255] * 6   # different size (24 bytes)

try:
    pixelmatch(img1, img2, 4, 1)
except ValueError as e:
    print(f"Error: {e}")  # Error: ('Image sizes do not match.', 16, 24)
```
Tokens:
Raw