pixelmatch

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

Features accurate anti-aliased pixels detection and perceptual color difference metrics. Inspired by Resemble.js and Blink-diff. Unlike these libraries, pixelmatch is just a few hundred lines of code, has no dependencies, and works on raw typed arrays of image data, so it's very fast and can be used in both Node and browsers.

const numDiffPixels = pixelmatch(img1, img2, diff, 800, 600, {threshold: 0.1});

Implements ideas from the following papers:

• A perceptual color space for image processing (2020, Björn Ottosson) — the OKLab color space used for color difference.
• Distance metrics for very large color differences (2019, Saeideh Abasi et al.) — the OKLab HyAB metric used to compare colors.
• Anti-aliased pixel and intensity slope detector (2009, Vytautas Vyšniauskas)

Demo

Example output

| expected | actual | diff | | --- | --- | --- | | | | | | | | | | | | |

API

pixelmatch(img1, img2, output, width, height[, options])

• img1, img2 — Image data of the images to compare (Buffer, Uint8Array or Uint8ClampedArray). Note: image dimensions must be equal.
• output — Image data to write the diff to, or null if don't need a diff image.
• width, height — Width and height of the images. Note that all three images need to have the same dimensions.

options is an object literal with the following properties:

• threshold — How different two colors must be for a pixel to count as mismatched, from 0 to 1. It's a per-pixel perceptual color difference, where 1 is the difference between black and white, not a share of the image; to allow some percentage of the image to differ, compare the returned count against width * height instead. 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.
• aaColor — The color of anti-aliased pixels in the diff output in [R, G, B] format. [255, 255, 0] by default.
• diffColor — The color of differing pixels in the diff output in [R, G, B] format. [255, 0, 0] by default.
• diffColorAlt — An alternative color to use for dark on light differences to differentiate between "added" and "removed" parts. If not provided, all differing pixels use the color specified by diffColor. null by default.
• diffMask — Draw the diff over a transparent background (a mask), rather than over the original image. Will not draw anti-aliased pixels (if detected).
• checkerboard — Blend semi-transparent pixels against a checkerboard pattern when comparing (true) rather than plain white (false), avoiding false matches between colors that only look alike over one background. true by default.
• windowSize — If set to a finite number N, return the maximum number of differing pixels in any N×N sliding window instead of the total count (see below). Infinity by default.
• ignoreMask — A Uint8Array, Uint8ClampedArray or Buffer with one value per pixel (width * height long); pixels with a non-zero value are excluded from the comparison and drawn as unchanged in the diff output. Not set by default.

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

Windowed diff counts

Normally the return value is the total number of differing pixels. With windowSize: N you get the highest number of diff pixels in any N×N square instead. Anti-aliased pixels are only included if includeAA is true.

This helps with noise. GPU dithering and sub-pixel anti-aliasing scatter stray pixels all over the image, so they never fill up one small square, while a real regression usually changes a compact area.

Compare the result against a pixel count: that number is how big a difference you let through, and N is how closely packed it has to be.

if (pixelmatch(img1, img2, null, width, height, {windowSize: 16}) > 28) throw new Error('changed');

N never exceeds either image dimension, so on a 10×2 image windowSize: 32 gives you a 2×2 window. The default Infinity makes the window the whole image, which is the total count.

Command line

Pixelmatch comes with a binary that works with PNG images:

pixelmatch image1.png image2.png output.png 0.1

Example usage

Node.js

import fs from 'fs';
import {PNG} from 'pngjs';
import pixelmatch from 'pixelmatch';

const img1 = PNG.sync.read(fs.readFileSync('img1.png'));
const img2 = PNG.sync.read(fs.readFileSync('img2.png'));
const {width, height} = img1;
const diff = new PNG({width, height});

pixelmatch(img1.data, img2.data, diff.data, width, height, {threshold: 0.1});

fs.writeFileSync('diff.png', PNG.sync.write(diff));

Browsers

const img1 = img1Context.getImageData(0, 0, width, height);
const img2 = img2Context.getImageData(0, 0, width, height);
const diff = diffContext.createImageData(width, height);

pixelmatch(img1.data, img2.data, diff.data, width, height, {threshold: 0.1});

diffContext.putImageData(diff, 0, 0);

Install

Install with NPM:

npm install pixelmatch

Or use in the browser from a CDN:

<script type="module">
	import pixelmatch from 'https://esm.run/pixelmatch';

Changelog