@ericblade/quagga2 1.10.2 → 1.11.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/DEPENDENCIES.md +4 -13
- package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
- package/README.md +111 -8
- package/dist/quagga.js +702 -250
- package/dist/quagga.min.js +4 -4
- package/docs/_config.yml +3 -0
- package/docs/assets/bb-binary.png +0 -0
- package/docs/assets/bb-rotated.png +0 -0
- package/docs/assets/binary.png +0 -0
- package/docs/assets/component-labeling-line.png +0 -0
- package/docs/assets/component-labeling-text.png +0 -0
- package/docs/assets/component-labeling.png +0 -0
- package/docs/assets/connected-patch-labels.png +0 -0
- package/docs/assets/mobile-detected.png +0 -0
- package/docs/assets/mobile-located.png +0 -0
- package/docs/assets/patches_found.png +0 -0
- package/docs/assets/quaggaJS-code128.png +0 -0
- package/docs/assets/remaining-patch-labels.png +0 -0
- package/docs/assets/skeleton.png +0 -0
- package/docs/assets/teaser.png +0 -0
- package/docs/contributing.md +102 -0
- package/docs/explanation/algorithm-overview.md +69 -0
- package/docs/explanation/architecture.md +117 -0
- package/docs/explanation/how-barcode-localization-works.md +197 -0
- package/docs/explanation/index.md +80 -0
- package/docs/explanation/input-streams.md +270 -0
- package/docs/getting-started.md +213 -0
- package/docs/how-to-guides/configure-readers.md +79 -0
- package/docs/how-to-guides/external-readers.md +234 -0
- package/docs/how-to-guides/handle-difficult-barcodes.md +127 -0
- package/docs/how-to-guides/index.md +77 -0
- package/docs/how-to-guides/optimize-performance.md +114 -0
- package/docs/how-to-guides/tips-and-tricks.md +115 -0
- package/docs/how-to-guides/use-debug-flags.md +776 -0
- package/docs/how-to-guides/working-with-coordinates.md +254 -0
- package/docs/index.md +118 -0
- package/docs/reference/api.md +716 -0
- package/docs/reference/browser-support.md +109 -0
- package/docs/reference/camera-access.md +376 -0
- package/docs/reference/configuration.md +1008 -0
- package/docs/reference/dependencies.md +295 -0
- package/docs/reference/index.md +74 -0
- package/docs/reference/readers.md +261 -0
- package/docs/tutorials/first-scan.md +141 -0
- package/docs/tutorials/index.md +77 -0
- package/docs/tutorials/node-usage.md +182 -0
- package/docs/tutorials/react-integration.md +176 -0
- package/docs/tutorials/static-image.md +130 -0
- package/lib/quagga.js +645 -265
- package/package.json +14 -11
- package/type-definitions/quagga.d.ts +86 -9
|
@@ -0,0 +1,716 @@
|
|
|
1
|
+
# API Documentation {#api-documentation}
|
|
2
|
+
|
|
3
|
+
Complete reference for all Quagga2 methods, callbacks, and events.
|
|
4
|
+
|
|
5
|
+
## Core Methods {#core-methods}
|
|
6
|
+
|
|
7
|
+
### `Quagga.init(config, callback)` {#quagga-init}
|
|
8
|
+
|
|
9
|
+
Initializes the library with the given configuration and requests camera access if using live stream mode.
|
|
10
|
+
|
|
11
|
+
**Parameters**:
|
|
12
|
+
|
|
13
|
+
- `config` (Object) - Configuration object. See [Configuration Reference](configuration.md) for complete details.
|
|
14
|
+
- `callback` (Function) - Called when initialization completes: `callback(err)`
|
|
15
|
+
- `err` (Error | null) - Error object if initialization failed, `null` on success
|
|
16
|
+
|
|
17
|
+
**Returns**: `void`
|
|
18
|
+
|
|
19
|
+
**Example - Live Camera**:
|
|
20
|
+
|
|
21
|
+
```javascript
|
|
22
|
+
Quagga.init({
|
|
23
|
+
inputStream: {
|
|
24
|
+
type: "LiveStream",
|
|
25
|
+
target: document.querySelector('#scanner') // Or '#scanner'
|
|
26
|
+
},
|
|
27
|
+
decoder: {
|
|
28
|
+
readers: ["code_128_reader"]
|
|
29
|
+
}
|
|
30
|
+
}, function(err) {
|
|
31
|
+
if (err) {
|
|
32
|
+
console.error("Initialization failed:", err);
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
console.log("Initialization successful, ready to start");
|
|
36
|
+
Quagga.start();
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**Example - Static Images**:
|
|
41
|
+
|
|
42
|
+
```javascript
|
|
43
|
+
Quagga.init({
|
|
44
|
+
inputStream: {
|
|
45
|
+
type: "ImageStream",
|
|
46
|
+
src: "/path/to/images/*.jpg",
|
|
47
|
+
target: document.querySelector('#scanner')
|
|
48
|
+
},
|
|
49
|
+
decoder: {
|
|
50
|
+
readers: ["ean_reader", "code_128_reader"]
|
|
51
|
+
}
|
|
52
|
+
}, function(err) {
|
|
53
|
+
if (err) {
|
|
54
|
+
console.error(err);
|
|
55
|
+
return;
|
|
56
|
+
}
|
|
57
|
+
Quagga.start();
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**Error Handling**:
|
|
62
|
+
|
|
63
|
+
The callback receives an `err` parameter if initialization fails. Common causes:
|
|
64
|
+
|
|
65
|
+
- User denies camera permission
|
|
66
|
+
- No camera device found
|
|
67
|
+
- Browser doesn't support required APIs
|
|
68
|
+
- Invalid configuration parameters
|
|
69
|
+
|
|
70
|
+
Always check for errors before calling `start()`:
|
|
71
|
+
|
|
72
|
+
**Target Element**:
|
|
73
|
+
|
|
74
|
+
If no `target` is specified, Quagga looks for an element matching the CSS selector `#interactive.viewport` (for backwards compatibility).
|
|
75
|
+
|
|
76
|
+
### `Quagga.start()` {#quagga-start}
|
|
77
|
+
|
|
78
|
+
Starts the video stream and begins locating and decoding barcodes.
|
|
79
|
+
|
|
80
|
+
**Parameters**: None
|
|
81
|
+
|
|
82
|
+
**Returns**: `void`
|
|
83
|
+
|
|
84
|
+
**Example**:
|
|
85
|
+
|
|
86
|
+
```javascript
|
|
87
|
+
Quagga.init(config, function(err) {
|
|
88
|
+
if (!err) {
|
|
89
|
+
Quagga.start();
|
|
90
|
+
}
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Prerequisites**:
|
|
95
|
+
|
|
96
|
+
- `Quagga.init()` must have completed successfully
|
|
97
|
+
- For live stream: Camera permission must be granted
|
|
98
|
+
|
|
99
|
+
**Note**: Call this in the `init()` callback after checking for errors.
|
|
100
|
+
|
|
101
|
+
### `Quagga.stop()` {#quagga-stop}
|
|
102
|
+
|
|
103
|
+
Stops the decoder from processing images and disconnects the camera if one was requested.
|
|
104
|
+
|
|
105
|
+
**Parameters**: None
|
|
106
|
+
|
|
107
|
+
**Returns**: `Promise<void>` - Resolves when cleanup is complete
|
|
108
|
+
|
|
109
|
+
**Example**:
|
|
110
|
+
|
|
111
|
+
```javascript
|
|
112
|
+
// Stop scanning
|
|
113
|
+
await Quagga.stop();
|
|
114
|
+
console.log("Scanner stopped");
|
|
115
|
+
|
|
116
|
+
// Or with .then()
|
|
117
|
+
Quagga.stop().then(() => {
|
|
118
|
+
console.log("Scanner stopped");
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
**Behavior**:
|
|
123
|
+
|
|
124
|
+
- Stops processing new frames
|
|
125
|
+
- If using live camera: disconnects and releases camera
|
|
126
|
+
- Does not remove event listeners (use `offDetected()` / `offProcessed()` for that)
|
|
127
|
+
- Returns a Promise that resolves when camera release is complete
|
|
128
|
+
|
|
129
|
+
### `Quagga.onDetected(callback)` {#quagga-ondetected}
|
|
130
|
+
|
|
131
|
+
Registers a callback that is triggered when a barcode is successfully located and decoded.
|
|
132
|
+
|
|
133
|
+
**Parameters**:
|
|
134
|
+
|
|
135
|
+
- `callback` (Function) - Handler function: `callback(data)`
|
|
136
|
+
- `data` (Object) - Result object containing decoded barcode information
|
|
137
|
+
|
|
138
|
+
**Returns**: `void`
|
|
139
|
+
|
|
140
|
+
**Example**:
|
|
141
|
+
|
|
142
|
+
```javascript
|
|
143
|
+
Quagga.onDetected(function(result) {
|
|
144
|
+
const code = result.codeResult.code;
|
|
145
|
+
const format = result.codeResult.format;
|
|
146
|
+
|
|
147
|
+
console.log(`Detected ${format} barcode: ${code}`);
|
|
148
|
+
|
|
149
|
+
// Process the barcode
|
|
150
|
+
processBarcode(code);
|
|
151
|
+
});
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
**Multiple Handlers**:
|
|
155
|
+
|
|
156
|
+
You can register multiple handlers - all will be called:
|
|
157
|
+
|
|
158
|
+
```javascript
|
|
159
|
+
Quagga.onDetected(handler1);
|
|
160
|
+
Quagga.onDetected(handler2); // Both execute on detection
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### `Quagga.onProcessed(callback)` {#quagga-onprocessed}
|
|
164
|
+
|
|
165
|
+
Registers a callback that is called for each processed frame, regardless of detection success.
|
|
166
|
+
|
|
167
|
+
**Parameters**:
|
|
168
|
+
|
|
169
|
+
- `callback` (Function) - Handler function: `callback(data)`
|
|
170
|
+
- `data` (Object) - Processing result with detailed information
|
|
171
|
+
|
|
172
|
+
**Returns**: `void`
|
|
173
|
+
|
|
174
|
+
**Example**:
|
|
175
|
+
|
|
176
|
+
```javascript
|
|
177
|
+
Quagga.onProcessed(function(result) {
|
|
178
|
+
const drawingCtx = Quagga.canvas.ctx.overlay;
|
|
179
|
+
const drawingCanvas = Quagga.canvas.dom.overlay;
|
|
180
|
+
|
|
181
|
+
if (result) {
|
|
182
|
+
// Draw boxes and lines for visualization
|
|
183
|
+
if (result.boxes) {
|
|
184
|
+
drawingCtx.clearRect(0, 0,
|
|
185
|
+
drawingCanvas.width, drawingCanvas.height);
|
|
186
|
+
|
|
187
|
+
result.boxes.forEach(function(box) {
|
|
188
|
+
Quagga.ImageDebug.drawPath(box, {x: 0, y: 1},
|
|
189
|
+
drawingCtx, {color: "blue", lineWidth: 2});
|
|
190
|
+
});
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
if (result.box) {
|
|
194
|
+
Quagga.ImageDebug.drawPath(result.box, {x: 0, y: 1},
|
|
195
|
+
drawingCtx, {color: "green", lineWidth: 2});
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
if (result.codeResult && result.codeResult.code) {
|
|
199
|
+
// Successfully decoded
|
|
200
|
+
console.log("Code detected:", result.codeResult.code);
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
});
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
**Use Cases**:
|
|
207
|
+
|
|
208
|
+
- Custom visualization of detection process
|
|
209
|
+
- Counting processed frames
|
|
210
|
+
- Performance monitoring
|
|
211
|
+
- Drawing custom overlays
|
|
212
|
+
|
|
213
|
+
### `Quagga.drawScannerArea()` {#quagga-drawscannerarea}
|
|
214
|
+
|
|
215
|
+
Manually draws the scanner area overlay on the overlay canvas using the configured `inputStream.area`.
|
|
216
|
+
|
|
217
|
+
**Parameters**: None (uses the area configuration from `Quagga.init()`)
|
|
218
|
+
|
|
219
|
+
**Returns**: `void`
|
|
220
|
+
|
|
221
|
+
**Behavior**:
|
|
222
|
+
|
|
223
|
+
- Only draws when `locate` is `false` and `inputStream.area` is configured with styling
|
|
224
|
+
- Uses the actual adjusted scanning area (after patch alignment) to accurately match where barcodes will be detected
|
|
225
|
+
- Automatically accounts for the area offset and dimensions
|
|
226
|
+
- Skips drawing if no styling is provided (no `borderColor`, `borderWidth`, or `backgroundColor`)
|
|
227
|
+
- Requires `canvas.createOverlay: true` so the overlay canvas exists
|
|
228
|
+
- Drawing occurs automatically every processed frame when conditions are met
|
|
229
|
+
|
|
230
|
+
**Example**:
|
|
231
|
+
|
|
232
|
+
```javascript
|
|
233
|
+
// Configure area during init
|
|
234
|
+
Quagga.init({
|
|
235
|
+
inputStream: {
|
|
236
|
+
area: {
|
|
237
|
+
top: "30%",
|
|
238
|
+
right: "10%",
|
|
239
|
+
bottom: "30%",
|
|
240
|
+
left: "10%",
|
|
241
|
+
borderColor: "#0F0",
|
|
242
|
+
borderWidth: 2,
|
|
243
|
+
backgroundColor: "rgba(255,0,0,0.15)"
|
|
244
|
+
}
|
|
245
|
+
},
|
|
246
|
+
locate: false
|
|
247
|
+
});
|
|
248
|
+
|
|
249
|
+
// Later, manually redraw if you've cleared the overlay
|
|
250
|
+
Quagga.drawScannerArea();
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
### `Quagga.offDetected(handler)` {#quagga-offdetected}
|
|
254
|
+
|
|
255
|
+
Removes a previously registered `onDetected` handler.
|
|
256
|
+
|
|
257
|
+
**Parameters**:
|
|
258
|
+
|
|
259
|
+
- `handler` (Function, optional) - Specific handler to remove. If omitted, **all** handlers are removed.
|
|
260
|
+
|
|
261
|
+
**Returns**: `void`
|
|
262
|
+
|
|
263
|
+
**Example**:
|
|
264
|
+
|
|
265
|
+
```javascript
|
|
266
|
+
function myHandler(result) {
|
|
267
|
+
console.log(result.codeResult.code);
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
Quagga.onDetected(myHandler);
|
|
271
|
+
|
|
272
|
+
// Later: remove specific handler
|
|
273
|
+
Quagga.offDetected(myHandler);
|
|
274
|
+
|
|
275
|
+
// Or remove all handlers
|
|
276
|
+
Quagga.offDetected();
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### `Quagga.offProcessed(handler)` {#quagga-offprocessed}
|
|
280
|
+
|
|
281
|
+
Removes a previously registered `onProcessed` handler.
|
|
282
|
+
|
|
283
|
+
**Parameters**:
|
|
284
|
+
|
|
285
|
+
- `handler` (Function, optional) - Specific handler to remove. If omitted, **all** handlers are removed.
|
|
286
|
+
|
|
287
|
+
**Returns**: `void`
|
|
288
|
+
|
|
289
|
+
**Example**:
|
|
290
|
+
|
|
291
|
+
```javascript
|
|
292
|
+
function processHandler(result) {
|
|
293
|
+
// Process frame
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
Quagga.onProcessed(processHandler);
|
|
297
|
+
|
|
298
|
+
// Remove specific handler
|
|
299
|
+
Quagga.offProcessed(processHandler);
|
|
300
|
+
|
|
301
|
+
// Or remove all handlers
|
|
302
|
+
Quagga.offProcessed();
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
### `Quagga.decodeSingle(config, callback)` {#quagga-decodesingle}
|
|
306
|
+
|
|
307
|
+
Decodes a single image without using `getUserMedia`. Useful for processing uploaded images or static images.
|
|
308
|
+
|
|
309
|
+
**Parameters**:
|
|
310
|
+
|
|
311
|
+
- `config` (Object) - Configuration object (subset of full config)
|
|
312
|
+
- `callback` (Function) - Result handler: `callback(result)`
|
|
313
|
+
- `result` (Object) - Same format as `onDetected` callback
|
|
314
|
+
|
|
315
|
+
**Returns**: `void`
|
|
316
|
+
|
|
317
|
+
**Important - Default Scaling**: `decodeSingle` has a built-in default of `inputStream.size: 800`. This means images are **automatically scaled to 800px** on their longest side (both larger images scaled down AND smaller images scaled up). The result's `box`, `boxes`, and `line` coordinates are returned in this scaled coordinate space, not the original image dimensions. To use the original image dimensions without scaling, set `inputStream.size` to `0`.
|
|
318
|
+
|
|
319
|
+
**Example**:
|
|
320
|
+
|
|
321
|
+
```javascript
|
|
322
|
+
Quagga.decodeSingle({
|
|
323
|
+
src: '/images/barcode.jpg', // Or data URL
|
|
324
|
+
decoder: {
|
|
325
|
+
readers: ["code_128_reader", "ean_reader"]
|
|
326
|
+
},
|
|
327
|
+
locate: true // Try to locate barcode in image
|
|
328
|
+
// Note: inputStream.size defaults to 800; images are scaled to 800px (up or down)
|
|
329
|
+
}, function(result) {
|
|
330
|
+
if (result && result.codeResult) {
|
|
331
|
+
console.log("Detected:", result.codeResult.code);
|
|
332
|
+
console.log("Format:", result.codeResult.format);
|
|
333
|
+
} else {
|
|
334
|
+
console.log("No barcode detected");
|
|
335
|
+
}
|
|
336
|
+
});
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
**Using Data URLs**:
|
|
340
|
+
|
|
341
|
+
```javascript
|
|
342
|
+
// From file input
|
|
343
|
+
document.querySelector('#file-input').addEventListener('change', function(e) {
|
|
344
|
+
const file = e.target.files[0];
|
|
345
|
+
const reader = new FileReader();
|
|
346
|
+
|
|
347
|
+
reader.onload = function(event) {
|
|
348
|
+
Quagga.decodeSingle({
|
|
349
|
+
src: event.target.result, // Data URL
|
|
350
|
+
decoder: {
|
|
351
|
+
readers: ["code_128_reader"]
|
|
352
|
+
}
|
|
353
|
+
// Default size: 800 applies - image scaled if larger
|
|
354
|
+
}, function(result) {
|
|
355
|
+
if (result && result.codeResult) {
|
|
356
|
+
alert("Barcode: " + result.codeResult.code);
|
|
357
|
+
}
|
|
358
|
+
});
|
|
359
|
+
};
|
|
360
|
+
|
|
361
|
+
reader.readAsDataURL(file);
|
|
362
|
+
});
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
**Node.js Usage**:
|
|
366
|
+
|
|
367
|
+
```javascript
|
|
368
|
+
const Quagga = require('@ericblade/quagga2').default;
|
|
369
|
+
|
|
370
|
+
Quagga.decodeSingle({
|
|
371
|
+
src: "./barcode.jpg",
|
|
372
|
+
inputStream: {
|
|
373
|
+
size: 800 // This is actually the default; shown explicitly here
|
|
374
|
+
},
|
|
375
|
+
decoder: {
|
|
376
|
+
readers: ["code_128_reader"]
|
|
377
|
+
}
|
|
378
|
+
}, function(result) {
|
|
379
|
+
if (result && result.codeResult) {
|
|
380
|
+
console.log("Code:", result.codeResult.code);
|
|
381
|
+
}
|
|
382
|
+
});
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
## Result Object {#result-object}
|
|
386
|
+
|
|
387
|
+
The result object passed to `onDetected`, `onProcessed`, and `decodeSingle` callbacks contains detailed information about the detection and decoding process.
|
|
388
|
+
|
|
389
|
+
### Complete Result Structure {#result-structure}
|
|
390
|
+
|
|
391
|
+
```javascript
|
|
392
|
+
{
|
|
393
|
+
codeResult: {
|
|
394
|
+
code: "FANAVF1461710", // The decoded barcode string
|
|
395
|
+
format: "code_128", // Barcode format
|
|
396
|
+
start: 355, // Start position
|
|
397
|
+
end: 26, // End position
|
|
398
|
+
codeset: 100, // Code 128 specific
|
|
399
|
+
startInfo: {
|
|
400
|
+
error: 1.0,
|
|
401
|
+
code: 104,
|
|
402
|
+
start: 21,
|
|
403
|
+
end: 41
|
|
404
|
+
},
|
|
405
|
+
decodedCodes: [ // Individual code segments
|
|
406
|
+
{ code: 104, start: 21, end: 41 },
|
|
407
|
+
// ... more segments
|
|
408
|
+
{ error: 0.88, code: 106, start: 328, end: 350 }
|
|
409
|
+
],
|
|
410
|
+
endInfo: {
|
|
411
|
+
error: 0.88,
|
|
412
|
+
code: 106,
|
|
413
|
+
start: 328,
|
|
414
|
+
end: 350
|
|
415
|
+
},
|
|
416
|
+
direction: -1 // Scan direction
|
|
417
|
+
},
|
|
418
|
+
line: [ // Scan line coordinates
|
|
419
|
+
{ x: 25.97, y: 360.56 },
|
|
420
|
+
{ x: 401.92, y: 70.88 }
|
|
421
|
+
],
|
|
422
|
+
angle: -0.657, // Rotation angle in radians
|
|
423
|
+
pattern: [0, 0, 1, 1, ...], // Bar pattern (0=space, 1=bar)
|
|
424
|
+
box: [ // Primary bounding box (4 corners)
|
|
425
|
+
[77.41, 410.93], // Top-left
|
|
426
|
+
[0.05, 310.54], // Top-right
|
|
427
|
+
[360.16, 33.06], // Bottom-right
|
|
428
|
+
[437.51, 133.45] // Bottom-left
|
|
429
|
+
],
|
|
430
|
+
boxes: [ // All detected boxes
|
|
431
|
+
[/* box 1 */],
|
|
432
|
+
[/* box 2 */],
|
|
433
|
+
// ...
|
|
434
|
+
]
|
|
435
|
+
}
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
### Result Properties {#result-properties}
|
|
439
|
+
|
|
440
|
+
| Property | Type | Description |
|
|
441
|
+
|----------|------|-------------|
|
|
442
|
+
| `codeResult` | Object | Decoded barcode information (may be `undefined` if detection failed) |
|
|
443
|
+
| `codeResult.code` | String | The decoded barcode value |
|
|
444
|
+
| `codeResult.format` | String | Barcode format (e.g., "code_128", "ean_13") |
|
|
445
|
+
| `codeResult.start` | Number | Start position in pattern |
|
|
446
|
+
| `codeResult.end` | Number | End position in pattern |
|
|
447
|
+
| `codeResult.direction` | Number | Scan direction (1 or -1) |
|
|
448
|
+
| `codeResult.supplement` | Object | (Optional) Supplement barcode data for EAN-13/UPC-A with EAN-2 or EAN-5 extensions |
|
|
449
|
+
| `codeResult.supplement.code` | String | The decoded supplement value (2 or 5 digits) |
|
|
450
|
+
| `codeResult.supplement.format` | String | Supplement format: "ean_2" or "ean_5" |
|
|
451
|
+
| `line` | Array | Two points defining the scan line |
|
|
452
|
+
| `angle` | Number | Barcode rotation angle (radians) |
|
|
453
|
+
| `pattern` | Array | Binary pattern (0=space, 1=bar) |
|
|
454
|
+
| `box` | Array | Bounding box coordinates (4 corner points) |
|
|
455
|
+
| `boxes` | Array | All candidate boxes found during localization. When `locate` is `false`, this contains a single box representing the actual adjusted scanning area (after patch alignment) |
|
|
456
|
+
|
|
457
|
+
> **Note: `boxes` with `locate: false`**
|
|
458
|
+
>
|
|
459
|
+
> When `locate` is `false` and an `inputStream.area` is configured, `result.boxes` contains a single box representing the actual scanning area dimensions. This box reflects the adjusted dimensions after patch alignment (which can differ slightly from the percentage-based area due to rounding to patch size multiples). Use these coordinates if you need to know the exact scanning rectangle:
|
|
460
|
+
>
|
|
461
|
+
> ```javascript
|
|
462
|
+
> Quagga.onProcessed(function(result) {
|
|
463
|
+
> if (result.boxes && result.boxes.length > 0) {
|
|
464
|
+
> // When locate=false, boxes[0] is the actual scanning area
|
|
465
|
+
> const scanArea = result.boxes[0];
|
|
466
|
+
> console.log("Scanning area corners:", scanArea);
|
|
467
|
+
> }
|
|
468
|
+
> });
|
|
469
|
+
> ```
|
|
470
|
+
|
|
471
|
+
> **Important: Coordinate System**
|
|
472
|
+
>
|
|
473
|
+
> The `box`, `boxes`, and `line` coordinates are returned in **processed canvas coordinates**, not original image/video coordinates. If you're using `inputStream.size` to scale the processing resolution (e.g., for performance), you'll need to scale these coordinates to match your original video/image dimensions.
|
|
474
|
+
>
|
|
475
|
+
> ```javascript
|
|
476
|
+
> // Scale coordinates to original video size
|
|
477
|
+
> const scaleX = video.videoWidth / Quagga.canvas.dom.image.width;
|
|
478
|
+
> const scaleY = video.videoHeight / Quagga.canvas.dom.image.height;
|
|
479
|
+
> const scaledBox = result.box.map(p => [p[0] * scaleX, p[1] * scaleY]);
|
|
480
|
+
> ```
|
|
481
|
+
>
|
|
482
|
+
> See [Working with Box Coordinates](../how-to-guides/working-with-coordinates.md) for complete examples.
|
|
483
|
+
|
|
484
|
+
### Checking for Successful Detection {#checking-detection}
|
|
485
|
+
|
|
486
|
+
```javascript
|
|
487
|
+
Quagga.onDetected(function(result) {
|
|
488
|
+
// Always check if codeResult exists
|
|
489
|
+
if (result && result.codeResult && result.codeResult.code) {
|
|
490
|
+
console.log("Detected:", result.codeResult.code);
|
|
491
|
+
}
|
|
492
|
+
});
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
### Using Multiple Barcode Detection {#multiple-barcode-detection}
|
|
496
|
+
|
|
497
|
+
When `decoder.multiple` is `true`, results are returned as an array:
|
|
498
|
+
|
|
499
|
+
```javascript
|
|
500
|
+
Quagga.init({
|
|
501
|
+
decoder: {
|
|
502
|
+
readers: ["code_128_reader"],
|
|
503
|
+
multiple: true
|
|
504
|
+
}
|
|
505
|
+
});
|
|
506
|
+
|
|
507
|
+
Quagga.onDetected(function(result) {
|
|
508
|
+
// result is an array of result objects
|
|
509
|
+
result.forEach(function(item) {
|
|
510
|
+
if (item.codeResult) {
|
|
511
|
+
console.log("Code:", item.codeResult.code);
|
|
512
|
+
console.log("Box:", item.box);
|
|
513
|
+
}
|
|
514
|
+
});
|
|
515
|
+
});
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
## Canvas Access {#canvas-access}
|
|
519
|
+
|
|
520
|
+
Quagga automatically creates and manages two canvas elements for visualization. These are positioned over the video/image stream and sized to match the processing dimensions.
|
|
521
|
+
|
|
522
|
+
### Canvas Structure {#canvas-structure}
|
|
523
|
+
|
|
524
|
+
```javascript
|
|
525
|
+
Quagga.canvas = {
|
|
526
|
+
dom: {
|
|
527
|
+
image: HTMLCanvasElement, // Canvas for processed image data
|
|
528
|
+
overlay: HTMLCanvasElement | null // Transparent canvas for drawing overlays
|
|
529
|
+
},
|
|
530
|
+
ctx: {
|
|
531
|
+
image: CanvasRenderingContext2D, // Context for image canvas
|
|
532
|
+
overlay: CanvasRenderingContext2D | null // Context for overlay canvas
|
|
533
|
+
}
|
|
534
|
+
};
|
|
535
|
+
```
|
|
536
|
+
|
|
537
|
+
> **Note**: The overlay canvas can be `null` if `canvas.createOverlay` is set to `false` in the configuration. See [Canvas Configuration](configuration.md#canvas-configuration) for details.
|
|
538
|
+
|
|
539
|
+
### Overlay Canvas {#overlay-canvas}
|
|
540
|
+
|
|
541
|
+
The **overlay canvas** (`Quagga.canvas.dom.overlay`) is a transparent canvas element positioned over the video stream. It's automatically created when Quagga initializes (unless `canvas.createOverlay` is `false`) and is designed for drawing bounding boxes, scan lines, and other visual feedback.
|
|
542
|
+
|
|
543
|
+
**Key characteristics:**
|
|
544
|
+
- Has CSS class `drawingBuffer`
|
|
545
|
+
- Sized to match the processed image dimensions (`inputStream.size`)
|
|
546
|
+
- Positioned absolutely over the video/image element
|
|
547
|
+
- Automatically appended to the viewport container
|
|
548
|
+
- Coordinates match the processed image space (no scaling needed)
|
|
549
|
+
- Can be disabled via `canvas.createOverlay: false` for performance
|
|
550
|
+
|
|
551
|
+
**Accessing the overlay:**
|
|
552
|
+
```javascript
|
|
553
|
+
const overlay = Quagga.canvas.dom.overlay;
|
|
554
|
+
const overlayCtx = Quagga.canvas.ctx.overlay;
|
|
555
|
+
|
|
556
|
+
// Always check if overlay exists before using
|
|
557
|
+
if (overlayCtx && overlay) {
|
|
558
|
+
// Clear overlay
|
|
559
|
+
overlayCtx.clearRect(0, 0, overlay.width, overlay.height);
|
|
560
|
+
|
|
561
|
+
// Draw custom shapes
|
|
562
|
+
overlayCtx.strokeStyle = "red";
|
|
563
|
+
overlayCtx.lineWidth = 3;
|
|
564
|
+
overlayCtx.strokeRect(10, 10, 100, 100);
|
|
565
|
+
}
|
|
566
|
+
```
|
|
567
|
+
|
|
568
|
+
### Image Canvas {#image-canvas}
|
|
569
|
+
|
|
570
|
+
The **image canvas** (`Quagga.canvas.dom.image`) contains the processed grayscale image data used for barcode detection. This is primarily for internal use and debugging.
|
|
571
|
+
|
|
572
|
+
**Key characteristics:**
|
|
573
|
+
- Has CSS class `imgBuffer`
|
|
574
|
+
- Contains the grayscale/processed image data
|
|
575
|
+
- Useful for debugging locator issues
|
|
576
|
+
|
|
577
|
+
### When to Use Each Canvas {#when-to-use-canvas}
|
|
578
|
+
|
|
579
|
+
| Use Case | Canvas to Use |
|
|
580
|
+
|----------|---------------|
|
|
581
|
+
| Drawing bounding boxes | `overlay` |
|
|
582
|
+
| Highlighting detected barcodes | `overlay` |
|
|
583
|
+
| Custom scan line visualization | `overlay` |
|
|
584
|
+
| Debugging image processing | `image` |
|
|
585
|
+
| Checking processed resolution | Either (they have same dimensions) |
|
|
586
|
+
|
|
587
|
+
### Important: Coordinate System {#canvas-coordinate-system}
|
|
588
|
+
|
|
589
|
+
When drawing on the overlay canvas, use `result.box` and `result.boxes` coordinates directly - **no scaling is needed**. These coordinates are already in the overlay canvas's coordinate space.
|
|
590
|
+
|
|
591
|
+
```javascript
|
|
592
|
+
Quagga.onProcessed(function(result) {
|
|
593
|
+
const ctx = Quagga.canvas.ctx.overlay;
|
|
594
|
+
const canvas = Quagga.canvas.dom.overlay;
|
|
595
|
+
|
|
596
|
+
// Clear previous drawings
|
|
597
|
+
ctx.clearRect(0, 0, canvas.width, canvas.height);
|
|
598
|
+
|
|
599
|
+
// Draw box directly - coordinates already match the overlay canvas
|
|
600
|
+
if (result && result.box) {
|
|
601
|
+
Quagga.ImageDebug.drawPath(result.box, {x: 0, y: 1}, ctx, {
|
|
602
|
+
color: "green", lineWidth: 2
|
|
603
|
+
});
|
|
604
|
+
}
|
|
605
|
+
});
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
> **Note**: Scaling is only needed when drawing on a **different** canvas (like a custom overlay on the original video element). See [Working with Box Coordinates](../how-to-guides/working-with-coordinates.md) for details.
|
|
609
|
+
|
|
610
|
+
### CSS Styling {#canvas-css-styling}
|
|
611
|
+
|
|
612
|
+
The overlay canvas can be styled with CSS for positioning:
|
|
613
|
+
|
|
614
|
+
```css
|
|
615
|
+
/* Default positioning (handled automatically by Quagga) */
|
|
616
|
+
canvas.drawingBuffer {
|
|
617
|
+
position: absolute;
|
|
618
|
+
top: 0;
|
|
619
|
+
left: 0;
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
/* Ensure proper stacking */
|
|
623
|
+
#scanner-container {
|
|
624
|
+
position: relative;
|
|
625
|
+
}
|
|
626
|
+
```
|
|
627
|
+
|
|
628
|
+
## ImageDebug Helper {#imagedebug-helper}
|
|
629
|
+
|
|
630
|
+
Quagga provides a helper for drawing debug visualizations:
|
|
631
|
+
|
|
632
|
+
```javascript
|
|
633
|
+
// Draw a path (array of points)
|
|
634
|
+
Quagga.ImageDebug.drawPath(points, offset, ctx, options);
|
|
635
|
+
|
|
636
|
+
// Example
|
|
637
|
+
Quagga.ImageDebug.drawPath(
|
|
638
|
+
result.box,
|
|
639
|
+
{ x: 0, y: 1 },
|
|
640
|
+
overlayCtx,
|
|
641
|
+
{ color: "green", lineWidth: 2 }
|
|
642
|
+
);
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
## Complete Example {#complete-example}
|
|
646
|
+
|
|
647
|
+
```javascript
|
|
648
|
+
// Initialize
|
|
649
|
+
Quagga.init({
|
|
650
|
+
inputStream: {
|
|
651
|
+
type: "LiveStream",
|
|
652
|
+
target: document.querySelector('#scanner'),
|
|
653
|
+
constraints: {
|
|
654
|
+
width: 640,
|
|
655
|
+
height: 480,
|
|
656
|
+
facingMode: "environment"
|
|
657
|
+
}
|
|
658
|
+
},
|
|
659
|
+
decoder: {
|
|
660
|
+
readers: ["code_128_reader", "ean_reader"]
|
|
661
|
+
}
|
|
662
|
+
}, function(err) {
|
|
663
|
+
if (err) {
|
|
664
|
+
console.error(err);
|
|
665
|
+
return;
|
|
666
|
+
}
|
|
667
|
+
|
|
668
|
+
// Start scanning
|
|
669
|
+
Quagga.start();
|
|
670
|
+
});
|
|
671
|
+
|
|
672
|
+
// Handle detections
|
|
673
|
+
Quagga.onDetected(function(result) {
|
|
674
|
+
console.log("Barcode detected:", result.codeResult.code);
|
|
675
|
+
|
|
676
|
+
// Stop after first detection
|
|
677
|
+
Quagga.stop();
|
|
678
|
+
|
|
679
|
+
// Cleanup
|
|
680
|
+
Quagga.offDetected();
|
|
681
|
+
Quagga.offProcessed();
|
|
682
|
+
});
|
|
683
|
+
|
|
684
|
+
// Visualize processing
|
|
685
|
+
Quagga.onProcessed(function(result) {
|
|
686
|
+
const ctx = Quagga.canvas.ctx.overlay;
|
|
687
|
+
const canvas = Quagga.canvas.dom.overlay;
|
|
688
|
+
|
|
689
|
+
ctx.clearRect(0, 0, canvas.width, canvas.height);
|
|
690
|
+
|
|
691
|
+
if (result && result.box) {
|
|
692
|
+
Quagga.ImageDebug.drawPath(result.box, {x: 0, y: 1}, ctx, {
|
|
693
|
+
color: "green",
|
|
694
|
+
lineWidth: 2
|
|
695
|
+
});
|
|
696
|
+
}
|
|
697
|
+
});
|
|
698
|
+
|
|
699
|
+
// Stop button
|
|
700
|
+
document.querySelector('#stop').addEventListener('click', function() {
|
|
701
|
+
Quagga.stop();
|
|
702
|
+
Quagga.offDetected();
|
|
703
|
+
Quagga.offProcessed();
|
|
704
|
+
});
|
|
705
|
+
```
|
|
706
|
+
|
|
707
|
+
## Related {#related}
|
|
708
|
+
|
|
709
|
+
- [Configuration Reference](configuration.md) - Complete configuration options
|
|
710
|
+
- [CameraAccess API](camera-access.md) - Camera control methods
|
|
711
|
+
- [Supported Barcode Types](readers.md) - Available barcode readers
|
|
712
|
+
- [Getting Started](../getting-started.md) - Basic usage examples
|
|
713
|
+
|
|
714
|
+
---
|
|
715
|
+
|
|
716
|
+
[← Back to Reference](index.md)
|