pixelmatch

A Go port of mapbox/pixelmatch, compatible with v8.0.0.

Comparison uses the OKLab HyAB metric with toe-corrected lightness. Thresholds from older YIQ-based versions can produce different counts. Semi-transparent pixels are compared over a checkerboard by default; use Checkerboard(false) to compare over white.

Installation

library

go get github.com/orisano/pixelmatch

cli

go get github.com/orisano/pixelmatch/cmd/pixelmatch

Library usage

Pass two equally sized image.Image values. Their bounds origins may differ; the output uses the first image's bounds. The Go port also preserves precision when comparing 16-bit images.

var diff image.Image
count, err := pixelmatch.MatchPixel(img1, img2,
    pixelmatch.Threshold(0.1),
    pixelmatch.WriteTo(&diff),
)

Omit WriteTo when only the count is needed.

Upstream option	Go option	Default / behavior
threshold	Threshold(float64)	0.1; smaller is more sensitive. 1 is approximately the black-to-white distance.
includeAA	IncludeAntiAlias	Off; when supplied, anti-aliased pixels count as differences.
alpha	Alpha(float64)	0.1; opacity of unchanged pixels in the grayscale output.
aaColor	AntiAliasedColor(color.Color)	Yellow.
diffColor	DiffColor(color.Color)	Red.
diffColorAlt	DiffColorAlt(color.Color)	Uses diffColor by default; highlights pixels darker in the second image.
diffMask	EnableDiffMask	Off; when supplied, unchanged and excluded AA pixels stay transparent.
checkerboard	Checkerboard(bool)	true; controls the background for semi-transparent comparison.
windowSize	WindowSize(float64)	+Inf; finite values return the largest diff count in any square sliding window.
ignoreMask	IgnoreMask([]byte)	nil; nonzero bytes skip comparison and draw the pixel as unchanged.

Marker colors use RGB and are always opaque. The ignore mask must contain one byte per pixel in row order (width * height), or MatchPixel returns ErrIgnoreMaskSizeNotMatch. Ignored pixels still participate in neighboring anti-alias detection, as in upstream.

Window sizes are floored and clamped to 1..min(width, height). For example, WindowSize(32) on a 10×2 image uses a 2×2 window. Non-finite sizes return the total count. Windowing changes only the returned count; the output image still shows every difference.

Command line

The positional arguments and exit codes follow upstream:

pixelmatch image1.png image2.png [diff.png] [threshold] [includeAA]
pixelmatch image1.png image2.png diff.png 0.1 false

The CLI prints the differing pixel count and percentage. It exits with 0 for a match, 66 for differences, 65 for different dimensions, 64 for invalid usage, and 1 for file or encoding errors. Without a destination it only prints the count. Use -dest - to stream a PNG to stdout; the count then goes to stderr.

The existing flags remain available, including JPEG output, with additional comparison options:

pixelmatch -checkerboard=false -dest diff.png image1.png image2.png
pixelmatch -windowsize 16 -aa image1.png image2.png
pixelmatch -diffmask -ignoremask ignore.bin -dest diff.png image1.png image2.png

-ignoremask reads raw bytes, one per pixel. -aa includes anti-aliased pixels in the count. Color flags accept #RRGGBB or #RRGGBBAA; output marker alpha is always opaque. Run pixelmatch -h for all flags.

Compatibility tests

go test ./... checks counts and output pixels against reference results generated by upstream v8.0.0. It covers transparency, near-black colors, anti-alias detection, masks, windows, cropped images, and differing bounds origins. Tests require no JavaScript runtime or network access.

To regenerate the reference results:

curl -fsSL https://raw.githubusercontent.com/mapbox/pixelmatch/v8.0.0/index.js -o /tmp/pixelmatch-v8.mjs
node testdata/generate-v8.mjs /tmp/pixelmatch-v8.mjs > testdata/pixelmatch-v8.json

Performance

Benchmarks cover identical, sparse, dense, transparent, cropped, and windowed comparisons, both with and without diff output, plus the PNG fixtures:

go test -run '^$' -bench BenchmarkMatchPixel -benchmem
go test -run '^$' -bench '^BenchmarkMatchPixel/dense/count$' -benchtime=3s \
    -cpuprofile /tmp/pixelmatch.cpu -o /tmp/pixelmatch.test
go tool pprof /tmp/pixelmatch.test /tmp/pixelmatch.cpu

Author

Nao Yonashiro (@orisano)

License

MIT