@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.

Returns: Number of different pixels

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:

1. Block-Based Pre-filtering: Divides images into adaptive blocks and uses 32-bit integer comparison to quickly identify unchanged regions
2. YIQ Color Space: Converts RGB to YIQ color space for perceptually accurate color difference measurement
3. Anti-Aliasing Detection: Implements the Vysniauskas (2009) algorithm to distinguish anti-aliasing artifacts from real differences
4. 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