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

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

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