What is pixelmatch?
The pixelmatch npm package is a high-performance, zero-dependency library for comparing two images. It is primarily used to find differences between images in terms of pixels, making it highly useful for tasks such as visual regression testing, automated testing of graphics or rendering engines, and anywhere else where image differences need to be quantified programmatically.
What are pixelmatch's main functionalities?
Image comparison
This feature allows you to compare two images and find the number of pixels that differ between them. The `img1` and `img2` parameters are the image data of the two images to compare, `diff` is a Uint8Array or Uint8ClampedArray to store the diff output, `width` and `height` specify the dimensions of the images, and the `threshold` option in the options object allows you to specify the sensitivity of the comparison.
const numDiffPixels = pixelmatch(img1, img2, diff, width, height, {threshold: 0.1});
Customizable comparison
Beyond basic image comparison, pixelmatch allows for customization of the comparison process. The `includeAA` option, for example, can be set to false to exclude anti-aliased pixels from being considered as differences. This is useful for comparing images where anti-aliasing may vary but is not considered a significant difference.
const numDiffPixels = pixelmatch(img1, img2, diff, width, height, {threshold: 0.1, includeAA: false});
Other packages similar to pixelmatch
resemblejs
Resemble.js is a package similar to pixelmatch that analyzes and compares images with a focus on visual differences. It provides more detailed analysis options, such as the ability to ignore colors or to get a percentage of image similarity. However, it might be heavier in terms of dependencies compared to the lightweight nature of pixelmatch.
looks-same
Looks-same is another npm package that offers image comparison capabilities. It focuses on flexibility, offering features like tolerance to color and antialiasing differences. Compared to pixelmatch, looks-same provides a higher-level API that might be more accessible to some users, but potentially at the cost of lower-level control and performance.
pixelmatch
![](https://img.shields.io/badge/simply-awesome-brightgreen.svg)
The smallest, simplest and fastest 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 around 150 lines of code,
has no dependencies, and works on raw typed arrays of image data,
so it's blazing fast and can be used in any environment (Node or browsers).
const numDiffPixels = pixelmatch(img1, img2, diff, 800, 600, {threshold: 0.1});
Implements ideas from the following papers:
Example output
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
— 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.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).
Compares two images, writes the output diff and returns the number of mismatched pixels.
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
const fs = require('fs');
const PNG = require('pngjs').PNG;
const pixelmatch = require('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
Use in the browser from a CDN:
<script src="https://bundle.run/pixelmatch"></script>