\n\n[](https://www.npmjs.com/package/@blazediff/core)\n[](https://www.npmjs.com/package/@blazediff/core)\n\n
\n\nHigh-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.\n\n**Features:**\n- YIQ color space for perceptual color difference\n- Anti-aliasing detection and filtering\n- Two-pass block-based optimization with 32-bit integer comparison\n- Support for alpha channel and transparency\n\nFor detailed algorithm explanation and mathematical formulas, see [FORMULA.md](./FORMULA.md).\n\n## Installation\n\n```bash\nnpm install @blazediff/core\n```\n\n## API\n\n### blazediff(image1, image2, output, width, height, options)\n\nCompare two images and return the number of different pixels.\n\n\n \n | Option | \n Type | \n Default | \n Description | \n Hint | \n
\n \n threshold | \n number | \n 0.1 | \n Color difference threshold (0-1) | \n Lower values = more sensitive. 0.05 for strict comparison, 0.2+ for loose comparison | \n
\n \n alpha | \n number | \n 0.1 | \n Background image opacity | \n Controls how faded unchanged pixels appear in diff output | \n
\n \n aaColor | \n [number, number, number] | \n [255,255,0] | \n Anti-aliasing pixel color | \n Yellow by default. Set to red [255,0,0] to highlight anti-aliasing | \n
\n \n diffColor | \n [number, number, number] | \n [255,0,0] | \n Different pixel color | \n Red by default. Use contrasting colors for better visibility | \n
\n \n diffColorAlt | \n [number, number, number] | \n - | \n Alternative color for dark differences | \n Helps distinguish light vs dark pixel changes | \n
\n \n includeAA | \n boolean | \n false | \n Include anti-aliasing in diff count | \n Set true to count anti-aliasing pixels as actual differences | \n
\n \n diffMask | \n boolean | \n false | \n Output only differences (transparent background) | \n Useful for creating overlay masks or highlighting changes only | \n
\n \n fastBufferCheck | \n boolean | \n true | \n Use fast buffer check using Buffer.compare | \n Set to false if images are processed differently, but look similiar | \n
\n
\n\n## Usage\n\n```typescript\nimport { diff } from '@blazediff/core';\n\nconst diffCount = diff(\n image1.data,\n image2.data,\n outputData,\n width,\n height,\n {\n threshold: 0.1,\n alpha: 0.1,\n aaColor: [255, 255, 0],\n diffColor: [255, 0, 0],\n includeAA: false,\n diffMask: false,\n fastBufferCheck: true,\n }\n);\n```\n\n## Algorithm\n\nBlazeDiff uses a sophisticated multi-stage approach for high-performance image comparison:\n\n1. **Block-Based Pre-filtering**: Divides images into adaptive blocks and uses 32-bit integer comparison to quickly identify unchanged regions\n2. **YIQ Color Space**: Converts RGB to YIQ color space for perceptually accurate color difference measurement\n3. **Anti-Aliasing Detection**: Implements the Vysniauskas (2009) algorithm to distinguish anti-aliasing artifacts from real differences\n4. **Optimized Memory Access**: Zero-allocation design with cache-friendly memory patterns\n\nSee [FORMULA.md](./FORMULA.md) for detailed mathematical formulas and algorithm explanation.\n\n## Performance\n\n> **Average: ~62%** | Median: ~85% | Best case (identical): up to 91%\n\nBenchmarked against pixelmatch across 34 fixtures (50 iterations, 5 warmup) on Apple M1 Max with Node.js 22. Full numbers in the root [BENCHMARKS.md](https://github.com/teimurjan/blazediff/blob/main/BENCHMARKS.md).\n\n| Benchmark | Pixelmatch | BlazeDiff | Improvement |\n|-----------|------------|-----------|-------------|\n| 4k/1 (5600×3200) | 349.90ms | 172.60ms | **50.7%** |\n| 4k/1 (identical) | 21.47ms | 3.52ms | **83.6%** |\n| page/1 (3598×16384) | 147.00ms | 94.64ms | **35.6%** |\n| page/1 (identical) | 70.36ms | 7.77ms | **89.0%** |\n| small images | 0.2-4ms | 0.01-2ms | **30-91%** |\n\nThe block-based optimization provides the most benefit on identical images (~85-91% faster) and images with large unchanged regions.\n\n## References\n\n- **Algorithm Documentation**: [FORMULA.md](./FORMULA.md) - Complete mathematical foundation and formulas\n- **YIQ Color Space**: [Kotsarenko & Ramos (2009)](https://doaj.org/article/b2e3b5088ba943eebd9af2927fef08ad) - \"Measuring perceived color difference using YIQ NTSC transmission color space\"\n- **Anti-Aliasing Detection**: [Vysniauskas (2009)](https://www.researchgate.net/publication/234073157_Anti-aliased_Pixel_and_Intensity_Slope_Detector) - \"Anti-aliased Pixel and Intensity Slope Detector\"\n- **Inspiration**: [pixelmatch](https://github.com/mapbox/pixelmatch) - Original pixel-by-pixel diff algorithm\n","readmeFilename":"README.md"}