Blazing-fast pixel-by-pixel image comparison with block-based optimization. 1.5x times faster than pixelmatch
npm install @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.
``bash`
npm install @blazediff/core
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 |
`typescript
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,
}
);
``
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.
> 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.
- 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