Screenshot comparison in a single pass, written in Rust, for Node.js.
Two images go in. Out come a score, the mask of the pixels that differ, a fingerprint that is the same for diffs that look alike, and a report of the content that moved rather than changed.
It replaces a pipeline of three tools — sharp to pad the images to a common
size, odiff run twice at two thresholds, and @argos-ci/mask-fingerprint on
the mask one of the two runs wrote — that decoded each screenshot at least
twice and the mask twice more. Here each image is decoded once, on its own thread; every
threshold is evaluated in the same scan; anti-aliasing is decided once per
pixel; and the fingerprint is computed from the mask in memory.
import { diff } from "@argos-ci/iris";
const result = await diff("base.png", "head.png", { output: "mask.png" });
result.score; // 0.0421 — share of the image that differs, 0 when nothing does
result.fingerprint; // "v1:g16:d1:t0.002,0.02,0.08:ccb73aa8a5d0317b"
result.mask; // { path, sha256, byteLength, bounds: { x, y, width, height } }
result.shift; // { segments: [{ baseY: 90, headY: 120, height: 270, dy: 30, … }], … }A comparison is made of tiers: a colour threshold, and how much of the image has to be over it before the tier reports anything. The two built-in tiers are the ones Argos uses:
| tier | colour threshold | reports when | catches |
|---|---|---|---|
| tolerant | 0.15 | 20 pixels differ (0.02% on small images) | a changed icon, a moved border |
| sensitive | 0.0225 | 3% of the image differs | a tint, a shadow, a faded text |
threshold (0 to 1, default 0.5) scales both; tiers replaces them. The
pixels over a high threshold are a subset of those over a low one, so one
counter per pixel describes every tier and the image is read once whatever
their number. The result carries what each tier saw, and the mask of the one
that reports the most.
Two detectors, chosen with antialiasing:
"classic"(default) is the detector of pixelmatch and odiff: a pixel is anti-aliasing when it is brighter than one neighbour and darker than another, and one of the two sits in a flat area. Its masks are identical to odiff 4.5.0's, pixel for pixel, which keeps existing fingerprints valid."subpixel"asks a different question: could both images be the same shape, rendered less than a pixel apart? Along each axis through the pixel it looks for two pixels that did not change, then requires what lies between them to be either one edge whose position moved by at most 0.6 px, or one thin stroke that kept its ink and its centre.
What that changes, each line being a test in
tests/antialiasing.rs:
| classic | subpixel | |
|---|---|---|
| an edge blended differently | noise | noise |
| an edge over a gradient, a photo, a dithered fill | reported | noise |
| a hairline snapped to another pixel (font hinting) | reported | noise |
| a hairline a little lighter | reported | noise |
| a recoloured shape: its blended edge pixels | ignored | reported |
| an anti-aliased edge moved by a whole pixel | ignored | reported |
| a red pixel on a black and white edge | ignored | reported |
| a hard edge or a hairline moved by a pixel | reported | reported |
| a new hairline, a bolder stroke | reported | reported |
On the screenshot fixtures, differing pixels left at the sensitive tier
(cargo run --release -p iris --example antialiasing):
| nothing changed but the rendering | none | classic | subpixel |
|---|---|---|---|
fontAliasing |
1,803 | 575 | 432 |
imageCompression4 |
1,416 | 1,275 | 228 |
imageCompression5 |
21,295 | 21,203 | 3,345 |
imageCompression7 |
42,365 | 42,306 | 5,314 |
| something changed | none | classic | subpixel |
|---|---|---|---|
simple |
499,332 | 489,927 | 497,624 |
big-images |
3,809,477 | 3,618,183 | 3,809,398 |
Switching detector changes masks, and with them the fingerprints of diffs that involve anti-aliasing: ignore rules recorded against the old fingerprints stop matching those diffs.
The mask is dilated by a pixel, cropped to its bounding box, centred in a
square, reduced to a 16×16 grid of fill levels, and hashed. Position and scale
drop out. The format is v1 of @argos-ci/mask-fingerprint and the values
are identical bit for bit — including the three places where the original,
which streams a PNG row by row, departs from a textbook dilation. They are
written down in fingerprint.rs and
checked against a copy of the original on every mask up to 4×4 and thousands
of random ones.
fingerprintDiff(png) fingerprints a stored mask, as the old package does,
truncated files included.
When an element grows by twenty pixels, everything below it moves and the diff
lights up the whole page. result.shift says how much of the diff is that:
{
// Blocks of rows found elsewhere: `dy` rows down, `dx` columns right.
segments: [
{ x: 0, width: 200, baseY: 90, headY: 120, height: 270, dy: 30, dx: 0 },
],
// What is new, and what is gone, once movement is set aside.
inserted: [{ x: 0, y: 90, width: 200, height: 30 }],
removed: [],
// Areas of the mask that differ only because content moved, none
// overlapping another: leave them out and what is left is what changed.
hidden: [{ x: 0, y: 120, width: 200, height: 270 }],
// Pixels of the mask in `hidden`.
shiftedPixels: 20537,
}Rows are compared within the columns that differ, so a sidebar that stayed put does not stop the page next to it from matching. Only distances whole rows were found to have moved by, pixel for pixel, are tried, and only where rows of content show it: a shift is never invented. Background between a card's borders fits anywhere and proves nothing, and a copy of content that is still where it was is new, not moved.
From there, a row counts as moved when none of its pixels would be in the mask. Browsers lay content out at fractional positions and render it anew where it lands: a block that moves by 23.5 pixels ends up partly 23 and partly 24 pixels down, its gradients dithered and its edges anti-aliased afresh. Exact matching cut such a block into dozens of pieces and lost the rows that no longer matched at all; it is now one block.
Content that slid sideways is found too: rows are hashed a second time without the background on either side, so a card that moved eight columns left when its neighbour narrowed hashes the same, and where its content starts says by how much. Glyphs drawn at another fraction of a column blend their edges differently; on edges, and only there, they are compared at the tolerant tier's threshold.
Where rows across a strip match nowhere, its columns may have moved apart: in a row of cards, the one that grew pushes its own button down and the section below the cards, not the cards beside it. The strip is then cut down the gutters of the head image, the uniform columns between cards, and each column is looked at on its own.
Background that grew or shrank is more of what is next to it: the rows a card gains or loses when its content moves are movement too, not a change. A new line of text, or a bar of another colour, differs from the rows around it and still shows.
cargo run --release -p iris --example shifts -- DIR reports, for pairs of
NAME.base.png and NAME.head.png in DIR, how much of each diff movement
explains.
diff(base, head, options?): Promise<DiffResult>
fingerprintDiff(png): Promise<string>base, head and png are file paths or buffers. PNG, JPEG and WebP are
decoded, told apart by their signature.
| option | default | |
|---|---|---|
threshold |
0.5 |
sensitivity, 0 (strict) to 1; scales the built-in tiers |
tiers |
{ threshold, minScore?, maxIgnoredPixels? }[], up to 8 |
|
antialiasing |
"classic" |
"classic", "subpixel", or false |
exactScore |
false |
see below |
fingerprint |
true |
|
shifts |
true |
|
minShiftRows |
4 |
fewest rows of content that must move together |
maxPixels |
reject canvases over this size, before decoding | |
threads |
up to 4 | for the scan, above a megapixel; the result does not depend on it |
output |
write the mask there instead of returning it in mask.data |
The mask is a 1-bit PNG, opaque red on transparent, the size of the larger
width and the larger height. mask.sha256 is the hash of the file.
Each call runs on a thread of its own, not on libuv's thread pool: the pool has four threads, and the rest of the process needs them for file system calls, DNS lookups and crypto while a comparison runs.
Argos has always read its scores from the odiff command line, which prints a
percentage with two decimals. A change under 0.005% of the image therefore
scored zero and was never reported: on a 1920×1080 screenshot that is 103
pixels, where the tolerant tier is meant to stop at 20. The minorChange2
fixture — 42 differing pixels, expected verdict "no change" — only passes
because of it.
By default the library rounds the same way, so that swapping it in changes no
verdict. exactScore: true turns the rounding off: the tiers then mean what
they say, and changes that were silently dropped are reported.
Same verdict, same score and same fingerprint on every fixture at four
sensitivities, as PNG and re-encoded as baseline, 4:4:4, progressive and grey
JPEG and lossy and lossless WebP, checked against the real odiff-bin, sharp
and @argos-ci/mask-fingerprint in __test__.
Lossy formats are where that takes care. A JPEG decoder rounds its inverse
DCT and colour conversion its own way, and a different one moves pixels
across a threshold: with zune-jpeg, a progressive JPEG of the tableAlpha
fixture scored 328,731 differing pixels where odiff found 60,823. So JPEG and
WebP go through the libraries odiff 4.5.0 links — libjpeg-turbo through its
TurboJPEG API, with the fast IDCT unless the threshold is 0, and libwebp —
called the way odiff calls them, built from vendored sources with their SIMD
code.
Three things differ on purpose:
- An image smaller both ways is not rescaled.
sharp'sfit: "contain"scaled such an image up before padding it, so the same content at twice the size read as a large difference. Images are now padded, never scaled. - Oversized pairs are compared in full. Over 80 megapixels the old code
capped the width, padded one image and not the other, and let odiff count
what stuck out. Set
maxPixelsto refuse them instead. - The mask is a 1-bit PNG, several times smaller than odiff's RGBA one. Its content hash differs from that of the same mask written by odiff.
Median of 9 runs, Apple M-series, from two files on disk to a mask on disk
with its hash and fingerprint (pnpm bench):
| fixture | megapixels | differs | before (ms) | after (ms) | |
|---|---|---|---|---|---|
boxShadow |
0.1 | — | 5.6 | 0.3 | 17.1× |
alphaSmallGraph |
1.4 | — | 21.5 | 1.6 | 13.4× |
minorChange1 |
2.7 | 0.01% | 58.5 | 2.6 | 22.4× |
minorChange2 |
2.1 | — | 29.4 | 3.3 | 9.0× |
imageCompression5 |
3.0 | — | 49.4 | 11.5 | 4.3× |
imageCompression7 |
2.7 | — | 97.4 | 26.5 | 3.7× |
tableAlpha |
2.1 | 18% | 53.8 | 6.3 | 8.6× |
simple |
1.6 | 30% | 55.9 | 8.3 | 6.7× |
big-images |
4.5 | 81% | 349.5 | 41.0 | 8.5× |
different-dimensions |
105.3 | 9% | 3043.7 | 518.8 | 5.9× |
All 19 fixtures: 3.9 s before, 0.65 s after. Where little differs the time
left is PNG decoding; imageCompression7 is two noisy 2.7 megapixel PNGs that
take 16 ms each to inflate.
A comparison holds the two decoded images, 4 bytes a pixel each, and a quarter of a byte per pixel of the canvas: one bit per tier, the reported bit plane becoming the mask. Nothing else grows with the image:
- images of different sizes are read in place, never copied onto a padded canvas;
- PNG files are decoded as they are read, greyscale ones widened in place, and JPEG decoded straight into the pixel buffer;
- with
maxPixels, an oversized pair — or a decompression bomb — is refused from the headers, before a pixel buffer exists.
tests/memory.rs counts every allocation and
fails when one of these grows past its budget, and a Node.js test checks that
repeated calls give their memory back.
The old pipeline ran two odiff processes at once, each holding both images
and an RGBA diff. Peak resident memory, measured with /usr/bin/time -l:
| fixture | megapixels | odiff ×2 | iris |
|---|---|---|---|
simple |
1.6 | 44 MiB | 14 MiB |
tableAlpha |
2.1 | 54 MiB | 17 MiB |
imageCompression7 |
2.7 | 68 MiB | 22 MiB |
big-images |
4.5 | 108 MiB | 34 MiB |
iris is measured above a Node.js process with the addon loaded; the odiff
figures leave out sharp and the fingerprinting process.
The comparison is the iris crate, in
crates/iris; the Node.js package is a thin N-API
binding over it.
use iris::{compare_files, Antialiasing, Options};
let options = Options {
antialiasing: Antialiasing::Subpixel,
..Options::sensitivity(0.5)
};
let result = compare_files("base.png", "head.png", &options)?;
if let Some(mask) = &result.mask {
std::fs::write("mask.png", mask.to_png()?)?;
}Building needs CMake, and NASM on x86 for libjpeg-turbo's SIMD code.
pnpm install
pnpm build # the native addon, release profile
pnpm test # Rust tests, then the Node.js tests
pnpm benchpnpm test:rust points ODIFF_BIN at the binary odiff-bin ships and runs
it on every fixture — PNG, JPEG and WebP — and on generated images, at six
thresholds, with anti-aliasing on and off, comparing masks bit by bit. It also
feeds the decoders 1,500 damaged files: a comparison runs inside the server
process, so bad input has to be refused, never crash it. Parity is with odiff
4.5.0, whose fixed-point coefficients are truncated; later versions round
them and count a few more pixels near the threshold.
MIT