Détail du package

@blazediff/core

teimurjan54.6kMIT1.5.0

Blazing-fast pixel-by-pixel image comparison with block-based optimization. 1.5x times faster than pixelmatch

image, comparison, diff, pixel

readme

@blazediff/core

npm bundle size NPM Downloads

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 blazediff from '@blazediff/core';

const diffCount = blazediff(
  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

Compared to pixelmatch on a 1920×1080 image with 10% differences:

Metric BlazeDiff pixelmatch Improvement
Speed ~25ms ~30ms 20% faster
Memory 0 allocations Multiple allocations Zero allocation
Accuracy YIQ perceptual YIQ perceptual Same

The block-based optimization provides the most benefit on images with large unchanged regions.

When to Use BlazeDiff vs Other Metrics

Use @blazediff/core when:

  • You need pixel-perfect diff visualization
  • You want to filter out anti-aliasing artifacts
  • You need precise control over difference colors
  • Performance is critical for CI/CD pipelines

Use @blazediff/gmsd when:

  • You need a perceptual similarity score (0-1)
  • You want to detect structural/gradient changes
  • You're comparing images with different compression or slight shifts
  • You need a single quality metric for regression testing

Limitations

  • Format: Requires RGBA format (4 bytes per pixel). Use transformers to convert other formats.
  • Memory: Images must fit in memory. For very large images (>100MP), consider tiling.
  • Precision: Uses floating-point arithmetic for color conversion. Expect ~0.01% variance in edge cases.
  • Anti-aliasing: Detection works best on standard rendering. May not detect exotic AA techniques.

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