Pixel-by-pixel Comparison - Rust + N-API in Node

The fastest path: native Rust compiled to a Node addon via N-API, ~3-4× faster than odiff. @blazediff/core-native accepts file paths or encoded Buffer and Uint8Array inputs. It decodes PNG, JPEG, and QOI itself in parallel and can write the diff image straight to disk. Reach for it in Node test runners and CI when you want maximum throughput.

Installation


npm install @blazediff/core-native


pnpm add @blazediff/core-native


yarn add @blazediff/core-native


bun add @blazediff/core-native

Examples

Basic Comparison

Image 1

Image 2

Result


import { compare } from "@blazediff/core-native";
 
const result = await compare("3a.png", "3b.png");
 
if (result.match) {
  console.log("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("dimensions differ");
}

Buffer Comparison


import { readFile } from "node:fs/promises";
import { compare } from "@blazediff/core-native";
 
const [expected, actual] = await Promise.all([
  readFile("3a.png"),
  readFile("3b.png"),
]);
 
// The native binding borrows these Buffer allocations without copying them.
const result = await compare(expected, actual);

Custom Threshold

Image 1

Image 2

Result


import { compare } from "@blazediff/core-native";
 
const result = await compare("3a.png", "3b.png", undefined, {
  threshold: 0.5,
  antialiasing: true,
});

Write Diff Image

Image 1

Image 2

Result


import { compare } from "@blazediff/core-native";
 
// Pass an output path to render the diff visualization to disk.
// Format is inferred from the extension (PNG, JPEG, QOI).
const result = await compare("3a.png", "3b.png", "diff.png");

Encoded inputs are borrowed directly for each synchronous native call, so the JavaScript bytes are not copied into Rust. PNG, JPEG, or QOI decoding still allocates native RGBA pixel buffers.

Want a verdict on what changed, not just how many pixels? Pass interpret: true or use the dedicated Image Difference Analysis → example. Full options in the API reference →.