@blazediff/core-native 4.0.0 → 4.2.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
@@ -102,16 +102,82 @@ Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detec
102
102
  <td>false</td>
103
103
  <td>Output only differences with transparent background</td>
104
104
  </tr>
105
+ <tr>
106
+ <td><code>interpret</code></td>
107
+ <td>boolean</td>
108
+ <td>false</td>
109
+ <td>Run structured interpretation after diff — adds <code>interpretation</code> to the result with detected change regions, classification, and a human-readable summary</td>
110
+ </tr>
111
+ <tr>
112
+ <td><code>outputFormat</code></td>
113
+ <td>"png" | "html"</td>
114
+ <td>"png"</td>
115
+ <td>Output format for diff. Use <code>"html"</code> to generate an interpret report (implies <code>interpret: true</code>)</td>
116
+ </tr>
105
117
  </table>
106
118
 
119
+ ### interpret(image1Path, image2Path, options?)
120
+
121
+ Convenience wrapper that calls `compare` with `interpret: true` and returns the `InterpretResult` directly. No diff image output — purely analytical.
122
+
123
+ <table>
124
+ <tr>
125
+ <th width="500">Parameter</th>
126
+ <th width="500">Type</th>
127
+ <th width="500">Description</th>
128
+ </tr>
129
+ <tr>
130
+ <td><code>image1Path</code></td>
131
+ <td>string</td>
132
+ <td>Path to the first image</td>
133
+ </tr>
134
+ <tr>
135
+ <td><code>image2Path</code></td>
136
+ <td>string</td>
137
+ <td>Path to the second image</td>
138
+ </tr>
139
+ <tr>
140
+ <td><code>options</code></td>
141
+ <td>Pick&lt;BlazeDiffOptions, "threshold" | "antialiasing"&gt;</td>
142
+ <td>Comparison options (optional)</td>
143
+ </tr>
144
+ </table>
145
+
146
+ <strong>Returns:</strong> `Promise<InterpretResult>`
147
+
107
148
  ### Result Types
108
149
 
109
150
  ```typescript
110
151
  type BlazeDiffResult =
111
- | { match: true }
152
+ | { match: true; interpretation?: InterpretResult }
112
153
  | { match: false; reason: "layout-diff" }
113
- | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number }
154
+ | { match: false; reason: "pixel-diff"; diffCount: number; diffPercentage: number; interpretation?: InterpretResult }
114
155
  | { match: false; reason: "file-not-exists"; file: string };
156
+
157
+ interface InterpretResult {
158
+ summary: string; // Human-readable summary of the diff
159
+ diffCount: number; // Total number of differing pixels
160
+ totalRegions: number; // Number of detected change regions
161
+ regions: ChangeRegion[]; // Detailed per-region analysis
162
+ severity: string; // Overall severity level
163
+ diffPercentage: number; // Percentage of pixels that differ
164
+ width: number; // Image width
165
+ height: number; // Image height
166
+ }
167
+
168
+ interface ChangeRegion {
169
+ bbox: BoundingBox; // Bounding box of the region
170
+ pixelCount: number; // Number of changed pixels in this region
171
+ percentage: number; // Percentage of image this region covers
172
+ position: string; // Spatial position descriptor
173
+ shape: string; // Shape classification
174
+ shapeStats: ShapeStats; // Shape statistical analysis
175
+ changeType: string; // Type of change detected
176
+ signals: ClassificationSignals; // Classification signal details
177
+ confidence: number; // Confidence level of classification
178
+ colorDelta: ColorDeltaStats; // Color difference statistics
179
+ gradient: GradientStats; // Gradient analysis statistics
180
+ }
115
181
  ```
116
182
 
117
183
  ## Usage
@@ -135,6 +201,35 @@ if (result.match) {
135
201
  }
136
202
  ```
137
203
 
204
+ ### Compare with Interpretation
205
+
206
+ ```typescript
207
+ import { compare } from '@blazediff/core-native';
208
+
209
+ const result = await compare('expected.png', 'actual.png', 'diff.png', {
210
+ threshold: 0.1,
211
+ interpret: true,
212
+ });
213
+
214
+ if (!result.match && result.reason === 'pixel-diff') {
215
+ const { interpretation } = result;
216
+ console.log(interpretation.summary);
217
+ for (const region of interpretation.regions) {
218
+ console.log(`${region.position}: ${region.changeType} (${region.percentage.toFixed(2)}%)`);
219
+ }
220
+ }
221
+ ```
222
+
223
+ ### Interpret Only (no diff image)
224
+
225
+ ```typescript
226
+ import { interpret } from '@blazediff/core-native';
227
+
228
+ const result = await interpret('expected.png', 'actual.png');
229
+ console.log(result.summary);
230
+ console.log(`Severity: ${result.severity}, ${result.diffPercentage.toFixed(2)}% changed`);
231
+ ```
232
+
138
233
  ### CLI Usage
139
234
 
140
235
  ```bash
package/dist/index.d.ts CHANGED
@@ -9,9 +9,14 @@ interface BlazeDiffOptions {
9
9
  compression?: number;
10
10
  /** JPEG quality (1-100). Default: 90 */
11
11
  quality?: number;
12
+ /** Run structured interpretation after raw pixel diff */
13
+ interpret?: boolean;
14
+ /** Output format for diff: "png" (default) or "html" (interpret report) */
15
+ outputFormat?: "png" | "html";
12
16
  }
13
17
  type BlazeDiffResult = {
14
18
  match: true;
19
+ interpretation?: InterpretResult;
15
20
  } | {
16
21
  match: false;
17
22
  reason: "layout-diff";
@@ -20,11 +25,70 @@ type BlazeDiffResult = {
20
25
  reason: "pixel-diff";
21
26
  diffCount: number;
22
27
  diffPercentage: number;
28
+ interpretation?: InterpretResult;
23
29
  } | {
24
30
  match: false;
25
31
  reason: "file-not-exists";
26
32
  file: string;
27
33
  };
34
+ interface BoundingBox {
35
+ x: number;
36
+ y: number;
37
+ width: number;
38
+ height: number;
39
+ }
40
+ interface ShapeStats {
41
+ fillRatio: number;
42
+ borderRatio: number;
43
+ innerFillRatio: number;
44
+ centerDensity: number;
45
+ rowOccupancy: number;
46
+ colOccupancy: number;
47
+ }
48
+ interface ColorDeltaStats {
49
+ meanDelta: number;
50
+ maxDelta: number;
51
+ deltaStddev: number;
52
+ }
53
+ interface GradientStats {
54
+ edgeScore: number;
55
+ edgeScoreImg2: number;
56
+ edgeCorrelation: number;
57
+ }
58
+ interface ClassificationSignals {
59
+ blendsWithBgInImg1: boolean;
60
+ blendsWithBgInImg2: boolean;
61
+ lowColorDelta: boolean;
62
+ lowEdgeChange: boolean;
63
+ denseFill: boolean;
64
+ sparseFill: boolean;
65
+ tinyRegion: boolean;
66
+ edgesCorrelated: boolean;
67
+ confidence: number;
68
+ }
69
+ interface ChangeRegion {
70
+ bbox: BoundingBox;
71
+ pixelCount: number;
72
+ percentage: number;
73
+ position: string;
74
+ shape: string;
75
+ shapeStats: ShapeStats;
76
+ changeType: string;
77
+ signals: ClassificationSignals;
78
+ confidence: number;
79
+ colorDelta: ColorDeltaStats;
80
+ gradient: GradientStats;
81
+ }
82
+ interface InterpretResult {
83
+ summary: string;
84
+ diffCount: number;
85
+ totalRegions: number;
86
+ regions: ChangeRegion[];
87
+ severity: string;
88
+ diffPercentage: number;
89
+ width: number;
90
+ height: number;
91
+ }
28
92
  /**
29
93
  * Compare two images (PNG or JPEG) and optionally generate a diff image.
30
94
  *
@@ -55,5 +119,21 @@ declare function getBinaryPath(): string;
55
119
  * Returns true if the native module loaded successfully.
56
120
  */
57
121
  declare function hasNativeBinding(): boolean;
122
+ /**
123
+ * Interpret the diff between two images, returning structured analysis results.
124
+ *
125
+ * Uses native N-API bindings when available for better performance.
126
+ * Falls back to execFile if native bindings are unavailable.
127
+ *
128
+ * @example
129
+ * ```ts
130
+ * const result = await interpret('expected.png', 'actual.png');
131
+ * console.log(result.summary);
132
+ * for (const region of result.regions) {
133
+ * console.log(`${region.position}: ${region.changeType} (${region.percentage.toFixed(2)}%)`);
134
+ * }
135
+ * ```
136
+ */
137
+ declare function interpret(image1Path: string, image2Path: string, options?: Pick<BlazeDiffOptions, "threshold" | "antialiasing">): Promise<InterpretResult>;
58
138
 
59
- export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath, hasNativeBinding };
139
+ export { type BlazeDiffOptions, type BlazeDiffResult, type BoundingBox, type ChangeRegion, type ClassificationSignals, type ColorDeltaStats, type GradientStats, type InterpretResult, type ShapeStats, compare, getBinaryPath, hasNativeBinding, interpret };
package/dist/index.js CHANGED
@@ -32,7 +32,8 @@ var index_exports = {};
32
32
  __export(index_exports, {
33
33
  compare: () => compare,
34
34
  getBinaryPath: () => getBinaryPath,
35
- hasNativeBinding: () => hasNativeBinding
35
+ hasNativeBinding: () => hasNativeBinding,
36
+ interpret: () => interpret
36
37
  });
37
38
  module.exports = __toCommonJS(index_exports);
38
39
 
@@ -119,25 +120,19 @@ function tryLoadNativeBinding() {
119
120
  return null;
120
121
  }
121
122
  function convertNapiResult(result) {
123
+ const interpretation = result.interpretation ?? void 0;
122
124
  if (result.matchResult) {
123
- return { match: true };
125
+ return { match: true, interpretation };
124
126
  }
125
127
  if (result.reason === "layout-diff") {
126
128
  return { match: false, reason: "layout-diff" };
127
129
  }
128
- if (result.reason === "pixel-diff") {
129
- return {
130
- match: false,
131
- reason: "pixel-diff",
132
- diffCount: result.diffCount ?? 0,
133
- diffPercentage: result.diffPercentage ?? 0
134
- };
135
- }
136
130
  return {
137
131
  match: false,
138
132
  reason: "pixel-diff",
139
133
  diffCount: result.diffCount ?? 0,
140
- diffPercentage: result.diffPercentage ?? 0
134
+ diffPercentage: result.diffPercentage ?? 0,
135
+ interpretation
141
136
  };
142
137
  }
143
138
  function convertToNapiOptions(options) {
@@ -146,7 +141,9 @@ function convertToNapiOptions(options) {
146
141
  antialiasing: options?.antialiasing,
147
142
  diffMask: options?.diffMask,
148
143
  compression: options?.compression,
149
- quality: options?.quality
144
+ quality: options?.quality,
145
+ interpret: options?.interpret,
146
+ outputFormat: options?.outputFormat
150
147
  };
151
148
  }
152
149
  function resolveBinaryPath() {
@@ -195,16 +192,21 @@ function getBinaryPathInternal() {
195
192
  }
196
193
  function buildArgs(diffOutput, options) {
197
194
  const args = [];
195
+ const useInterpret = options?.interpret || options?.outputFormat === "html";
198
196
  if (diffOutput) args.push(diffOutput);
197
+ if (useInterpret) args.push("--interpret");
199
198
  args.push("--output-format=json");
200
199
  if (!options) return args;
201
200
  if (options.threshold !== void 0)
202
201
  args.push(`--threshold=${options.threshold}`);
203
202
  if (options.antialiasing) args.push("--antialiasing");
204
- if (options.diffMask) args.push("--diff-mask");
205
- if (options.compression !== void 0)
206
- args.push(`--compression=${options.compression}`);
207
- if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
203
+ if (!useInterpret) {
204
+ if (options.diffMask) args.push("--diff-mask");
205
+ if (options.compression !== void 0)
206
+ args.push(`--compression=${options.compression}`);
207
+ if (options.quality !== void 0)
208
+ args.push(`--quality=${options.quality}`);
209
+ }
208
210
  return args;
209
211
  }
210
212
  function parseJsonOutput(text) {
@@ -225,6 +227,9 @@ function detectMissingFile(error, basePath, comparePath) {
225
227
  async function execFileCompare(basePath, comparePath, diffOutput, options) {
226
228
  const binaryPath = getBinaryPathInternal();
227
229
  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
230
+ if (options?.interpret || options?.outputFormat === "html") {
231
+ return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
232
+ }
228
233
  try {
229
234
  await execFileAsync(binaryPath, args);
230
235
  return { match: true };
@@ -257,6 +262,35 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
257
262
  throw new Error(output || `blazediff exited with code ${code}`);
258
263
  }
259
264
  }
265
+ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
266
+ try {
267
+ const { stdout } = await execFileAsync(binaryPath, args);
268
+ const interpretation = JSON.parse(stdout);
269
+ return { match: true, interpretation };
270
+ } catch (err) {
271
+ const { code, stdout, stderr } = err;
272
+ if (code === 1 && stdout) {
273
+ const interpretation = JSON.parse(stdout);
274
+ return {
275
+ match: false,
276
+ reason: "pixel-diff",
277
+ diffCount: interpretation.diffCount,
278
+ diffPercentage: interpretation.diffPercentage,
279
+ interpretation
280
+ };
281
+ }
282
+ const errorOutput = stderr || stdout || "";
283
+ if (code === 2) {
284
+ const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
285
+ if (missingFile) {
286
+ return { match: false, reason: "file-not-exists", file: missingFile };
287
+ }
288
+ }
289
+ throw new Error(
290
+ errorOutput || `blazediff --interpret exited with code ${code}`
291
+ );
292
+ }
293
+ }
260
294
  async function compare(basePath, comparePath, diffOutput, options) {
261
295
  const binding = tryLoadNativeBinding();
262
296
  if (binding) {
@@ -285,9 +319,27 @@ function getBinaryPath() {
285
319
  function hasNativeBinding() {
286
320
  return tryLoadNativeBinding() !== null;
287
321
  }
322
+ async function interpret(image1Path, image2Path, options) {
323
+ const binding = tryLoadNativeBinding();
324
+ if (binding) {
325
+ return binding.interpretImages(image1Path, image2Path, {
326
+ threshold: options?.threshold,
327
+ antialiasing: options?.antialiasing
328
+ });
329
+ }
330
+ const result = await compare(image1Path, image2Path, void 0, {
331
+ ...options,
332
+ interpret: true
333
+ });
334
+ if ("interpretation" in result && result.interpretation) {
335
+ return result.interpretation;
336
+ }
337
+ throw new Error("Interpretation result missing from compare");
338
+ }
288
339
  // Annotate the CommonJS export names for ESM import in node:
289
340
  0 && (module.exports = {
290
341
  compare,
291
342
  getBinaryPath,
292
- hasNativeBinding
343
+ hasNativeBinding,
344
+ interpret
293
345
  });
package/dist/index.mjs CHANGED
@@ -77,25 +77,19 @@ function tryLoadNativeBinding() {
77
77
  return null;
78
78
  }
79
79
  function convertNapiResult(result) {
80
+ const interpretation = result.interpretation ?? void 0;
80
81
  if (result.matchResult) {
81
- return { match: true };
82
+ return { match: true, interpretation };
82
83
  }
83
84
  if (result.reason === "layout-diff") {
84
85
  return { match: false, reason: "layout-diff" };
85
86
  }
86
- if (result.reason === "pixel-diff") {
87
- return {
88
- match: false,
89
- reason: "pixel-diff",
90
- diffCount: result.diffCount ?? 0,
91
- diffPercentage: result.diffPercentage ?? 0
92
- };
93
- }
94
87
  return {
95
88
  match: false,
96
89
  reason: "pixel-diff",
97
90
  diffCount: result.diffCount ?? 0,
98
- diffPercentage: result.diffPercentage ?? 0
91
+ diffPercentage: result.diffPercentage ?? 0,
92
+ interpretation
99
93
  };
100
94
  }
101
95
  function convertToNapiOptions(options) {
@@ -104,7 +98,9 @@ function convertToNapiOptions(options) {
104
98
  antialiasing: options?.antialiasing,
105
99
  diffMask: options?.diffMask,
106
100
  compression: options?.compression,
107
- quality: options?.quality
101
+ quality: options?.quality,
102
+ interpret: options?.interpret,
103
+ outputFormat: options?.outputFormat
108
104
  };
109
105
  }
110
106
  function resolveBinaryPath() {
@@ -153,16 +149,21 @@ function getBinaryPathInternal() {
153
149
  }
154
150
  function buildArgs(diffOutput, options) {
155
151
  const args = [];
152
+ const useInterpret = options?.interpret || options?.outputFormat === "html";
156
153
  if (diffOutput) args.push(diffOutput);
154
+ if (useInterpret) args.push("--interpret");
157
155
  args.push("--output-format=json");
158
156
  if (!options) return args;
159
157
  if (options.threshold !== void 0)
160
158
  args.push(`--threshold=${options.threshold}`);
161
159
  if (options.antialiasing) args.push("--antialiasing");
162
- if (options.diffMask) args.push("--diff-mask");
163
- if (options.compression !== void 0)
164
- args.push(`--compression=${options.compression}`);
165
- if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
160
+ if (!useInterpret) {
161
+ if (options.diffMask) args.push("--diff-mask");
162
+ if (options.compression !== void 0)
163
+ args.push(`--compression=${options.compression}`);
164
+ if (options.quality !== void 0)
165
+ args.push(`--quality=${options.quality}`);
166
+ }
166
167
  return args;
167
168
  }
168
169
  function parseJsonOutput(text) {
@@ -183,6 +184,9 @@ function detectMissingFile(error, basePath, comparePath) {
183
184
  async function execFileCompare(basePath, comparePath, diffOutput, options) {
184
185
  const binaryPath = getBinaryPathInternal();
185
186
  const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
187
+ if (options?.interpret || options?.outputFormat === "html") {
188
+ return execFileInterpretCompare(binaryPath, args, basePath, comparePath);
189
+ }
186
190
  try {
187
191
  await execFileAsync(binaryPath, args);
188
192
  return { match: true };
@@ -215,6 +219,35 @@ async function execFileCompare(basePath, comparePath, diffOutput, options) {
215
219
  throw new Error(output || `blazediff exited with code ${code}`);
216
220
  }
217
221
  }
222
+ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath) {
223
+ try {
224
+ const { stdout } = await execFileAsync(binaryPath, args);
225
+ const interpretation = JSON.parse(stdout);
226
+ return { match: true, interpretation };
227
+ } catch (err) {
228
+ const { code, stdout, stderr } = err;
229
+ if (code === 1 && stdout) {
230
+ const interpretation = JSON.parse(stdout);
231
+ return {
232
+ match: false,
233
+ reason: "pixel-diff",
234
+ diffCount: interpretation.diffCount,
235
+ diffPercentage: interpretation.diffPercentage,
236
+ interpretation
237
+ };
238
+ }
239
+ const errorOutput = stderr || stdout || "";
240
+ if (code === 2) {
241
+ const missingFile = detectMissingFile(errorOutput, basePath, comparePath);
242
+ if (missingFile) {
243
+ return { match: false, reason: "file-not-exists", file: missingFile };
244
+ }
245
+ }
246
+ throw new Error(
247
+ errorOutput || `blazediff --interpret exited with code ${code}`
248
+ );
249
+ }
250
+ }
218
251
  async function compare(basePath, comparePath, diffOutput, options) {
219
252
  const binding = tryLoadNativeBinding();
220
253
  if (binding) {
@@ -243,8 +276,26 @@ function getBinaryPath() {
243
276
  function hasNativeBinding() {
244
277
  return tryLoadNativeBinding() !== null;
245
278
  }
279
+ async function interpret(image1Path, image2Path, options) {
280
+ const binding = tryLoadNativeBinding();
281
+ if (binding) {
282
+ return binding.interpretImages(image1Path, image2Path, {
283
+ threshold: options?.threshold,
284
+ antialiasing: options?.antialiasing
285
+ });
286
+ }
287
+ const result = await compare(image1Path, image2Path, void 0, {
288
+ ...options,
289
+ interpret: true
290
+ });
291
+ if ("interpretation" in result && result.interpretation) {
292
+ return result.interpretation;
293
+ }
294
+ throw new Error("Interpretation result missing from compare");
295
+ }
246
296
  export {
247
297
  compare,
248
298
  getBinaryPath,
249
- hasNativeBinding
299
+ hasNativeBinding,
300
+ interpret
250
301
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazediff/core-native",
3
- "version": "4.0.0",
3
+ "version": "4.2.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": "4.0.0",
24
- "@blazediff/core-native-darwin-x64": "4.0.0",
25
- "@blazediff/core-native-linux-arm64": "4.0.0",
26
- "@blazediff/core-native-linux-x64": "4.0.0",
27
- "@blazediff/core-native-win32-arm64": "4.0.0",
28
- "@blazediff/core-native-win32-x64": "4.0.0"
23
+ "@blazediff/core-native-darwin-arm64": "4.2.0",
24
+ "@blazediff/core-native-darwin-x64": "4.2.0",
25
+ "@blazediff/core-native-linux-arm64": "4.2.0",
26
+ "@blazediff/core-native-linux-x64": "4.2.0",
27
+ "@blazediff/core-native-win32-arm64": "4.2.0",
28
+ "@blazediff/core-native-win32-x64": "4.2.0"
29
29
  },
30
30
  "keywords": [
31
31
  "image",