@blazediff/core-native 5.4.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -106,11 +106,29 @@ The native binding borrows the existing `Buffer` or `Uint8Array` backing memory
106
106
  <th width="500">Default</th>
107
107
  <th width="500">Description</th>
108
108
  </tr>
109
+ <tr>
110
+ <td><code>metric</code></td>
111
+ <td>"pixel" | "ssim" | "ms-ssim" | "hitchhikers-ssim"</td>
112
+ <td>"pixel"</td>
113
+ <td>Comparison metric. <code>pixel</code> reports which pixels changed; the rest report a pooled similarity <code>score</code> in 0-1</td>
114
+ </tr>
115
+ <tr>
116
+ <td><code>minScore</code></td>
117
+ <td>number</td>
118
+ <td>1</td>
119
+ <td>Score at or above which the ssim metrics call two images identical</td>
120
+ </tr>
121
+ <tr>
122
+ <td><code>ssimWindowSize</code></td>
123
+ <td>number</td>
124
+ <td>11</td>
125
+ <td>Local window size for the ssim metrics</td>
126
+ </tr>
109
127
  <tr>
110
128
  <td><code>threshold</code></td>
111
129
  <td>number</td>
112
130
  <td>0.1</td>
113
- <td>Color difference threshold (0.0-1.0). Lower = more strict</td>
131
+ <td>Color difference threshold (0.0-1.0). Lower = more strict. Pixel metric only</td>
114
132
  </tr>
115
133
  <tr>
116
134
  <td><code>antialiasing</code></td>
@@ -130,76 +148,16 @@ The native binding borrows the existing `Buffer` or `Uint8Array` backing memory
130
148
  <td>diff color</td>
131
149
  <td>Alternative RGB color for darkening differences</td>
132
150
  </tr>
133
- <tr>
134
- <td><code>interpret</code></td>
135
- <td>boolean</td>
136
- <td>false</td>
137
- <td>Generate the diff image and structured interpretation in one pass, adding <code>interpretation</code> to the result</td>
138
- </tr>
139
- </table>
140
-
141
- ### interpret(image1, image2, options?)
142
-
143
- Convenience wrapper that calls `compare` with `interpret: true` and returns the `InterpretResult` directly. Accepts matching path or encoded byte inputs. No diff image output - purely analytical.
144
-
145
- <table>
146
- <tr>
147
- <th width="500">Parameter</th>
148
- <th width="500">Type</th>
149
- <th width="500">Description</th>
150
- </tr>
151
- <tr>
152
- <td><code>image1</code></td>
153
- <td>string | Uint8Array</td>
154
- <td>First image path or encoded bytes</td>
155
- </tr>
156
- <tr>
157
- <td><code>image2</code></td>
158
- <td>string | Uint8Array</td>
159
- <td>Second image path or encoded bytes</td>
160
- </tr>
161
- <tr>
162
- <td><code>options</code></td>
163
- <td>Pick&lt;BlazeDiffOptions, "threshold" | "antialiasing"&gt;</td>
164
- <td>Comparison options (optional)</td>
165
- </tr>
166
151
  </table>
167
152
 
168
- <strong>Returns:</strong> `Promise<InterpretResult>`
169
-
170
153
  ### Result Types
171
154
 
172
155
  ```typescript
173
156
  type BlazeDiffResult =
174
- | { match: true; interpretation?: InterpretResult }
157
+ | { match: true }
175
158
  | { match: false; reason: "layout-diff" }
176
- | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number; interpretation?: InterpretResult }
159
+ | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number }
177
160
  | { match: false; reason: "file-not-exists"; file: string };
178
-
179
- interface InterpretResult {
180
- summary: string; // Human-readable summary of the diff
181
- diffCount: number; // Total number of differing pixels
182
- totalRegions: number; // Number of detected change regions
183
- regions: ChangeRegion[]; // Detailed per-region analysis
184
- severity: string; // Overall severity level
185
- diffPercentage: number; // Percentage of pixels that differ
186
- width: number; // Image width
187
- height: number; // Image height
188
- }
189
-
190
- interface ChangeRegion {
191
- bbox: BoundingBox; // Bounding box of the region
192
- pixelCount: number; // Number of changed pixels in this region
193
- percentage: number; // Percentage of image this region covers
194
- position: string; // Spatial position descriptor
195
- shape: string; // Shape classification
196
- shapeStats: ShapeStats; // Shape statistical analysis
197
- changeType: string; // Type of change detected
198
- signals: ClassificationSignals; // Classification signal details
199
- confidence: number; // Confidence level of classification
200
- colorDelta: ColorDeltaStats; // Color difference statistics
201
- gradient: GradientStats; // Gradient analysis statistics
202
- }
203
161
  ```
204
162
 
205
163
  ## Usage
@@ -223,31 +181,18 @@ if (result.match) {
223
181
  }
224
182
  ```
225
183
 
226
- ### Compare with Interpretation
227
-
228
- ```typescript
229
- import { compare } from '@blazediff/core-native';
230
-
231
- const result = await compare('expected.png', 'actual.png', 'diff.png', {
232
- threshold: 0.1,
233
- interpret: true,
234
- });
235
-
236
- if (!result.match && result.reason === 'pixel-diff') {
237
- const { interpretation } = result;
238
- console.log(interpretation.summary);
239
- for (const region of interpretation.regions) {
240
- console.log(`${region.position}: ${region.changeType} (${region.percentage.toFixed(2)}%)`);
241
- }
242
- }
243
- ```
184
+ ### Describing What Changed
244
185
 
245
- ### Interpret Only (no diff image)
186
+ This package answers *where* two images differ. For *what* changed — labelled
187
+ regions, change types, severity and a human-readable summary — use
188
+ [`@blazediff/interpret-native`](https://www.npmjs.com/package/@blazediff/interpret-native),
189
+ which classifies the same diff and can also locate regions with an SSIM map or
190
+ boxes you already have.
246
191
 
247
192
  ```typescript
248
- import { interpret } from '@blazediff/core-native';
193
+ import { interpret } from '@blazediff/interpret-native';
249
194
 
250
- const result = await interpret('expected.png', 'actual.png');
195
+ const result = await interpret('expected.png', 'actual.png', 'diff.png');
251
196
  console.log(result.summary);
252
197
  console.log(`Severity: ${result.severity}, ${result.diffPercentage.toFixed(2)}% changed`);
253
198
  ```
@@ -270,6 +215,9 @@ npx blazediff expected.png actual.png diff.qoi
270
215
  # With options
271
216
  npx blazediff expected.png actual.png diff.png --threshold 0.05 --antialiasing
272
217
 
218
+ # Score structural similarity instead of counting pixels, and pass at 0.99
219
+ npx blazediff expected.png actual.png ssim-map.png --metric ssim --min-score 0.99
220
+
273
221
  # With higher PNG compression (smaller output file, slower)
274
222
  npx blazediff expected.png actual.png diff.png -c 6
275
223
 
@@ -291,6 +239,9 @@ Arguments:
291
239
  [OUTPUT] Output diff image path (optional, format detected from extension)
292
240
 
293
241
  Options:
242
+ --metric <METRIC> pixel, ssim, ms-ssim or hitchhikers-ssim [default: pixel]
243
+ --min-score <SCORE> Score at or above which the ssim metrics call images identical [default: 1.0]
244
+ --ssim-window-size <N> Local window size for the ssim metrics [default: 11]
294
245
  -t, --threshold <THRESHOLD> Color difference threshold (0.0-1.0) [default: 0.1]
295
246
  -a, --antialiasing Enable anti-aliasing detection
296
247
  --diff-mask Output only differences (transparent background)
@@ -298,7 +249,6 @@ Options:
298
249
  -c, --compression <LEVEL> PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0]
299
250
  -q, --quality <QUALITY> JPEG quality (1-100) [default: 90]
300
251
  --output-format <FORMAT> Output format (json or text) [default: json]
301
- --interpret Generate diff output and structured interpretation
302
252
  -h, --help Print help
303
253
  -V, --version Print version
304
254
  ```
package/dist/index.d.ts CHANGED
@@ -11,86 +11,25 @@ interface BlazeDiffOptions {
11
11
  compression?: number;
12
12
  /** JPEG quality (1-100). Default: 90 */
13
13
  quality?: number;
14
- /** Run structured interpretation after raw pixel diff */
15
- interpret?: boolean;
16
14
  }
17
15
  /** File path or encoded PNG, JPEG, or QOI bytes. */
18
16
  type BlazeDiffInput = string | Uint8Array;
19
17
  type BlazeDiffResult = {
20
18
  match: true;
21
- interpretation?: InterpretResult;
22
19
  } | {
23
20
  match: false;
24
21
  reason: "layout-diff";
25
22
  } | {
26
23
  match: false;
27
24
  reason: "pixel-diff";
25
+ /** Differing pixels. */
28
26
  diffCount: number;
29
27
  diffPercentage: number;
30
- interpretation?: InterpretResult;
31
28
  } | {
32
29
  match: false;
33
30
  reason: "file-not-exists";
34
31
  file: string;
35
32
  };
36
- interface BoundingBox {
37
- x: number;
38
- y: number;
39
- width: number;
40
- height: number;
41
- }
42
- interface ShapeStats {
43
- fillRatio: number;
44
- borderRatio: number;
45
- innerFillRatio: number;
46
- centerDensity: number;
47
- rowOccupancy: number;
48
- colOccupancy: number;
49
- }
50
- interface ColorDeltaStats {
51
- meanDelta: number;
52
- maxDelta: number;
53
- deltaStddev: number;
54
- }
55
- interface GradientStats {
56
- edgeScore: number;
57
- edgeScoreImg2: number;
58
- edgeCorrelation: number;
59
- }
60
- interface ClassificationSignals {
61
- blendsWithBgInImg1: boolean;
62
- blendsWithBgInImg2: boolean;
63
- lowColorDelta: boolean;
64
- lowEdgeChange: boolean;
65
- denseFill: boolean;
66
- sparseFill: boolean;
67
- tinyRegion: boolean;
68
- edgesCorrelated: boolean;
69
- confidence: number;
70
- }
71
- interface ChangeRegion {
72
- bbox: BoundingBox;
73
- pixelCount: number;
74
- percentage: number;
75
- position: string;
76
- shape: string;
77
- shapeStats: ShapeStats;
78
- changeType: string;
79
- signals: ClassificationSignals;
80
- confidence: number;
81
- colorDelta: ColorDeltaStats;
82
- gradient: GradientStats;
83
- }
84
- interface InterpretResult {
85
- summary: string;
86
- diffCount: number;
87
- totalRegions: number;
88
- regions: ChangeRegion[];
89
- severity: string;
90
- diffPercentage: number;
91
- width: number;
92
- height: number;
93
- }
94
33
  /**
95
34
  * Compare two encoded images (PNG, JPEG, or QOI) and optionally generate a diff image.
96
35
  *
@@ -124,22 +63,5 @@ declare function getBinaryPath(): string;
124
63
  * Returns true if the native module loaded successfully.
125
64
  */
126
65
  declare function hasNativeBinding(): boolean;
127
- /**
128
- * Interpret the diff between two images, returning structured analysis results.
129
- *
130
- * Inputs must both be file paths or both be encoded byte arrays. Uses native
131
- * N-API bindings when available for better performance. Path inputs fall back
132
- * to execFile if native bindings are unavailable.
133
- *
134
- * @example
135
- * ```ts
136
- * const result = await interpret('expected.png', 'actual.png');
137
- * console.log(result.summary);
138
- * for (const region of result.regions) {
139
- * console.log(`${region.position}: ${region.changeType} (${region.percentage.toFixed(2)}%)`);
140
- * }
141
- * ```
142
- */
143
- declare function interpret(image1: BlazeDiffInput, image2: BlazeDiffInput, options?: Pick<BlazeDiffOptions, "threshold" | "antialiasing">): Promise<InterpretResult>;
144
66
 
145
- export { type BlazeDiffInput, type BlazeDiffOptions, type BlazeDiffResult, type BoundingBox, type ChangeRegion, type ClassificationSignals, type ColorDeltaStats, type GradientStats, type InterpretResult, type ShapeStats, compare, getBinaryPath, hasNativeBinding, interpret };
67
+ export { type BlazeDiffInput, type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath, hasNativeBinding };
package/dist/index.js CHANGED
@@ -32,8 +32,7 @@ var index_exports = {};
32
32
  __export(index_exports, {
33
33
  compare: () => compare,
34
34
  getBinaryPath: () => getBinaryPath,
35
- hasNativeBinding: () => hasNativeBinding,
36
- interpret: () => interpret
35
+ hasNativeBinding: () => hasNativeBinding
37
36
  });
38
37
  module.exports = __toCommonJS(index_exports);
39
38
 
@@ -131,9 +130,8 @@ function tryLoadNativeBinding() {
131
130
  return null;
132
131
  }
133
132
  function convertNapiResult(result) {
134
- const interpretation = result.interpretation ?? void 0;
135
133
  if (result.matchResult) {
136
- return { match: true, interpretation };
134
+ return { match: true };
137
135
  }
138
136
  if (result.reason === "layout-diff") {
139
137
  return { match: false, reason: "layout-diff" };
@@ -142,8 +140,7 @@ function convertNapiResult(result) {
142
140
  match: false,
143
141
  reason: "pixel-diff",
144
142
  diffCount: result.diffCount ?? 0,
145
- diffPercentage: result.diffPercentage ?? 0,
146
- interpretation
143
+ diffPercentage: result.diffPercentage ?? 0
147
144
  };
148
145
  }
149
146
  function convertToNapiOptions(options) {
@@ -153,8 +150,7 @@ function convertToNapiOptions(options) {
153
150
  diffMask: options?.diffMask,
154
151
  diffColorAlt: validateRgb(options?.diffColorAlt),
155
152
  compression: options?.compression,
156
- quality: options?.quality,
157
- interpret: options?.interpret
153
+ quality: options?.quality
158
154
  };
159
155
  }
160
156
  function resolveBinaryPath() {
@@ -203,9 +199,7 @@ function getBinaryPathInternal() {
203
199
  }
204
200
  function buildArgs(diffOutput, options) {
205
201
  const args = [];
206
- const useInterpret = options?.interpret ?? false;
207
202
  if (diffOutput) args.push(diffOutput);
208
- if (useInterpret) args.push("--interpret");
209
203
  args.push("--output-format=json");
210
204
  if (!options) return args;
211
205
  if (options.threshold !== void 0)
@@ -237,9 +231,6 @@ function detectMissingFile(error, basePath, comparePath) {
237
231
  async function execFileCompare(basePath, comparePath, diffOutput, options) {
238
232
  const binaryPath = getBinaryPathInternal();
239
233
  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
240
- if (options?.interpret) {
241
- return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
242
- }
243
234
  try {
244
235
  await execFileAsync(binaryPath, args);
245
236
  return { match: true };
@@ -272,35 +263,6 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
272
263
  throw new Error(output || `blazediff exited with code ${code}`);
273
264
  }
274
265
  }
275
- async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
276
- try {
277
- const { stdout } = await execFileAsync(binaryPath, args);
278
- const interpretation = JSON.parse(stdout);
279
- return { match: true, interpretation };
280
- } catch (err) {
281
- const { code, stdout, stderr } = err;
282
- if (code === 1 && stdout) {
283
- const interpretation = JSON.parse(stdout);
284
- return {
285
- match: false,
286
- reason: "pixel-diff",
287
- diffCount: interpretation.diffCount,
288
- diffPercentage: interpretation.diffPercentage,
289
- interpretation
290
- };
291
- }
292
- const errorOutput = stderr || stdout || "";
293
- if (code === 2) {
294
- const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
295
- if (missingFile) {
296
- return { match: false, reason: "file-not-exists", file: missingFile };
297
- }
298
- }
299
- throw new Error(
300
- errorOutput || `blazediff --interpret exited with code ${code}`
301
- );
302
- }
303
- }
304
266
  async function compare(base, comparison, diffOutput, options) {
305
267
  const baseIsPath = typeof base === "string";
306
268
  const comparisonIsPath = typeof comparison === "string";
@@ -350,29 +312,9 @@ function getBinaryPath() {
350
312
  function hasNativeBinding() {
351
313
  return tryLoadNativeBinding() !== null;
352
314
  }
353
- async function interpret(image1, image2, options) {
354
- const image1IsPath = typeof image1 === "string";
355
- const image2IsPath = typeof image2 === "string";
356
- const binding = tryLoadNativeBinding();
357
- if (binding && image1IsPath && image2IsPath) {
358
- return binding.interpretImages(image1, image2, {
359
- threshold: options?.threshold,
360
- antialiasing: options?.antialiasing
361
- });
362
- }
363
- const result = await compare(image1, image2, void 0, {
364
- ...options,
365
- interpret: true
366
- });
367
- if ("interpretation" in result && result.interpretation) {
368
- return result.interpretation;
369
- }
370
- throw new Error("Interpretation result missing from compare");
371
- }
372
315
  // Annotate the CommonJS export names for ESM import in node:
373
316
  0 && (module.exports = {
374
317
  compare,
375
318
  getBinaryPath,
376
- hasNativeBinding,
377
- interpret
319
+ hasNativeBinding
378
320
  });
package/dist/index.mjs CHANGED
@@ -88,9 +88,8 @@ function tryLoadNativeBinding() {
88
88
  return null;
89
89
  }
90
90
  function convertNapiResult(result) {
91
- const interpretation = result.interpretation ?? void 0;
92
91
  if (result.matchResult) {
93
- return { match: true, interpretation };
92
+ return { match: true };
94
93
  }
95
94
  if (result.reason === "layout-diff") {
96
95
  return { match: false, reason: "layout-diff" };
@@ -99,8 +98,7 @@ function convertNapiResult(result) {
99
98
  match: false,
100
99
  reason: "pixel-diff",
101
100
  diffCount: result.diffCount ?? 0,
102
- diffPercentage: result.diffPercentage ?? 0,
103
- interpretation
101
+ diffPercentage: result.diffPercentage ?? 0
104
102
  };
105
103
  }
106
104
  function convertToNapiOptions(options) {
@@ -110,8 +108,7 @@ function convertToNapiOptions(options) {
110
108
  diffMask: options?.diffMask,
111
109
  diffColorAlt: validateRgb(options?.diffColorAlt),
112
110
  compression: options?.compression,
113
- quality: options?.quality,
114
- interpret: options?.interpret
111
+ quality: options?.quality
115
112
  };
116
113
  }
117
114
  function resolveBinaryPath() {
@@ -160,9 +157,7 @@ function getBinaryPathInternal() {
160
157
  }
161
158
  function buildArgs(diffOutput, options) {
162
159
  const args = [];
163
- const useInterpret = options?.interpret ?? false;
164
160
  if (diffOutput) args.push(diffOutput);
165
- if (useInterpret) args.push("--interpret");
166
161
  args.push("--output-format=json");
167
162
  if (!options) return args;
168
163
  if (options.threshold !== void 0)
@@ -194,9 +189,6 @@ function detectMissingFile(error, basePath, comparePath) {
194
189
  async function execFileCompare(basePath, comparePath, diffOutput, options) {
195
190
  const binaryPath = getBinaryPathInternal();
196
191
  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
197
- if (options?.interpret) {
198
- return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
199
- }
200
192
  try {
201
193
  await execFileAsync(binaryPath, args);
202
194
  return { match: true };
@@ -229,35 +221,6 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
229
221
  throw new Error(output || `blazediff exited with code ${code}`);
230
222
  }
231
223
  }
232
- async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
233
- try {
234
- const { stdout } = await execFileAsync(binaryPath, args);
235
- const interpretation = JSON.parse(stdout);
236
- return { match: true, interpretation };
237
- } catch (err) {
238
- const { code, stdout, stderr } = err;
239
- if (code === 1 && stdout) {
240
- const interpretation = JSON.parse(stdout);
241
- return {
242
- match: false,
243
- reason: "pixel-diff",
244
- diffCount: interpretation.diffCount,
245
- diffPercentage: interpretation.diffPercentage,
246
- interpretation
247
- };
248
- }
249
- const errorOutput = stderr || stdout || "";
250
- if (code === 2) {
251
- const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
252
- if (missingFile) {
253
- return { match: false, reason: "file-not-exists", file: missingFile };
254
- }
255
- }
256
- throw new Error(
257
- errorOutput || `blazediff --interpret exited with code ${code}`
258
- );
259
- }
260
- }
261
224
  async function compare(base, comparison, diffOutput, options) {
262
225
  const baseIsPath = typeof base === "string";
263
226
  const comparisonIsPath = typeof comparison === "string";
@@ -307,28 +270,8 @@ function getBinaryPath() {
307
270
  function hasNativeBinding() {
308
271
  return tryLoadNativeBinding() !== null;
309
272
  }
310
- async function interpret(image1, image2, options) {
311
- const image1IsPath = typeof image1 === "string";
312
- const image2IsPath = typeof image2 === "string";
313
- const binding = tryLoadNativeBinding();
314
- if (binding && image1IsPath && image2IsPath) {
315
- return binding.interpretImages(image1, image2, {
316
- threshold: options?.threshold,
317
- antialiasing: options?.antialiasing
318
- });
319
- }
320
- const result = await compare(image1, image2, void 0, {
321
- ...options,
322
- interpret: true
323
- });
324
- if ("interpretation" in result && result.interpretation) {
325
- return result.interpretation;
326
- }
327
- throw new Error("Interpretation result missing from compare");
328
- }
329
273
  export {
330
274
  compare,
331
275
  getBinaryPath,
332
- hasNativeBinding,
333
- interpret
276
+ hasNativeBinding
334
277
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazediff/core-native",
3
- "version": "5.4.0",
3
+ "version": "6.0.0",
4
4
  "description": "Native Rust binaries for blazediff - the fastest image diff in the world",
5
5
  "private": false,
6
6
  "publishConfig": {
@@ -20,12 +20,12 @@
20
20
  "dist"
21
21
  ],
22
22
  "optionalDependencies": {
23
- "@blazediff/core-native-darwin-arm64": "5.4.0",
24
- "@blazediff/core-native-darwin-x64": "5.4.0",
25
- "@blazediff/core-native-linux-arm64": "5.4.0",
26
- "@blazediff/core-native-linux-x64": "5.4.0",
27
- "@blazediff/core-native-win32-arm64": "5.4.0",
28
- "@blazediff/core-native-win32-x64": "5.4.0"
23
+ "@blazediff/core-native-darwin-arm64": "6.0.0",
24
+ "@blazediff/core-native-darwin-x64": "6.0.0",
25
+ "@blazediff/core-native-linux-arm64": "6.0.0",
26
+ "@blazediff/core-native-linux-x64": "6.0.0",
27
+ "@blazediff/core-native-win32-arm64": "6.0.0",
28
+ "@blazediff/core-native-win32-x64": "6.0.0"
29
29
  },
30
30
  "keywords": [
31
31
  "image",