@blazediff/core-native 4.1.0 → 4.3.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
@@ -2,9 +2,9 @@
2
2
 
3
3
  <div align="center">
4
4
 
5
- [![npm bundle size](https://img.shields.io/bundlephobia/min/%40blazediff%2Fbin)](https://www.npmjs.com/package/@blazediff/core-native)
6
- [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fbin)](https://www.npmjs.com/package/@blazediff/core-native)
7
- [![Crates.io](https://img.shields.io/crates/v/blazediff.svg)](https://crates.io/crates/blazediff)
5
+ [![npm bundle size](https://img.shields.io/npm/unpacked-size/%40blazediff%2Fcore-native?style=flat-square)](https://www.npmjs.com/package/@blazediff/core-native)
6
+ [![NPM Downloads](https://img.shields.io/npm/dy/%40blazediff%2Fcore-native?style=flat-square)](https://www.npmjs.com/package/@blazediff/core-native)
7
+ [![Crates.io](https://img.shields.io/crates/v/blazediff.svg?style=flat-square)](https://crates.io/crates/blazediff)
8
8
 
9
9
  </div>
10
10
 
@@ -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
@@ -48,9 +48,12 @@ interface ShapeStats {
48
48
  interface ColorDeltaStats {
49
49
  meanDelta: number;
50
50
  maxDelta: number;
51
+ deltaStddev: number;
51
52
  }
52
53
  interface GradientStats {
53
54
  edgeScore: number;
55
+ edgeScoreImg2: number;
56
+ edgeCorrelation: number;
54
57
  }
55
58
  interface ClassificationSignals {
56
59
  blendsWithBgInImg1: boolean;
@@ -60,6 +63,7 @@ interface ClassificationSignals {
60
63
  denseFill: boolean;
61
64
  sparseFill: boolean;
62
65
  tinyRegion: boolean;
66
+ edgesCorrelated: boolean;
63
67
  confidence: number;
64
68
  }
65
69
  interface ChangeRegion {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazediff/core-native",
3
- "version": "4.1.0",
3
+ "version": "4.3.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.1.0",
24
- "@blazediff/core-native-darwin-x64": "4.1.0",
25
- "@blazediff/core-native-linux-arm64": "4.1.0",
26
- "@blazediff/core-native-linux-x64": "4.1.0",
27
- "@blazediff/core-native-win32-arm64": "4.1.0",
28
- "@blazediff/core-native-win32-x64": "4.1.0"
23
+ "@blazediff/core-native-darwin-arm64": "4.3.0",
24
+ "@blazediff/core-native-darwin-x64": "4.3.0",
25
+ "@blazediff/core-native-linux-arm64": "4.3.0",
26
+ "@blazediff/core-native-linux-x64": "4.3.0",
27
+ "@blazediff/core-native-win32-arm64": "4.3.0",
28
+ "@blazediff/core-native-win32-x64": "4.3.0"
29
29
  },
30
30
  "keywords": [
31
31
  "image",