\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 block-based optimization. 20% faster than pixelmatch with zero memory allocation.\n\n**Features:**\n- YIQ color space for perceptual color difference\n- Anti-aliasing detection and filtering\n- Block-based optimization with 32-bit integer comparison\n- Zero memory allocation during 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> **Median: 82%** | Arithmetic mean: 65% | Weighted average: 42%\n\nBenchmarked against pixelmatch across various image sizes (50 iterations, 5 warmup):\n\n| Benchmark | Pixelmatch | BlazeDiff | Improvement |\n|-----------|------------|-----------|-------------|\n| 4k/1 (5600×3200) | 302ms | 212ms | **30%** |\n| 4k/1 (identical) | 19ms | 2.4ms | **88%** |\n| page/1 (3598×16384) | 332ms | 93ms | **72%** |\n| page/1 (identical) | 63ms | 7.7ms | **88%** |\n| small images | 0.4-4ms | 0.1-2ms | **55-90%** |\n\nThe block-based optimization provides the most benefit on identical images (~88% 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","users":{}}