@blazediff/core

High-performance pixel-by-pixel image comparison with block-based optimization. 20% faster than pixelmatch with zero memory allocation.

Features:

YIQ color space for perceptual color difference
Anti-aliasing detection and filtering
Block-based optimization with 32-bit integer comparison
Zero memory allocation during comparison
Support for alpha channel and transparency

For detailed algorithm explanation and mathematical formulas, see FORMULA.md.

Installation

npm install @blazediff/core

API

blazediff(image1, image2, output, width, height, options)

Compare two images and return the number of different pixels.

Parameter	Type	Description
`image1`	Uint8Array \| Uint8ClampedArray	First image data
`image2`	Uint8Array \| Uint8ClampedArray	Second image data
`output`	Uint8Array \| Uint8ClampedArray	Optional output buffer for diff visualization
`width`	number	Image width in pixels
`height`	number	Image height in pixels
`options`	object	Comparison options (optional)

Returns: Number of different pixels

Option	Type	Default	Description	Hint
`threshold`	number	0.1	Color difference threshold (0-1)	Lower values = more sensitive. 0.05 for strict comparison, 0.2+ for loose comparison
`alpha`	number	0.1	Background image opacity	Controls how faded unchanged pixels appear in diff output
`aaColor`	[number, number, number]	[255,255,0]	Anti-aliasing pixel color	Yellow by default. Set to red [255,0,0] to highlight anti-aliasing
`diffColor`	[number, number, number]	[255,0,0]	Different pixel color	Red by default. Use contrasting colors for better visibility
`diffColorAlt`	[number, number, number]	-	Alternative color for dark differences	Helps distinguish light vs dark pixel changes
`includeAA`	boolean	false	Include anti-aliasing in diff count	Set true to count anti-aliasing pixels as actual differences
`diffMask`	boolean	false	Output only differences (transparent background)	Useful for creating overlay masks or highlighting changes only
`fastBufferCheck`	boolean	true	Use fast buffer check using Buffer.compare	Set to false if images are processed differently, but look similiar

Usage

import { diff } from '@blazediff/core';

const diffCount = diff(
  image1.data,
  image2.data,
  outputData,
  width,
  height,
  {
    threshold: 0.1,
    alpha: 0.1,
    aaColor: [255, 255, 0],
    diffColor: [255, 0, 0],
    includeAA: false,
    diffMask: false,
    fastBufferCheck: true,
  }
);

Algorithm

BlazeDiff uses a sophisticated multi-stage approach for high-performance image comparison:

Block-Based Pre-filtering: Divides images into adaptive blocks and uses 32-bit integer comparison to quickly identify unchanged regions
YIQ Color Space: Converts RGB to YIQ color space for perceptually accurate color difference measurement
Anti-Aliasing Detection: Implements the Vysniauskas (2009) algorithm to distinguish anti-aliasing artifacts from real differences
Optimized Memory Access: Zero-allocation design with cache-friendly memory patterns

See FORMULA.md for detailed mathematical formulas and algorithm explanation.

Performance

Median: 82% | Arithmetic mean: 65% | Weighted average: 42%

Benchmarked against pixelmatch across various image sizes (50 iterations, 5 warmup):

Benchmark	Pixelmatch	BlazeDiff	Improvement
4k/1 (5600×3200)	302ms	212ms	30%
4k/1 (identical)	19ms	2.4ms	88%
page/1 (3598×16384)	332ms	93ms	72%
page/1 (identical)	63ms	7.7ms	88%
small images	0.4-4ms	0.1-2ms	55-90%

The block-based optimization provides the most benefit on identical images (~88% faster) and images with large unchanged regions.

References

Algorithm Documentation: FORMULA.md - Complete mathematical foundation and formulas
YIQ Color Space: Kotsarenko & Ramos (2009) - "Measuring perceived color difference using YIQ NTSC transmission color space"
Anti-Aliasing Detection: Vysniauskas (2009) - "Anti-aliased Pixel and Intensity Slope Detector"
Inspiration: pixelmatch - Original pixel-by-pixel diff algorithm