@blazediff/bin 1.7.0 → 2.0.1

package/README.md

@@ -7,118 +7,203 @@
 
 </div>
 
-Command-line interface for the BlazeDiff image comparison library.
+The fastest single-threaded image diff in the world. Native Rust implementation with SIMD optimization, **3-4x faster** and **3x smaller** than [odiff](https://github.com/dmtrKovalenko/odiff).
+
+**Features:**
+- SIMD-accelerated (NEON on ARM, SSE4.1 on x86)
+- Block-based two-pass optimization
+- YIQ perceptual color difference
+- Anti-aliasing detection
+- Cross-platform pre-built binaries (~700KB-900KB, no compilation required)
 
 ## Installation
 
 ```bash
-npm install -g @blazediff/bin
+npm install @blazediff/bin
 ```
 
-## Usage
-
-```bash
-blazediff <command> <image1> <image2> [options]
+Pre-built [binaries](https://github.com/teimurjan/blazediff/tree/main/packages/bin/binaries) are included for:
+- macOS ARM64 (Apple Silicon)
+- macOS x64 (Intel)
+- Linux ARM64
+- Linux x64
+- Windows ARM64
+- Windows x64
+
+## API
+
+### compare(basePath, comparePath, diffOutput, options?)
+
+Compare two PNG images and generate a diff image.
+
+<table>
+  <tr>
+    <th width="500">Parameter</th>
+    <th width="500">Type</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>basePath</code></td>
+    <td>string</td>
+    <td>Path to the base/expected image</td>
+  </tr>
+  <tr>
+    <td><code>comparePath</code></td>
+    <td>string</td>
+    <td>Path to the comparison/actual image</td>
+  </tr>
+  <tr>
+    <td><code>diffOutput</code></td>
+    <td>string</td>
+    <td>Path where the diff image will be saved</td>
+  </tr>
+  <tr>
+    <td><code>options</code></td>
+    <td>BlazeDiffOptions</td>
+    <td>Comparison options (optional)</td>
+  </tr>
+</table>
+
+<strong>Returns:</strong> `Promise<BlazeDiffResult>`
+
+<table>
+  <tr>
+    <th width="500">Option</th>
+    <th width="500">Type</th>
+    <th width="500">Default</th>
+    <th width="500">Description</th>
+  </tr>
+  <tr>
+    <td><code>threshold</code></td>
+    <td>number</td>
+    <td>0.1</td>
+    <td>Color difference threshold (0.0-1.0). Lower = more strict</td>
+  </tr>
+  <tr>
+    <td><code>antialiasing</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Enable anti-aliasing detection to exclude AA pixels from diff count</td>
+  </tr>
+  <tr>
+    <td><code>diffMask</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Output only differences with transparent background</td>
+  </tr>
+  <tr>
+    <td><code>failOnLayoutDiff</code></td>
+    <td>boolean</td>
+    <td>false</td>
+    <td>Fail immediately if images have different dimensions</td>
+  </tr>
+</table>
+
+### Result Types
+
+```typescript
+type BlazeDiffResult =
+  | { match: true }
+  | { match: false; reason: "layout-diff" }
+  | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number }
+  | { match: false; reason: "file-not-exists"; file: string };
 ```
 
-## Commands
+## Usage
 
-BlazeDiff supports multiple comparison algorithms, each optimized for different use cases:
+### Programmatic API
 
-### `diff` - Pixel-by-pixel comparison (default)
-Fast pixel-level comparison for detecting visual regressions.
+```typescript
+import { compare } from '@blazediff/bin';
 
-```bash
-blazediff diff image1.png image2.png [options]
-# Or simply:
-blazediff image1.png image2.png [options]
+const result = await compare('expected.png', 'actual.png', 'diff.png', {
+  threshold: 0.1,
+  antialiasing: true,
+});
+
+if (result.match) {
+  console.log('Images are identical!');
+} else if (result.reason === 'pixel-diff') {
+  console.log(`${result.diffCount} pixels differ (${result.diffPercentage.toFixed(2)}%)`);
+} else if (result.reason === 'layout-diff') {
+  console.log('Images have different dimensions');
+}
 ```
 
-**Options:**
-- `-o, --output <path>` - Output path for the diff image
-- `-t, --threshold <num>` - Matching threshold (0 to 1, default: 0.1)
-- `-a, --alpha <num>` - Opacity of original image in diff (default: 0.1)
-- `--aa-color <r,g,b>` - Color for anti-aliased pixels (default: 255,255,0)
-- `--diff-color <r,g,b>` - Color for different pixels (default: 255,0,0)
-- `--diff-color-alt <r,g,b>` - Alternative color for dark differences
-- `--include-aa` - Include anti-aliasing detection
-- `--diff-mask` - Draw diff over transparent background
-- `--color-space <name>` - Specify color space to use (yiq, ycbcr)
-- `--transformer <name>` - Specify transformer to use (pngjs, sharp)
-- `-h, --help` - Show help message
-
-### `gmsd` - Gradient Magnitude Similarity Deviation
-Perceptual quality metric based on gradient similarity.
+### CLI Usage
 
 ```bash
-blazediff gmsd image1.png image2.png [options]
-```
+# Compare two images
+npx blazediff expected.png actual.png diff.png
 
-**Options:**
-- `-o, --output <path>` - Output path for GMS similarity map
-- `--downsample <0|1>` - Downsample factor (0=full-res, 1=2x, default: 0)
-- `--gmsd-c <num>` - Stability constant (default: 170)
-- `--transformer <name>` - Specify transformer to use (pngjs, sharp)
-- `-h, --help` - Show help message
+# With options
+npx blazediff expected.png actual.png diff.png --threshold 0.05 --antialiasing
 
-### `ssim` - Structural Similarity Index
-Industry-standard metric for measuring structural similarity.
+# With higher compression (smaller output file, slower)
+npx blazediff expected.png actual.png diff.png -c 6
 
-```bash
-blazediff ssim image1.png image2.png [options]
+# Output as JSON
+npx blazediff expected.png actual.png diff.png --output-format json
 ```
 
-**Options:**
-- `-o, --output <path>` - Output path for SSIM map visualization
-- `--transformer <name>` - Specify transformer to use (pngjs, sharp)
-- `-h, --help` - Show help message
-
-### `msssim` - Multi-Scale Structural Similarity Index
-Enhanced SSIM that operates at multiple image scales.
+### CLI Options
 
-```bash
-blazediff msssim image1.png image2.png [options]
+```
+Usage: blazediff [OPTIONS] <IMAGE1> <IMAGE2> <OUTPUT>
+
+Arguments:
+  <IMAGE1>  First image path
+  <IMAGE2>  Second image path
+  <OUTPUT>  Output diff image path
+
+Options:
+  -t, --threshold <THRESHOLD>  Color difference threshold (0.0-1.0) [default: 0.1]
+  -a, --antialiasing           Enable anti-aliasing detection
+      --diff-mask              Output only differences (transparent background)
+      --fail-on-layout         Fail on layout (size) difference
+  -c, --compression <LEVEL>    PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) [default: 0]
+      --output-format <FORMAT> Output format (json or text) [default: json]
+  -h, --help                   Print help
+  -V, --version                Print version
 ```
 
-**Options:**
-- `-o, --output <path>` - Output path for MS-SSIM map visualization
-- `--transformer <name>` - Specify transformer to use (pngjs, sharp)
-- `-h, --help` - Show help message
+### Exit Codes
 
-## Examples
+- `0` - Images are identical
+- `1` - Images differ (or layout mismatch with `--fail-on-layout`)
+- `2` - Error (file not found, invalid format, etc.)
 
-```bash
-# Pixel-by-pixel diff (default)
-blazediff image1.png image2.png
-blazediff diff image1.png image2.png -o diff.png -t 0.05
+## Performance
 
-# GMSD similarity metric
-blazediff gmsd image1.png image2.png
-blazediff gmsd image1.png image2.png -o gms-map.png
+Benchmarked on Apple M1 Pro with 5600x3200 4K images:
 
-# SSIM structural similarity
-blazediff ssim image1.png image2.png
-blazediff ssim image1.png image2.png -o ssim-map.png
+| Tool | Benchmark Time | vs blazediff |
+|------|------|--------------|
+| **blazediff** | ~327ms | - |
+| odiff | ~1215ms | 3.4x slower |
 
-# MS-SSIM multi-scale similarity
-blazediff msssim image1.png image2.png
-blazediff msssim image1.png image2.png -o msssim-map.png
+Binary sizes (stripped, LTO optimized) - **~3x smaller than odiff**:
 
-# Use Sharp transformer for better performance
-blazediff ssim image1.jpg image2.jpg --transformer sharp
-```
+| Platform | blazediff | odiff |
+|----------|-----------|-------|
+| macOS ARM64 | 702 KB | 2.2 MB |
+| macOS x64 | 773 KB | 2.6 MB |
+| Linux ARM64 | 753 KB | 2.3 MB |
+| Linux x64 | 869 KB | 2.9 MB |
+| Windows ARM64 | 580 KB | 2.4 MB |
+| Windows x64 | 915 KB | 3.0 MB |
 
-## Transformers
+## Algorithm
 
-- **pngjs** - Pure JavaScript, works everywhere. Supports PNG only.
-- **sharp** - Native bindings, significantly faster. Supports PNG and JPEG.
+BlazeDiff uses a two-pass block-based approach with SIMD acceleration:
 
-## Exit Codes
+1. **Cold Pass**: Scans image in 8x8 blocks using 32-bit integer comparison to identify changed regions
+2. **Hot Pass**: Only processes blocks marked as changed, applying YIQ perceptual color difference
+3. **SIMD**: Uses NEON (ARM) or SSE4.1 (x86) for parallel pixel processing
+4. **Anti-aliasing**: Implements Vysniauskas (2009) algorithm to detect AA artifacts
 
-### Diff Mode
-- `0` - Images are identical
-- `1` - Images have differences or error occurred
+## References
 
-### GMSD, SSIM, MS-SSIM Modes
-- `0` - Images are highly similar (score >= 0.95)
-- `1` - Images have noticeable differences (score < 0.95) or error occurred
+- **YIQ Color Space**: [Kotsarenko & Ramos (2009)](https://doaj.org/article/b2e3b5088ba943eebd9af2927fef08ad) - "Measuring perceived color difference using YIQ NTSC transmission color space"
+- **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"
+- **Inspiration**: [odiff](https://github.com/dmtrKovalenko/odiff) - Fast image comparison tool written in Zig

package/dist/index.d.mts

@@ -1,69 +1,46 @@
-interface Image {
-    data: Buffer | Uint8Array | Uint8ClampedArray;
-    width: number;
-    height: number;
-}
-interface Transformer {
-    read: (input: string | Buffer) => Promise<Image>;
-    write: (image: Image, output: string | Buffer) => Promise<void>;
-}
-type ComparisonMode = "diff" | "gmsd" | "ssim" | "msssim";
-interface DiffModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode?: "diff";
-    options?: Record<string, unknown>;
-}
-interface GmsdModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "gmsd";
-    options?: Record<string, unknown>;
-}
-interface SsimModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "ssim";
-    options?: Record<string, unknown>;
-}
-interface MsssimModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "msssim";
-    options?: Record<string, unknown>;
-}
-interface DiffModeResult {
-    mode: "diff";
+interface BlazeDiffOptions {
+    /** Color difference threshold (0.0-1.0). Lower = more strict. Default: 0.1 */
+    threshold?: number;
+    /** Enable anti-aliasing detection to exclude AA pixels from diff count */
+    antialiasing?: boolean;
+    /** Output only differences with transparent background */
+    diffMask?: boolean;
+    /** Fail immediately if images have different dimensions */
+    failOnLayoutDiff?: boolean;
+    /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
+    compression?: number;
+}
+type BlazeDiffResult = {
+    match: true;
+} | {
+    match: false;
+    reason: "layout-diff";
+} | {
+    match: false;
+    reason: "pixel-diff";
     diffCount: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface GmsdModeResult {
-    mode: "gmsd";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface SsimModeResult {
-    mode: "ssim";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface MsssimModeResult {
-    mode: "msssim";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-type BlazeDiffBinResult = DiffModeResult | GmsdModeResult | SsimModeResult | MsssimModeResult;
+    diffPercentage: number;
+} | {
+    match: false;
+    reason: "file-not-exists";
+    file: string;
+};
+/**
+ * Compare two PNG images and generate a diff image.
+ *
+ * @example
+ * ```ts
+ * const result = await compare('expected.png', 'actual.png', 'diff.png');
+ *
+ * if (result.match) {
+ *   console.log('Images identical');
+ * } else if (result.reason === 'pixel-diff') {
+ *   console.log(`${result.diffCount} pixels differ`);
+ * }
+ * ```
+ */
+declare function compare(basePath: string, comparePath: string, diffOutput: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
+/** Get the path to the blazediff binary for direct CLI usage. */
+declare function getBinaryPath(): string;
 
-export type { BlazeDiffBinResult, ComparisonMode, DiffModeOptions, DiffModeResult, GmsdModeOptions, GmsdModeResult, Image, MsssimModeOptions, MsssimModeResult, SsimModeOptions, SsimModeResult, Transformer };
+export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath };

package/dist/index.d.ts

@@ -1,69 +1,46 @@
-interface Image {
-    data: Buffer | Uint8Array | Uint8ClampedArray;
-    width: number;
-    height: number;
-}
-interface Transformer {
-    read: (input: string | Buffer) => Promise<Image>;
-    write: (image: Image, output: string | Buffer) => Promise<void>;
-}
-type ComparisonMode = "diff" | "gmsd" | "ssim" | "msssim";
-interface DiffModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode?: "diff";
-    options?: Record<string, unknown>;
-}
-interface GmsdModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "gmsd";
-    options?: Record<string, unknown>;
-}
-interface SsimModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "ssim";
-    options?: Record<string, unknown>;
-}
-interface MsssimModeOptions {
-    outputPath?: string;
-    transformer: Transformer;
-    mode: "msssim";
-    options?: Record<string, unknown>;
-}
-interface DiffModeResult {
-    mode: "diff";
+interface BlazeDiffOptions {
+    /** Color difference threshold (0.0-1.0). Lower = more strict. Default: 0.1 */
+    threshold?: number;
+    /** Enable anti-aliasing detection to exclude AA pixels from diff count */
+    antialiasing?: boolean;
+    /** Output only differences with transparent background */
+    diffMask?: boolean;
+    /** Fail immediately if images have different dimensions */
+    failOnLayoutDiff?: boolean;
+    /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
+    compression?: number;
+}
+type BlazeDiffResult = {
+    match: true;
+} | {
+    match: false;
+    reason: "layout-diff";
+} | {
+    match: false;
+    reason: "pixel-diff";
     diffCount: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface GmsdModeResult {
-    mode: "gmsd";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface SsimModeResult {
-    mode: "ssim";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-interface MsssimModeResult {
-    mode: "msssim";
-    score: number;
-    width: number;
-    height: number;
-    outputData?: Uint8Array;
-    duration: number;
-}
-type BlazeDiffBinResult = DiffModeResult | GmsdModeResult | SsimModeResult | MsssimModeResult;
+    diffPercentage: number;
+} | {
+    match: false;
+    reason: "file-not-exists";
+    file: string;
+};
+/**
+ * Compare two PNG images and generate a diff image.
+ *
+ * @example
+ * ```ts
+ * const result = await compare('expected.png', 'actual.png', 'diff.png');
+ *
+ * if (result.match) {
+ *   console.log('Images identical');
+ * } else if (result.reason === 'pixel-diff') {
+ *   console.log(`${result.diffCount} pixels differ`);
+ * }
+ * ```
+ */
+declare function compare(basePath: string, comparePath: string, diffOutput: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
+/** Get the path to the blazediff binary for direct CLI usage. */
+declare function getBinaryPath(): string;
 
-export type { BlazeDiffBinResult, ComparisonMode, DiffModeOptions, DiffModeResult, GmsdModeOptions, GmsdModeResult, Image, MsssimModeOptions, MsssimModeResult, SsimModeOptions, SsimModeResult, Transformer };
+export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath };

package/dist/index.js

@@ -1 +1,108 @@
-'use strict';
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  compare: () => compare,
+  getBinaryPath: () => getBinaryPath
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_child_process = require("child_process");
+var import_node_path = __toESM(require("path"));
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var BINARY_PATH = import_node_path.default.join(__dirname, "..", "bin", "blazediff.exe");
+function buildArgs(diffOutput, options) {
+  const args = [diffOutput, "--output-format=json"];
+  if (!options) return args;
+  if (options.threshold !== void 0) args.push(`--threshold=${options.threshold}`);
+  if (options.antialiasing) args.push("--antialiasing");
+  if (options.diffMask) args.push("--diff-mask");
+  if (options.failOnLayoutDiff) args.push("--fail-on-layout");
+  if (options.compression !== void 0) args.push(`--compression=${options.compression}`);
+  return args;
+}
+function parseJsonOutput(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function detectMissingFile(error, basePath, comparePath) {
+  if (!/Failed to load images:.*(?:No such file|not found)/i.test(error)) {
+    return null;
+  }
+  if (error.includes(basePath)) return basePath;
+  if (error.includes(comparePath)) return comparePath;
+  return basePath;
+}
+async function compare(basePath, comparePath, diffOutput, options) {
+  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
+  try {
+    await execFileAsync(BINARY_PATH, args);
+    return { match: true };
+  } catch (err) {
+    const { code, stdout, stderr } = err;
+    const output = stdout || stderr || "";
+    if (code === 1) {
+      const json = parseJsonOutput(output);
+      if (json?.error?.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+      if (json) {
+        return {
+          match: false,
+          reason: "pixel-diff",
+          diffCount: json.diffCount,
+          diffPercentage: json.diffPercentage
+        };
+      }
+      if (output.includes("Layout differs")) {
+        return { match: false, reason: "layout-diff" };
+      }
+    }
+    if (code === 2) {
+      const missingFile = detectMissingFile(output, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+    }
+    throw new Error(output || `blazediff exited with code ${code}`);
+  }
+}
+function getBinaryPath() {
+  return BINARY_PATH;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compare,
+  getBinaryPath
+});