Repository: mapbox/pixelmatch
Branch: main
Commit: 14419e81cd24
Files: 12
Total size: 22.0 KB

Directory structure:
gitextract_4xzvlv5j/

├── .gitattributes
├── .github/
│   └── workflows/
│       └── node.yml
├── .gitignore
├── LICENSE
├── README.md
├── bench.js
├── bin/
│   └── pixelmatch
├── eslint.config.js
├── index.js
├── package.json
├── test/
│   └── test.js
└── tsconfig.json

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitattributes
================================================
# Set the default behavior, in case people don't have core.autocrlf set.
* text=auto

# Declare files that will always have LF line endings on checkout, so that it matches the configured eslint rules.
*.js text eol=lf
bin/pixelmatch text eol=lf

================================================
FILE: .github/workflows/node.yml
================================================
name: Node
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup Node
      uses: actions/setup-node@v4
      with:
        node-version: 20

    - name: Install dependencies
      run: npm install

    - name: Run tests
      run: npm test

    - name: Run the CLI tool
      run: node bin/pixelmatch test/fixtures/1a.png test/fixtures/1a.png


================================================
FILE: .gitignore
================================================
*.log
node_modules
.DS_Store
.nyc_output
coverage
tmp
index.d.ts


================================================
FILE: LICENSE
================================================
ISC License

Copyright (c) 2025, Mapbox

Permission to use, copy, modify, and/or distribute this software for any purpose
with or without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.


================================================
FILE: README.md
================================================
# pixelmatch

[![Node](https://github.com/mapbox/pixelmatch/actions/workflows/node.yml/badge.svg)](https://github.com/mapbox/pixelmatch/actions/workflows/node.yml)
[![](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects)

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](https://github.com/Huddle/Resemble.js)
and [Blink-diff](https://github.com/yahoo/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).

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

Implements ideas from the following papers:

- [Measuring perceived color difference using YIQ NTSC transmission color space in mobile applications](https://www.spiedigitallibrary.org/conference-proceedings-of-spie/8011/80119D/Simple-perceptual-color-space-for-color-specification-and-real-time/10.1117/12.901997.full) (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)

## [Demo](https://observablehq.com/@mourner/pixelmatch-demo)

## Example output

| expected | actual | diff |
| --- | --- | --- |
| ![](test/fixtures/4a.png) | ![](test/fixtures/4b.png) | ![1diff](test/fixtures/4diff.png) |
| ![](test/fixtures/3a.png) | ![](test/fixtures/3b.png) | ![1diff](test/fixtures/3diff.png) |
| ![](test/fixtures/6a.png) | ![](test/fixtures/6b.png) | ![1diff](test/fixtures/6diff.png) |

## 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:

```bash
pixelmatch image1.png image2.png output.png 0.1
```

## Example usage

### Node.js

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

```js
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:

```bash
npm install pixelmatch
```

Or use in the browser from a CDN:

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

## [Changelog](https://github.com/mapbox/pixelmatch/releases)


================================================
FILE: bench.js
================================================
import match from './index.js';
import {PNG} from 'pngjs';
import fs from 'fs';

const data = [1, 2, 3, 4, 5, 6, 7].map(i => [
    readImage(`${i}a`),
    readImage(`${i}b`)
]);

console.time('match');
let sum = 0;
for (let i = 0; i < 100; i++) {
    for (const [img1, img2] of data) {
        sum += match(img1.data, img2.data, null, img1.width, img1.height);
    }
}
console.timeEnd('match');
console.log(sum);

function readImage(name) {
    return PNG.sync.read(fs.readFileSync(new URL(`test/fixtures/${name}.png`, import.meta.url)));
}


================================================
FILE: bin/pixelmatch
================================================
#!/usr/bin/env node

import {PNG} from 'pngjs';
import fs from 'fs';
import match from '../index.js';

if (process.argv.length < 4) {
    console.log('Usage: pixelmatch image1.png image2.png [diff.png] [threshold] [includeAA]');
    process.exit(64);
}

const [,, img1Path, img2Path, diffPath, threshold, includeAA] = process.argv;
const options = {};
if (threshold !== undefined) options.threshold = +threshold;
if (includeAA !== undefined) options.includeAA = includeAA !== 'false';

const img1 = PNG.sync.read(fs.readFileSync(img1Path));
const img2 = PNG.sync.read(fs.readFileSync(img2Path));

const {width, height} = img1;

if (img2.width !== width || img2.height !== height) {
    console.log(`Image dimensions do not match: ${width}x${height} vs ${img2.width}x${img2.height}`);
    process.exit(65);
}

const diff = diffPath ? new PNG({width, height}) : null;

console.time('matched in');
const diffs = match(img1.data, img2.data, diff ? diff.data : null, width, height, options);
console.timeEnd('matched in');

console.log(`different pixels: ${diffs}`);
console.log(`error: ${Math.round(100 * 100 * diffs / (width * height)) / 100}%`);

if (diff) {
    fs.writeFileSync(diffPath, PNG.sync.write(diff));
}
process.exit(diffs ? 66 : 0);


================================================
FILE: eslint.config.js
================================================
import config from 'eslint-config-mourner';

export default [
    ...config,
    {
        files: ['*.js', 'test/test.js', 'bin/pixelmatch']
    }
];


================================================
FILE: index.js
================================================
/**
 * Compare two equally sized images, pixel by pixel.
 *
 * @param {Uint8Array | Uint8ClampedArray} img1 First image data.
 * @param {Uint8Array | Uint8ClampedArray} img2 Second image data.
 * @param {Uint8Array | Uint8ClampedArray | void} output Image data to write the diff to, if provided.
 * @param {number} width Input images width.
 * @param {number} height Input images height.
 *
 * @param {Object} [options]
 * @param {number} [options.threshold=0.1] Matching threshold (0 to 1); smaller is more sensitive.
 * @param {boolean} [options.includeAA=false] Whether to skip anti-aliasing detection.
 * @param {number} [options.alpha=0.1] Opacity of original image in diff output.
 * @param {[number, number, number]} [options.aaColor=[255, 255, 0]] Color of anti-aliased pixels in diff output.
 * @param {[number, number, number]} [options.diffColor=[255, 0, 0]] Color of different pixels in diff output.
 * @param {[number, number, number]} [options.diffColorAlt=options.diffColor] Whether to detect dark on light differences between img1 and img2 and set an alternative color to differentiate between the two.
 * @param {boolean} [options.diffMask=false] Draw the diff over a transparent background (a mask).
 *
 * @return {number} The number of mismatched pixels.
 */
export default function pixelmatch(img1, img2, output, width, height, options = {}) {
    const {
        threshold = 0.1,
        alpha = 0.1,
        aaColor = [255, 255, 0],
        diffColor = [255, 0, 0],
        includeAA, diffColorAlt, diffMask
    } = options;

    if (!isPixelData(img1) || !isPixelData(img2) || (output && !isPixelData(output)))
        throw new Error('Image data: Uint8Array, Uint8ClampedArray or Buffer expected.');

    if (img1.length !== img2.length || (output && output.length !== img1.length))
        throw new Error(`Image sizes do not match. Image 1 size: ${img1.length}, image 2 size: ${img2.length}`);

    if (img1.length !== width * height * 4) throw new Error(`Image data size does not match width/height. Expecting ${width * height * 4}. Got ${img1.length}`);

    // check if images are identical
    const len = width * height;
    const a32 = new Uint32Array(img1.buffer, img1.byteOffset, len);
    const b32 = new Uint32Array(img2.buffer, img2.byteOffset, len);
    let identical = true;

    for (let i = 0; i < len; i++) {
        if (a32[i] !== b32[i]) { identical = false; break; }
    }
    if (identical) { // fast path if identical
        if (output && !diffMask) {
            for (let i = 0; i < len; i++) drawGrayPixel(img1, 4 * i, alpha, output);
        }
        return 0;
    }

    // maximum acceptable square distance between two colors;
    // 35215 is the maximum possible value for the YIQ difference metric
    const maxDelta = 35215 * threshold * threshold;
    const [aaR, aaG, aaB] = aaColor;
    const [diffR, diffG, diffB] = diffColor;
    const [altR, altG, altB] = diffColorAlt || diffColor;
    let diff = 0;

    // compare each pixel of one image against the other one
    for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {

            const i = y * width + x;
            const pos = i * 4;

            // squared YUV distance between colors at this pixel position, negative if the img2 pixel is darker
            const delta = a32[i] === b32[i] ? 0 : colorDelta(img1, img2, pos, pos, false);

            // the color difference is above the threshold
            if (Math.abs(delta) > maxDelta) {
                // check it's a real rendering difference or just anti-aliasing
                const isExcludedAA = !includeAA && (antialiased(img1, x, y, width, height, a32, b32) || antialiased(img2, x, y, width, height, b32, a32));
                if (isExcludedAA) {
                    // one of the pixels is anti-aliasing; draw as yellow and do not count as difference
                    // note that we do not include such pixels in a mask
                    if (output && !diffMask) drawPixel(output, pos, aaR, aaG, aaB);

                } else {
                    // found substantial difference not caused by anti-aliasing; draw it as such
                    if (output) {
                        if (delta < 0) {
                            drawPixel(output, pos, altR, altG, altB);
                        } else {
                            drawPixel(output, pos, diffR, diffG, diffB);
                        }
                    }
                    diff++;
                }

            } else if (output && !diffMask) {
                // pixels are similar; draw background as grayscale image blended with white
                drawGrayPixel(img1, pos, alpha, output);
            }
        }
    }

    // return the number of different pixels
    return diff;
}

/** @param {Uint8Array | Uint8ClampedArray} arr */
function isPixelData(arr) {
    // work around instanceof Uint8Array not working properly in some Jest environments
    return ArrayBuffer.isView(arr) && arr.BYTES_PER_ELEMENT === 1;
}

/**
 * Check if a pixel is likely a part of anti-aliasing;
 * based on "Anti-aliased Pixel and Intensity Slope Detector" paper by V. Vysniauskas, 2009
 * @param {Uint8Array | Uint8ClampedArray} img
 * @param {number} x1
 * @param {number} y1
 * @param {number} width
 * @param {number} height
 * @param {Uint32Array} a32
 * @param {Uint32Array} b32
 */
function antialiased(img, x1, y1, width, height, a32, b32) {
    const x0 = Math.max(x1 - 1, 0);
    const y0 = Math.max(y1 - 1, 0);
    const x2 = Math.min(x1 + 1, width - 1);
    const y2 = Math.min(y1 + 1, height - 1);
    const pos = y1 * width + x1;
    let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;
    let min = 0;
    let max = 0;
    let minX = 0;
    let minY = 0;
    let maxX = 0;
    let maxY = 0;

    // go through 8 adjacent pixels
    for (let x = x0; x <= x2; x++) {
        for (let y = y0; y <= y2; y++) {
            if (x === x1 && y === y1) continue;

            // brightness delta between the center pixel and adjacent one
            const delta = colorDelta(img, img, pos * 4, (y * width + x) * 4, true);

            // count the number of equal, darker and brighter adjacent pixels
            if (delta === 0) {
                zeroes++;
                // if found more than 2 equal siblings, it's definitely not anti-aliasing
                if (zeroes > 2) return false;

            // remember the darkest pixel
            } else if (delta < min) {
                min = delta;
                minX = x;
                minY = y;

            // remember the brightest pixel
            } else if (delta > max) {
                max = delta;
                maxX = x;
                maxY = y;
            }
        }
    }

    // if there are no both darker and brighter pixels among siblings, it's not anti-aliasing
    if (min === 0 || max === 0) return false;

    // if either the darkest or the brightest pixel has 3+ equal siblings in both images
    // (definitely not anti-aliased), this pixel is anti-aliased
    return (hasManySiblings(a32, minX, minY, width, height) && hasManySiblings(b32, minX, minY, width, height)) ||
           (hasManySiblings(a32, maxX, maxY, width, height) && hasManySiblings(b32, maxX, maxY, width, height));
}

/**
 * Check if a pixel has 3+ adjacent pixels of the same color.
 * @param {Uint32Array} img
 * @param {number} x1
 * @param {number} y1
 * @param {number} width
 * @param {number} height
 */
function hasManySiblings(img, x1, y1, width, height) {
    const x0 = Math.max(x1 - 1, 0);
    const y0 = Math.max(y1 - 1, 0);
    const x2 = Math.min(x1 + 1, width - 1);
    const y2 = Math.min(y1 + 1, height - 1);
    const val = img[y1 * width + x1];
    let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;

    // go through 8 adjacent pixels
    for (let x = x0; x <= x2; x++) {
        for (let y = y0; y <= y2; y++) {
            if (x === x1 && y === y1) continue;
            zeroes += +(val === img[y * width + x]);
            if (zeroes > 2) return true;
        }
    }
    return false;
}

/**
 * Calculate color difference according to the paper "Measuring perceived color difference
 * using YIQ NTSC transmission color space in mobile applications" by Y. Kotsarenko and F. Ramos
 * @param {Uint8Array | Uint8ClampedArray} img1
 * @param {Uint8Array | Uint8ClampedArray} img2
 * @param {number} k
 * @param {number} m
 * @param {boolean} yOnly
 */
function colorDelta(img1, img2, k, m, yOnly) {
    const r1 = img1[k];
    const g1 = img1[k + 1];
    const b1 = img1[k + 2];
    const a1 = img1[k + 3];
    const r2 = img2[m];
    const g2 = img2[m + 1];
    const b2 = img2[m + 2];
    const a2 = img2[m + 3];

    let dr = r1 - r2;
    let dg = g1 - g2;
    let db = b1 - b2;
    const da = a1 - a2;

    if (!dr && !dg && !db && !da) return 0;

    if (a1 < 255 || a2 < 255) { // blend pixels with background
        const rb = 48 + 159 * (k % 2);
        const gb = 48 + 159 * ((k / 1.618033988749895 | 0) % 2);
        const bb = 48 + 159 * ((k / 2.618033988749895 | 0) % 2);
        dr = (r1 * a1 - r2 * a2 - rb * da) / 255;
        dg = (g1 * a1 - g2 * a2 - gb * da) / 255;
        db = (b1 * a1 - b2 * a2 - bb * da) / 255;
    }

    const y = dr * 0.29889531 + dg * 0.58662247 + db * 0.11448223;

    if (yOnly) return y; // brightness difference only

    const i = dr * 0.59597799 - dg * 0.27417610 - db * 0.32180189;
    const q = dr * 0.21147017 - dg * 0.52261711 + db * 0.31114694;

    const delta = 0.5053 * y * y + 0.299 * i * i + 0.1957 * q * q;

    // encode whether the pixel lightens or darkens in the sign
    return y > 0 ? -delta : delta;
}

/**
 * @param {Uint8Array | Uint8ClampedArray} output
 * @param {number} pos
 * @param {number} r
 * @param {number} g
 * @param {number} b
 */
function drawPixel(output, pos, r, g, b) {
    output[pos + 0] = r;
    output[pos + 1] = g;
    output[pos + 2] = b;
    output[pos + 3] = 255;
}

/**
 * @param {Uint8Array | Uint8ClampedArray} img
 * @param {number} i
 * @param {number} alpha
 * @param {Uint8Array | Uint8ClampedArray} output
 */
function drawGrayPixel(img, i, alpha, output) {
    const val = 255 + (img[i] * 0.29889531 + img[i + 1] * 0.58662247 + img[i + 2] * 0.11448223 - 255) * alpha * img[i + 3] / 255;
    drawPixel(output, i, val, val, val);
}


================================================
FILE: package.json
================================================
{
  "name": "pixelmatch",
  "version": "7.1.0",
  "type": "module",
  "description": "The smallest and fastest pixel-level image comparison library.",
  "main": "index.js",
  "types": "index.d.ts",
  "bin": {
    "pixelmatch": "bin/pixelmatch"
  },
  "files": [
    "bin/pixelmatch",
    "index.d.ts"
  ],
  "dependencies": {
    "pngjs": "^7.0.0"
  },
  "devDependencies": {
    "eslint": "^9.27.0",
    "eslint-config-mourner": "^4.0.2",
    "typescript": "^5.8.3"
  },
  "scripts": {
    "pretest": "eslint",
    "test": "tsc && node --test"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/mapbox/pixelmatch.git"
  },
  "keywords": [
    "image",
    "comparison",
    "diff"
  ],
  "author": "Volodymyr Agafonkin",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/mapbox/pixelmatch/issues"
  },
  "homepage": "https://github.com/mapbox/pixelmatch#readme"
}


================================================
FILE: test/test.js
================================================

import assert from 'node:assert/strict';
import test from 'node:test';
import fs from 'node:fs';

import {PNG} from 'pngjs';
import match from '../index.js';

const options = {threshold: 0.05};

diffTest('1a', '1b', '1diff', options, 143);
diffTest('1a', '1b', '1diffdefaultthreshold', {threshold: undefined}, 106);
diffTest('1a', '1b', '1diffmask', {threshold: 0.05, includeAA: false, diffMask: true}, 143);
diffTest('1a', '1a', '1emptydiffmask', {threshold: 0, diffMask: true}, 0);
diffTest('2a', '2b', '2diff', {
    threshold: 0.05,
    alpha: 0.5,
    aaColor: [0, 192, 0],
    diffColor: [255, 0, 255]
}, 12437);
diffTest('3a', '3b', '3diff', options, 212);
diffTest('4a', '4b', '4diff', options, 36049);
diffTest('5a', '5b', '5diff', options, 6);
diffTest('6a', '6b', '6diff', options, 51);
diffTest('6a', '6a', '6empty', {threshold: 0}, 0);
diffTest('7a', '7b', '7diff', {diffColorAlt: [0, 255, 0]}, 2448);
diffTest('8a', '5b', '8diff', options, 32896);

test('throws error if image sizes do not match', () => {
    assert.throws(() => match(new Uint8Array(8), new Uint8Array(9), null, 2, 1), 'Image sizes do not match');
});

test('throws error if image sizes do not match width and height', () => {
    assert.throws(() => match(new Uint8Array(9), new Uint8Array(9), null, 2, 1), 'Image data size does not match width/height');
});

test('throws error if provided wrong image data format', () => {
    const err = 'Image data: Uint8Array, Uint8ClampedArray or Buffer expected';
    const arr = new Uint8Array(4 * 20 * 20);
    const bad = new Array(arr.length).fill(0);
    assert.throws(() => match(bad, arr, null, 20, 20), err);
    assert.throws(() => match(arr, bad, null, 20, 20), err);
    assert.throws(() => match(arr, arr, bad, 20, 20), err);
});

function diffTest(imgPath1, imgPath2, diffPath, options, expectedMismatch) {
    const name = `comparing ${imgPath1} to ${imgPath2}, ${JSON.stringify(options)}`;

    test(name, () => {
        const img1 = readImage(imgPath1);
        const img2 = readImage(imgPath2);
        const {width, height} = img1;
        const diff = new PNG({width, height});

        const mismatch = match(img1.data, img2.data, diff.data, width, height, options);
        const mismatch2 = match(img1.data, img2.data, null, width, height, options);

        if (process.env.UPDATE) {
            writeImage(diffPath, diff);
        } else {
            const expectedDiff = readImage(diffPath);
            assert.ok(diff.data.equals(expectedDiff.data), 'diff image');
        }
        assert.equal(mismatch, expectedMismatch, 'number of mismatched pixels');
        assert.equal(mismatch, mismatch2, 'number of mismatched pixels without diff');
    });
}

function readImage(name) {
    return PNG.sync.read(fs.readFileSync(new URL(`fixtures/${name}.png`, import.meta.url)));
}
function writeImage(name, image) {
    fs.writeFileSync(new URL(`fixtures/${name}.png`, import.meta.url), PNG.sync.write(image));
}


================================================
FILE: tsconfig.json
================================================
{
    "compilerOptions": {
        "allowJs": true,
        "checkJs": true,
        "strict": true,
        "emitDeclarationOnly": true,
        "declaration": true,
        "target": "es2017",
        "module": "nodenext",
        "moduleResolution": "nodenext"
    },
    "files": [
        "index.js"
    ]
}