blazediff

High-performance image diffing with block-based optimization and SIMD acceleration.

Features

• Block-based optimization - Skip identical regions for massive speedups on similar images
• SIMD acceleration - Native SSE4.1 (x86) and NEON (ARM) implementations
• Multiple formats - PNG, JPEG, and QOI support, via blazediff-shared
• Perceptual diffing - YIQ-based color difference with antialiasing detection
• In-house PNG codec - optional blazediff_png, faster than spng on every fixture, with byte-exact decode parity; opt-in via BLAZEDIFF_PNG_ENABLED
• Cross-platform - Linux, macOS, and Windows support
• Multi-language - Native Rust crate, Node.js (N-API), and Python (PyO3) bindings - all sharing the same core

Installation

Rust (CLI + library)

cargo install blazediff

Node.js - @blazediff/core-native

npm install @blazediff/core-native

N-API bindings shipped as pre-built .node binaries for macOS, Linux, and Windows (arm64 + x64). Built from this crate's napi Cargo feature.

import { diff } from "@blazediff/core-native";

const result = await diff("expected.png", "actual.png", {
  output: "diff.png",
  threshold: 0.1,
});
if (result.kind === "compared" && !result.identical) {
  console.log(`${result.count} pixels differ`);
}

Python - blazediff

pip install blazediff

PyO3 bindings shipped as abi3-py38 wheels for CPython ≥ 3.8 (macOS, Linux manylinux, Windows; arm64 + x86_64). Built from this crate's python Cargo feature.

from blazediff import diff

result = diff("expected.png", "actual.png", "diff.png", threshold=0.1)
if result.kind == "compared" and not result.identical:
    print(f"{result.count} pixels differ ({result.percentage:.2f}%)")

diff(a, b, output=None, *, threshold=0.1, antialiasing=True, metric="yiq", mask=None, window=None, alpha=0.1, diff_color=None, diff_color_alt=None, aa_color=None, background="faded", compression=0, quality=90) takes file paths or encoded bytes. The result has a kind:

Invalid options raise ValueError.

CLI Usage

# Basic diff
blazediff image1.png image2.png -o diff.png

# With custom threshold (0.0 - 1.0)
blazediff image1.png image2.png -o diff.png -t 0.1

# pixelmatch 8 metric, a mask, and the busiest 16×16 window, as JSON
blazediff image1.png image2.png --metric oklab --mask mask.png --window 16 --json

Exit codes: 0 identical, 1 the images differ or their dimensions do not match, 2 error. With --json, a result prints to stdout ({"kind":"compared","count":..,"percentage":..,"identical":..}, or {"kind":"dimension-mismatch","a":{..},"b":{..}}) and an error prints to stderr ({"kind":"io-error","path":..,"message":..}).

Library Usage

use blazediff::{diff, load_png, save_png, DiffOptions, DiffResult, Image, Metric};

let a = load_png("image1.png")?;
let b = load_png("image2.png")?;
let mut output = Image::new(a.width, a.height);
let options = DiffOptions {
    threshold: 0.1,
    metric: Metric::Oklab,
    window: Some(16),
    ..Default::default()
};

match diff(&a, &b, Some(&mut output), &options)? {
    DiffResult::Compared { count, window, .. } => {
        println!("Different pixels: {count}, busiest window: {window:?}");
        save_png(&output, "diff.png")?;
    }
    DiffResult::DimensionMismatch { a, b } => println!("Sizes differ: {a:?} vs {b:?}"),
}

DiffOptions holds threshold, antialiasing (default true), metric (Yiq or Oklab), mask (one byte per pixel, non-zero is skipped), window, and render (alpha, diff_color, diff_color_alt, aa_color, background). diff returns Err only for buffers that do not match their size and masks of the wrong length.

Structural similarity

This crate is a pixel diff: it answers where two images differ. For how alike they look — SSIM, MS-SSIM, Hitchhiker's SSIM — use blazediff-ssim, which stands alone and shares nothing with this crate but the blazediff-shared primitives. It is also what @blazediff/ssim-native wraps.

Interpret

Structured region analysis that produces human-readable change descriptions. It is not part of this crate: it lives in blazediff-interpret, which consumes what diff returns, with its own blazediff-interpret CLI.

The classifier is independent of whatever found the regions. Anything that can say where something changed can drive it: blazediff-ssim by thresholding a score map, or a caller passing boxes directly. Coarse boxes are fine — each is refined against the source pixels before any statistic is computed, so the analysis stays per-pixel.

See INTERPRET.md for the full algorithm documentation - pipeline stages, formulas, classification rules, and output format.

Performance

3-4x faster than odiff, 8x faster than pixelmatch on 4K images.

Image I/O lives in blazediff-shared, shared with the other crates; load_png, save_jpeg and friends are re-exported here unchanged. PNG I/O defaults to spng. Setting BLAZEDIFF_PNG_ENABLED=1 routes decode and stored (level 0) encode through the in-house blazediff_png codec, which is faster than spng on every fixture.

License

MIT