@ericblade/quagga2 1.10.1 → 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.
Files changed (51) hide show
  1. package/DEPENDENCIES.md +286 -0
  2. package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
  3. package/README.md +119 -10
  4. package/dist/quagga.js +11087 -10681
  5. package/dist/quagga.min.js +4 -3
  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 +102 -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 +716 -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 +1008 -0
  41. package/docs/reference/dependencies.md +295 -0
  42. package/docs/reference/index.md +74 -0
  43. package/docs/reference/readers.md +261 -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 +3140 -2757
  50. package/package.json +22 -18
  51. package/type-definitions/quagga.d.ts +111 -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)