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:

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

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