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