@blazediff/core

High-performance pixel-by-pixel image comparison library. 1.5x faster than pixelmatch while maintaining identical accuracy.

View Detailed Benchmarks

Installation


npm install @blazediff/core


pnpm add @blazediff/core


yarn add @blazediff/core


bun add @blazediff/core

Features

1.5x faster than pixelmatch on average, 88% faster on identical images
pixelmatch 8 adapter: @blazediff/core/pixelmatch is a drop-in replacement
Zero dependencies

API Reference

`diff(a, b, options?)`

Compares two RGBA images pixel by pixel. a and b are { data, width, height }, and browser ImageData fits as is. The same call, options and result exist in @blazediff/core-wasm and @blazediff/core-native.


import { diff } from "@blazediff/core";
 
const output = { data: new Uint8Array(width * height * 4), width, height };
const result = diff(a, b, { output });
 
if (result.kind === "compared" && !result.identical) {
  console.log(result.count, result.percentage);
}

Options

Option	Type	Default	Description
`threshold`	`number`	`0.1`	Matching threshold (0-1). Lower is stricter
`antialiasing`	`boolean`	`true`	Detect anti-aliased pixels and leave them out of the count
`metric`	`"yiq" \| "oklab"`	`"yiq"`	Color metric. `"oklab"` is the metric of pixelmatch 8
`mask`	`Uint8Array`	-	One byte per pixel (width × height). Non-zero pixels are skipped
`window`	`number`	-	Also report the N×N window with the most diff pixels
`output`	`Image`	-	Draw the diff here. Omit for a count-only comparison
`render.alpha`	`number`	`0.1`	Opacity of the original image in the output
`render.diffColor`	`[R,G,B]`	`[255,0,0]`	Color of different pixels
`render.diffColorAlt`	`[R,G,B]`	`diffColor`	Color of pixels that get darker in `b`
`render.aaColor`	`[R,G,B]`	`[255,255,0]`	Color of anti-aliased pixels
`render.background`	`"faded" \| "transparent"`	`"faded"`	`transparent` draws the diff without the gray copy of `a`

Result

Kind	Fields
`compared`	`count`, `percentage`, `identical`, and `window: { x, y, count }` when the `window` option is set
`dimension-mismatch`	`a` and `b`, each `{ width, height }`

Invalid buffers or options throw a BlazeDiffError with a code: invalid-image, invalid-output, invalid-mask or invalid-option.

`pixelmatch(img1, img2, output, width, height, options?)`

import pixelmatch from "@blazediff/core/pixelmatch" has the same signature, options, errors, counts and output bytes as pixelmatch 8.0.0, so you change the import and nothing else.

Threshold Guidelines: - 0.0 - Exact match only - 0.05 - Strict comparison - 0.1 - Default balanced comparison - 0.2 - Lenient comparison