@blazediff/core

@blazediff/core

High-performance pixel-by-pixel image comparison with two-pass block-based optimization and YIQ perceptual color difference. Up to 91% faster than pixelmatch on identical images, ~62% average improvement overall.

Features:

• YIQ color space for perceptual color difference
• Anti-aliasing detection and filtering
• Two-pass block-based optimization with 32-bit integer 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

Average: ~62% | Median: ~85% | Best case (identical): up to 91%

Benchmarked against pixelmatch across 34 fixtures (50 iterations, 5 warmup) on Apple M1 Max with Node.js 22. Full numbers in the root BENCHMARKS.md.

Benchmark	Pixelmatch	BlazeDiff	Improvement
4k/1 (5600×3200)	349.90ms	172.60ms	50.7%
4k/1 (identical)	21.47ms	3.52ms	83.6%
page/1 (3598×16384)	147.00ms	94.64ms	35.6%
page/1 (identical)	70.36ms	7.77ms	89.0%
small images	0.2-4ms	0.01-2ms	30-91%

The block-based optimization provides the most benefit on identical images (~85-91% 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