@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,776 @@
|
|
|
1
|
+
# How to Use Debug Flags {#how-to-use-debug-flags}
|
|
2
|
+
|
|
3
|
+
Quagga2 includes several debug flags that enable diagnostic console output to help troubleshoot issues with barcode detection and decoding. This guide explains when and how to use them.
|
|
4
|
+
|
|
5
|
+
## Overview {#overview}
|
|
6
|
+
|
|
7
|
+
Debug flags control what information Quagga2 logs to the browser console. By default, **all debug output is suppressed** to keep your console clean. Enable specific flags when you need to diagnose problems.
|
|
8
|
+
|
|
9
|
+
## Important Note {#important-note}
|
|
10
|
+
|
|
11
|
+
Debug flags only work when `ENV.development` is `true` (development builds). Production builds strip out all debug code to minimize bundle size.
|
|
12
|
+
|
|
13
|
+
## Available Debug Flags {#available-debug-flags}
|
|
14
|
+
|
|
15
|
+
Debug flags are organized into three categories:
|
|
16
|
+
|
|
17
|
+
1. **Console logging flags** - Print diagnostic information to the console
|
|
18
|
+
2. **Visual canvas overlays** - Draw debugging information on the canvas
|
|
19
|
+
3. **Performance analysis** - Display frequency and pattern data
|
|
20
|
+
|
|
21
|
+
### Console Logging Flags {#console-logging-flags}
|
|
22
|
+
|
|
23
|
+
#### `inputStream.debug.showImageDetails` {#inputstream-debug-showimagedetails}
|
|
24
|
+
|
|
25
|
+
**What it shows**: Image loading and frame grabber operations
|
|
26
|
+
|
|
27
|
+
**Console output example**:
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
*** frame_grabber_browser: willReadFrequency=undefined canvas=<canvas>
|
|
31
|
+
Image Loader: Loaded 3 images from /path/to/image.jpg
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**When to use**:
|
|
35
|
+
|
|
36
|
+
- Camera feed not showing
|
|
37
|
+
- Images not loading from file input
|
|
38
|
+
- Canvas-related issues
|
|
39
|
+
|
|
40
|
+
**How to enable**:
|
|
41
|
+
|
|
42
|
+
```javascript
|
|
43
|
+
Quagga.init({
|
|
44
|
+
inputStream: {
|
|
45
|
+
// ... your input config
|
|
46
|
+
debug: {
|
|
47
|
+
showImageDetails: true
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
// ... rest of config
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
#### `decoder.debug.printReaderInfo` {#decoder-debug-printreaderinfo}
|
|
55
|
+
|
|
56
|
+
**What it shows**: Barcode reader registration and initialization
|
|
57
|
+
|
|
58
|
+
**Console output example**:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
* ImageWrapper getCanvasAndContext
|
|
62
|
+
Registering reader: code_128_reader
|
|
63
|
+
Before registering reader: EANReader
|
|
64
|
+
Registered Readers: code_128, ean
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
**When to use**:
|
|
68
|
+
|
|
69
|
+
- Verifying which readers are active
|
|
70
|
+
- Reader not detecting expected barcode type
|
|
71
|
+
- Multiple reader configuration issues
|
|
72
|
+
|
|
73
|
+
**How to enable**:
|
|
74
|
+
|
|
75
|
+
```javascript
|
|
76
|
+
Quagga.init({
|
|
77
|
+
decoder: {
|
|
78
|
+
readers: ["code_128_reader", "ean_reader"],
|
|
79
|
+
debug: {
|
|
80
|
+
printReaderInfo: true
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
// ... rest of config
|
|
84
|
+
});
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
#### `locator.debug.showPatchSize` {#locator-debug-showpatchsize}
|
|
88
|
+
|
|
89
|
+
**What it shows**: Patch dimensions during barcode localization
|
|
90
|
+
|
|
91
|
+
**Console output example**:
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
Patch-Size: 320x240
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
**When to use**:
|
|
98
|
+
|
|
99
|
+
- Barcode locator not finding barcodes
|
|
100
|
+
- Understanding what image size the locator is processing
|
|
101
|
+
- Performance optimization (smaller patches = faster)
|
|
102
|
+
|
|
103
|
+
**How to enable**:
|
|
104
|
+
|
|
105
|
+
```javascript
|
|
106
|
+
Quagga.init({
|
|
107
|
+
locator: {
|
|
108
|
+
patchSize: "medium",
|
|
109
|
+
debug: {
|
|
110
|
+
showPatchSize: true
|
|
111
|
+
}
|
|
112
|
+
},
|
|
113
|
+
// ... rest of config
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
#### `locator.debug.showImageDetails` {#locator-debug-showimagedetails}
|
|
118
|
+
|
|
119
|
+
**What it shows**: Canvas and image wrapper initialization for locator
|
|
120
|
+
|
|
121
|
+
**Console output example**:
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
* initCanvas getCanvasAndContext
|
|
125
|
+
* ImageWrapper getCanvasAndContext
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**When to use**:
|
|
129
|
+
|
|
130
|
+
- Locator canvas not rendering
|
|
131
|
+
- Debugging locator initialization failures
|
|
132
|
+
- Understanding when canvas contexts are created
|
|
133
|
+
|
|
134
|
+
**How to enable**:
|
|
135
|
+
|
|
136
|
+
```javascript
|
|
137
|
+
Quagga.init({
|
|
138
|
+
locator: {
|
|
139
|
+
// ... your locator config
|
|
140
|
+
debug: {
|
|
141
|
+
showImageDetails: true
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
// ... rest of config
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Visual Canvas Overlay Flags {#visual-canvas-overlay-flags}
|
|
149
|
+
|
|
150
|
+
These flags draw debugging information directly on the canvas, allowing you to visualize the barcode detection algorithm's internal state.
|
|
151
|
+
|
|
152
|
+
Note: The scan area overlay (defined via `inputStream.area`) is not a debug flag. When `locate: false`, Quagga draws the scan area on the overlay canvas each processed frame. You can also draw it manually using `Quagga.drawScannerArea()`. See the [Configuration Reference](../reference/configuration.md#inputstream-area-drawing) and [API](../reference/api.md#quagga-drawscannerarea).
|
|
153
|
+
|
|
154
|
+
#### `decoder.debug.drawBoundingBox` {#decoder-debug-drawboundingbox}
|
|
155
|
+
|
|
156
|
+
**What it shows**: Draws a box around the detected barcode location
|
|
157
|
+
|
|
158
|
+
**When to use**:
|
|
159
|
+
|
|
160
|
+
- Verify barcode is being located correctly
|
|
161
|
+
- Debug positioning issues
|
|
162
|
+
- Understand where the decoder thinks the barcode is
|
|
163
|
+
|
|
164
|
+
**How to enable**:
|
|
165
|
+
|
|
166
|
+
```javascript
|
|
167
|
+
Quagga.init({
|
|
168
|
+
decoder: {
|
|
169
|
+
debug: {
|
|
170
|
+
drawBoundingBox: true
|
|
171
|
+
}
|
|
172
|
+
},
|
|
173
|
+
// ... rest of config
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
#### `decoder.debug.drawScanline` {#decoder-debug-drawscanline}
|
|
178
|
+
|
|
179
|
+
**What it shows**: Draws the scanline path used for decoding
|
|
180
|
+
|
|
181
|
+
**When to use**:
|
|
182
|
+
|
|
183
|
+
- Verify scanner is reading through the barcode correctly
|
|
184
|
+
- Debug angle/orientation issues
|
|
185
|
+
- Understand why certain barcodes fail to decode
|
|
186
|
+
|
|
187
|
+
**How to enable**:
|
|
188
|
+
|
|
189
|
+
```javascript
|
|
190
|
+
Quagga.init({
|
|
191
|
+
decoder: {
|
|
192
|
+
debug: {
|
|
193
|
+
drawScanline: true
|
|
194
|
+
}
|
|
195
|
+
},
|
|
196
|
+
// ... rest of config
|
|
197
|
+
});
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
#### `locator.debug.showCanvas` {#locator-debug-showcanvas}
|
|
201
|
+
|
|
202
|
+
**What it shows**: Displays the locator's internal canvas used for image processing
|
|
203
|
+
|
|
204
|
+
**When to use**:
|
|
205
|
+
|
|
206
|
+
- Debug localization algorithm
|
|
207
|
+
- Verify image preprocessing is working
|
|
208
|
+
- Understand what the locator "sees"
|
|
209
|
+
|
|
210
|
+
**How to enable**:
|
|
211
|
+
|
|
212
|
+
```javascript
|
|
213
|
+
Quagga.init({
|
|
214
|
+
locator: {
|
|
215
|
+
debug: {
|
|
216
|
+
showCanvas: true
|
|
217
|
+
}
|
|
218
|
+
},
|
|
219
|
+
// ... rest of config
|
|
220
|
+
});
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
#### `locator.debug.showPatches` {#locator-debug-showpatches}
|
|
224
|
+
|
|
225
|
+
**What it shows**: Draws all patches extracted during the localization phase
|
|
226
|
+
|
|
227
|
+
**When to use**:
|
|
228
|
+
|
|
229
|
+
- Debug patch extraction issues
|
|
230
|
+
- Verify patch size is appropriate
|
|
231
|
+
- Understand what regions are being analyzed
|
|
232
|
+
|
|
233
|
+
**How to enable**:
|
|
234
|
+
|
|
235
|
+
```javascript
|
|
236
|
+
Quagga.init({
|
|
237
|
+
locator: {
|
|
238
|
+
debug: {
|
|
239
|
+
showPatches: true
|
|
240
|
+
}
|
|
241
|
+
},
|
|
242
|
+
// ... rest of config
|
|
243
|
+
});
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
#### `locator.debug.showFoundPatches` {#locator-debug-showfoundpatches}
|
|
247
|
+
|
|
248
|
+
**What it shows**: Highlights patches where potential barcodes were found
|
|
249
|
+
|
|
250
|
+
**When to use**:
|
|
251
|
+
|
|
252
|
+
- Verify barcode candidates are being identified
|
|
253
|
+
- Debug false positives/negatives in patch detection
|
|
254
|
+
- Optimize patch threshold settings
|
|
255
|
+
|
|
256
|
+
**How to enable**:
|
|
257
|
+
|
|
258
|
+
```javascript
|
|
259
|
+
Quagga.init({
|
|
260
|
+
locator: {
|
|
261
|
+
debug: {
|
|
262
|
+
showFoundPatches: true
|
|
263
|
+
}
|
|
264
|
+
},
|
|
265
|
+
// ... rest of config
|
|
266
|
+
});
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
#### `locator.debug.showSkeleton` {#locator-debug-showskeleton}
|
|
270
|
+
|
|
271
|
+
**What it shows**: Displays the skeleton structure extracted from patches
|
|
272
|
+
|
|
273
|
+
**When to use**:
|
|
274
|
+
|
|
275
|
+
- Debug advanced localization algorithm
|
|
276
|
+
- Understand structure detection
|
|
277
|
+
- Verify skeleton extraction is working
|
|
278
|
+
|
|
279
|
+
**How to enable**:
|
|
280
|
+
|
|
281
|
+
```javascript
|
|
282
|
+
Quagga.init({
|
|
283
|
+
locator: {
|
|
284
|
+
debug: {
|
|
285
|
+
showSkeleton: true
|
|
286
|
+
}
|
|
287
|
+
},
|
|
288
|
+
// ... rest of config
|
|
289
|
+
});
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
#### `locator.debug.showLabels` {#locator-debug-showlabels}
|
|
293
|
+
|
|
294
|
+
**What it shows**: Displays component labels during connected component analysis
|
|
295
|
+
|
|
296
|
+
**When to use**:
|
|
297
|
+
|
|
298
|
+
- Debug component labeling phase
|
|
299
|
+
- Verify components are being identified correctly
|
|
300
|
+
- Understand clustering behavior
|
|
301
|
+
|
|
302
|
+
**How to enable**:
|
|
303
|
+
|
|
304
|
+
```javascript
|
|
305
|
+
Quagga.init({
|
|
306
|
+
locator: {
|
|
307
|
+
debug: {
|
|
308
|
+
showLabels: true
|
|
309
|
+
}
|
|
310
|
+
},
|
|
311
|
+
// ... rest of config
|
|
312
|
+
});
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
#### `locator.debug.showPatchLabels` {#locator-debug-showpatchlabels}
|
|
316
|
+
|
|
317
|
+
**What it shows**: Shows labels assigned to individual patches
|
|
318
|
+
|
|
319
|
+
**When to use**:
|
|
320
|
+
|
|
321
|
+
- Debug patch classification
|
|
322
|
+
- Verify patches are being labeled correctly
|
|
323
|
+
- Understand patch grouping
|
|
324
|
+
|
|
325
|
+
**How to enable**:
|
|
326
|
+
|
|
327
|
+
```javascript
|
|
328
|
+
Quagga.init({
|
|
329
|
+
locator: {
|
|
330
|
+
debug: {
|
|
331
|
+
showPatchLabels: true
|
|
332
|
+
}
|
|
333
|
+
},
|
|
334
|
+
// ... rest of config
|
|
335
|
+
});
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
#### `locator.debug.showRemainingPatchLabels` {#locator-debug-showremainingpatchlabels}
|
|
339
|
+
|
|
340
|
+
**What it shows**: Displays labels for patches remaining after filtering
|
|
341
|
+
|
|
342
|
+
**When to use**:
|
|
343
|
+
|
|
344
|
+
- Debug patch filtering logic
|
|
345
|
+
- Verify correct patches survive filtering
|
|
346
|
+
- Optimize filter thresholds
|
|
347
|
+
|
|
348
|
+
**How to enable**:
|
|
349
|
+
|
|
350
|
+
```javascript
|
|
351
|
+
Quagga.init({
|
|
352
|
+
locator: {
|
|
353
|
+
debug: {
|
|
354
|
+
showRemainingPatchLabels: true
|
|
355
|
+
}
|
|
356
|
+
},
|
|
357
|
+
// ... rest of config
|
|
358
|
+
});
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
#### `locator.debug.boxFromPatches.showTransformed` {#locator-debug-boxfrompatches-showtransformed}
|
|
362
|
+
|
|
363
|
+
**What it shows**: Shows transformed patch coordinates during box calculation
|
|
364
|
+
|
|
365
|
+
**When to use**:
|
|
366
|
+
|
|
367
|
+
- Debug coordinate transformation
|
|
368
|
+
- Verify spatial transformations are correct
|
|
369
|
+
- Understand box calculation from patches
|
|
370
|
+
|
|
371
|
+
**How to enable**:
|
|
372
|
+
|
|
373
|
+
```javascript
|
|
374
|
+
Quagga.init({
|
|
375
|
+
locator: {
|
|
376
|
+
debug: {
|
|
377
|
+
boxFromPatches: {
|
|
378
|
+
showTransformed: true
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
},
|
|
382
|
+
// ... rest of config
|
|
383
|
+
});
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
#### `locator.debug.boxFromPatches.showTransformedBox` {#locator-debug-boxfrompatches-showtransformedbox}
|
|
387
|
+
|
|
388
|
+
**What it shows**: Displays the bounding box after transformation
|
|
389
|
+
|
|
390
|
+
**When to use**:
|
|
391
|
+
|
|
392
|
+
- Debug box transformation
|
|
393
|
+
- Verify box coordinates after spatial transform
|
|
394
|
+
- Understand final box positioning
|
|
395
|
+
|
|
396
|
+
**How to enable**:
|
|
397
|
+
|
|
398
|
+
```javascript
|
|
399
|
+
Quagga.init({
|
|
400
|
+
locator: {
|
|
401
|
+
debug: {
|
|
402
|
+
boxFromPatches: {
|
|
403
|
+
showTransformedBox: true
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
},
|
|
407
|
+
// ... rest of config
|
|
408
|
+
});
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
#### `locator.debug.boxFromPatches.showBB` {#locator-debug-boxfrompatches-showbb}
|
|
412
|
+
|
|
413
|
+
**What it shows**: Displays the final bounding box around detected barcode region
|
|
414
|
+
|
|
415
|
+
**When to use**:
|
|
416
|
+
|
|
417
|
+
- Verify final bounding box is correct
|
|
418
|
+
- Debug box calculation from patches
|
|
419
|
+
- Optimize localization accuracy
|
|
420
|
+
|
|
421
|
+
**How to enable**:
|
|
422
|
+
|
|
423
|
+
```javascript
|
|
424
|
+
Quagga.init({
|
|
425
|
+
locator: {
|
|
426
|
+
debug: {
|
|
427
|
+
boxFromPatches: {
|
|
428
|
+
showBB: true
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
},
|
|
432
|
+
// ... rest of config
|
|
433
|
+
});
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
### Performance Analysis Flags {#performance-analysis-flags}
|
|
437
|
+
|
|
438
|
+
#### `decoder.debug.showFrequency` {#decoder-debug-showfrequency}
|
|
439
|
+
|
|
440
|
+
**What it shows**: Displays frequency data from the barcode scanline
|
|
441
|
+
|
|
442
|
+
**When to use**:
|
|
443
|
+
|
|
444
|
+
- Analyze barcode signal quality
|
|
445
|
+
- Debug decoding issues at the signal level
|
|
446
|
+
- Understand why certain barcodes fail to decode
|
|
447
|
+
|
|
448
|
+
**How to enable**:
|
|
449
|
+
|
|
450
|
+
```javascript
|
|
451
|
+
Quagga.init({
|
|
452
|
+
decoder: {
|
|
453
|
+
debug: {
|
|
454
|
+
showFrequency: true
|
|
455
|
+
}
|
|
456
|
+
},
|
|
457
|
+
// ... rest of config
|
|
458
|
+
});
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
#### `decoder.debug.showPattern` {#decoder-debug-showpattern}
|
|
462
|
+
|
|
463
|
+
**What it shows**: Displays the pattern data extracted from the barcode
|
|
464
|
+
|
|
465
|
+
**When to use**:
|
|
466
|
+
|
|
467
|
+
- Analyze pattern recognition issues
|
|
468
|
+
- Debug specific barcode format problems
|
|
469
|
+
- Understand pattern extraction process
|
|
470
|
+
|
|
471
|
+
**How to enable**:
|
|
472
|
+
|
|
473
|
+
```javascript
|
|
474
|
+
Quagga.init({
|
|
475
|
+
decoder: {
|
|
476
|
+
debug: {
|
|
477
|
+
showPattern: true
|
|
478
|
+
}
|
|
479
|
+
},
|
|
480
|
+
// ... rest of config
|
|
481
|
+
});
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
## Common Debugging Scenarios {#common-debugging-scenarios}
|
|
485
|
+
|
|
486
|
+
### "No barcodes detected" {#no-barcodes-detected}
|
|
487
|
+
|
|
488
|
+
Enable console logging first, then add visual overlays if needed:
|
|
489
|
+
|
|
490
|
+
```javascript
|
|
491
|
+
Quagga.init({
|
|
492
|
+
inputStream: {
|
|
493
|
+
target: document.querySelector('#scanner'),
|
|
494
|
+
debug: {
|
|
495
|
+
showImageDetails: true
|
|
496
|
+
}
|
|
497
|
+
},
|
|
498
|
+
decoder: {
|
|
499
|
+
readers: ["code_128_reader"],
|
|
500
|
+
debug: {
|
|
501
|
+
printReaderInfo: true,
|
|
502
|
+
drawBoundingBox: true, // Visual: see if barcode is located
|
|
503
|
+
drawScanline: true // Visual: see scan path
|
|
504
|
+
}
|
|
505
|
+
},
|
|
506
|
+
locator: {
|
|
507
|
+
debug: {
|
|
508
|
+
showPatchSize: true,
|
|
509
|
+
showImageDetails: true,
|
|
510
|
+
showFoundPatches: true // Visual: see candidate patches
|
|
511
|
+
}
|
|
512
|
+
}
|
|
513
|
+
}, function(err) {
|
|
514
|
+
if (err) {
|
|
515
|
+
console.error("Init error:", err);
|
|
516
|
+
return;
|
|
517
|
+
}
|
|
518
|
+
console.log("Starting Quagga...");
|
|
519
|
+
Quagga.start();
|
|
520
|
+
});
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
Check console for:
|
|
524
|
+
|
|
525
|
+
- ✅ Readers registered correctly?
|
|
526
|
+
- ✅ Images loading?
|
|
527
|
+
- ✅ Patch size reasonable (not 0x0)?
|
|
528
|
+
- ✅ Canvas contexts created?
|
|
529
|
+
|
|
530
|
+
Check canvas overlay for:
|
|
531
|
+
|
|
532
|
+
- ✅ Are patches being detected? (green highlights)
|
|
533
|
+
- ✅ Is a bounding box drawn?
|
|
534
|
+
- ✅ Is the scanline visible and passing through the barcode?
|
|
535
|
+
|
|
536
|
+
### "Camera not working" {#camera-not-working}
|
|
537
|
+
|
|
538
|
+
Enable input stream debugging:
|
|
539
|
+
|
|
540
|
+
```javascript
|
|
541
|
+
Quagga.init({
|
|
542
|
+
inputStream: {
|
|
543
|
+
type: "LiveStream",
|
|
544
|
+
debug: {
|
|
545
|
+
showImageDetails: true // Shows camera/canvas setup
|
|
546
|
+
}
|
|
547
|
+
},
|
|
548
|
+
// ... rest of config
|
|
549
|
+
});
|
|
550
|
+
```
|
|
551
|
+
|
|
552
|
+
### "Wrong barcode type detected" {#wrong-barcode-type}
|
|
553
|
+
|
|
554
|
+
Enable reader info to verify configuration:
|
|
555
|
+
|
|
556
|
+
```javascript
|
|
557
|
+
Quagga.init({
|
|
558
|
+
decoder: {
|
|
559
|
+
readers: [
|
|
560
|
+
"code_128_reader", // Did you enable the right readers?
|
|
561
|
+
"ean_reader"
|
|
562
|
+
],
|
|
563
|
+
debug: {
|
|
564
|
+
printReaderInfo: true // Shows which readers are active
|
|
565
|
+
}
|
|
566
|
+
},
|
|
567
|
+
// ... rest of config
|
|
568
|
+
});
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
### "Deep-dive localization debugging" {#deep-dive-debugging}
|
|
572
|
+
|
|
573
|
+
For advanced debugging of the localization algorithm, enable all visual overlays:
|
|
574
|
+
|
|
575
|
+
```javascript
|
|
576
|
+
Quagga.init({
|
|
577
|
+
locator: {
|
|
578
|
+
debug: {
|
|
579
|
+
showCanvas: true,
|
|
580
|
+
showPatches: true,
|
|
581
|
+
showFoundPatches: true,
|
|
582
|
+
showSkeleton: true,
|
|
583
|
+
showLabels: true,
|
|
584
|
+
showPatchLabels: true,
|
|
585
|
+
showRemainingPatchLabels: true,
|
|
586
|
+
boxFromPatches: {
|
|
587
|
+
showTransformed: true,
|
|
588
|
+
showTransformedBox: true,
|
|
589
|
+
showBB: true
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
}, function(err) {
|
|
594
|
+
if (err) {
|
|
595
|
+
console.error(err);
|
|
596
|
+
return;
|
|
597
|
+
}
|
|
598
|
+
Quagga.start();
|
|
599
|
+
});
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
This will display every step of the localization process visually on the canvas. Use this to:
|
|
603
|
+
|
|
604
|
+
- Understand the complete localization pipeline
|
|
605
|
+
- Optimize patch size and thresholds
|
|
606
|
+
- Debug complex barcode positioning issues
|
|
607
|
+
- Learn how the algorithm works
|
|
608
|
+
|
|
609
|
+
**Warning**: Enabling all visual overlays may impact performance and make the canvas cluttered. Enable only what you need.
|
|
610
|
+
|
|
611
|
+
## Performance Impact {#performance-impact}
|
|
612
|
+
|
|
613
|
+
Debug flags have varying performance impacts:
|
|
614
|
+
|
|
615
|
+
**Console logging flags** (minimal impact):
|
|
616
|
+
|
|
617
|
+
- `showImageDetails`, `printReaderInfo`, `showPatchSize` - negligible overhead
|
|
618
|
+
- Only execute when enabled and only in development builds
|
|
619
|
+
|
|
620
|
+
**Visual canvas overlays** (moderate to high impact):
|
|
621
|
+
|
|
622
|
+
- Drawing operations on canvas can slow down real-time detection
|
|
623
|
+
- More overlays = more draw calls = slower performance
|
|
624
|
+
- Consider disabling in production or using only for development/debugging
|
|
625
|
+
|
|
626
|
+
**Performance analysis flags** (high impact):
|
|
627
|
+
|
|
628
|
+
- `showFrequency`, `showPattern` - can generate large amounts of data
|
|
629
|
+
- Best used sparingly when diagnosing specific decoding issues
|
|
630
|
+
|
|
631
|
+
**Recommendation**: Enable only the flags you need. Disable all visual overlays for production.
|
|
632
|
+
|
|
633
|
+
## Disabling Debug Output {#disabling-debug-output}
|
|
634
|
+
|
|
635
|
+
To turn off all debug output, either:
|
|
636
|
+
|
|
637
|
+
**Option 1**: Remove debug properties entirely
|
|
638
|
+
|
|
639
|
+
```javascript
|
|
640
|
+
Quagga.init({
|
|
641
|
+
inputStream: {
|
|
642
|
+
// debug property removed
|
|
643
|
+
},
|
|
644
|
+
// ...
|
|
645
|
+
});
|
|
646
|
+
```
|
|
647
|
+
|
|
648
|
+
**Option 2**: Set flags to `false`
|
|
649
|
+
|
|
650
|
+
```javascript
|
|
651
|
+
Quagga.init({
|
|
652
|
+
inputStream: {
|
|
653
|
+
debug: {
|
|
654
|
+
showImageDetails: false
|
|
655
|
+
}
|
|
656
|
+
},
|
|
657
|
+
decoder: {
|
|
658
|
+
debug: {
|
|
659
|
+
printReaderInfo: false,
|
|
660
|
+
drawBoundingBox: false,
|
|
661
|
+
drawScanline: false,
|
|
662
|
+
showFrequency: false,
|
|
663
|
+
showPattern: false
|
|
664
|
+
}
|
|
665
|
+
},
|
|
666
|
+
locator: {
|
|
667
|
+
debug: {
|
|
668
|
+
showCanvas: false,
|
|
669
|
+
showPatches: false,
|
|
670
|
+
showFoundPatches: false,
|
|
671
|
+
showSkeleton: false,
|
|
672
|
+
showLabels: false,
|
|
673
|
+
showPatchLabels: false,
|
|
674
|
+
showRemainingPatchLabels: false,
|
|
675
|
+
showPatchSize: false,
|
|
676
|
+
showImageDetails: false,
|
|
677
|
+
boxFromPatches: {
|
|
678
|
+
showTransformed: false,
|
|
679
|
+
showTransformedBox: false,
|
|
680
|
+
showBB: false
|
|
681
|
+
}
|
|
682
|
+
}
|
|
683
|
+
}
|
|
684
|
+
});
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
## Using in Node.js {#using-in-nodejs}
|
|
688
|
+
|
|
689
|
+
Debug flags work in Node.js too! Output goes to `console.log`:
|
|
690
|
+
|
|
691
|
+
```javascript
|
|
692
|
+
const Quagga = require('@ericblade/quagga2').default;
|
|
693
|
+
|
|
694
|
+
Quagga.decodeSingle({
|
|
695
|
+
src: './barcode.jpg',
|
|
696
|
+
decoder: {
|
|
697
|
+
readers: ['code_128_reader'],
|
|
698
|
+
debug: {
|
|
699
|
+
printReaderInfo: true // Shows reader registration
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
}, (result) => {
|
|
703
|
+
// Check console for debug output
|
|
704
|
+
if (result) {
|
|
705
|
+
console.log('Decoded:', result.codeResult.code);
|
|
706
|
+
}
|
|
707
|
+
});
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
## Development vs Production {#development-vs-production}
|
|
711
|
+
|
|
712
|
+
**Development builds** (`dist/quagga.js` or when using webpack dev server):
|
|
713
|
+
|
|
714
|
+
- Debug flags work
|
|
715
|
+
- Console output visible
|
|
716
|
+
- Larger file size
|
|
717
|
+
|
|
718
|
+
**Production builds** (`dist/quagga.min.js`):
|
|
719
|
+
|
|
720
|
+
- Debug flags are stripped out (no-op)
|
|
721
|
+
- No console output
|
|
722
|
+
- Smaller file size
|
|
723
|
+
|
|
724
|
+
To enable debug output in production:
|
|
725
|
+
|
|
726
|
+
1. Use the development build (`quagga.js` instead of `quagga.min.js`)
|
|
727
|
+
2. Set `ENV.development = true` before importing Quagga
|
|
728
|
+
|
|
729
|
+
## Summary {#summary}
|
|
730
|
+
|
|
731
|
+
Quagga2 provides **19 debug flags** organized into three categories:
|
|
732
|
+
|
|
733
|
+
**Console logging** (4 flags) - Minimal performance impact:
|
|
734
|
+
|
|
735
|
+
- `inputStream.debug.showImageDetails` - Frame grabber and image loading
|
|
736
|
+
- `decoder.debug.printReaderInfo` - Reader registration
|
|
737
|
+
- `locator.debug.showPatchSize` - Patch dimensions
|
|
738
|
+
- `locator.debug.showImageDetails` - Canvas initialization
|
|
739
|
+
|
|
740
|
+
**Visual canvas overlays** (13 flags) - Moderate to high performance impact:
|
|
741
|
+
|
|
742
|
+
- `decoder.debug.drawBoundingBox` - Barcode location box
|
|
743
|
+
- `decoder.debug.drawScanline` - Scan path
|
|
744
|
+
- `locator.debug.showCanvas` - Locator's internal canvas
|
|
745
|
+
- `locator.debug.showPatches` - All extracted patches
|
|
746
|
+
- `locator.debug.showFoundPatches` - Candidate patches
|
|
747
|
+
- `locator.debug.showSkeleton` - Skeleton structure
|
|
748
|
+
- `locator.debug.showLabels` - Component labels
|
|
749
|
+
- `locator.debug.showPatchLabels` - Patch labels
|
|
750
|
+
- `locator.debug.showRemainingPatchLabels` - Post-filter labels
|
|
751
|
+
- `locator.debug.boxFromPatches.showTransformed` - Transformed coordinates
|
|
752
|
+
- `locator.debug.boxFromPatches.showTransformedBox` - Transformed box
|
|
753
|
+
- `locator.debug.boxFromPatches.showBB` - Final bounding box
|
|
754
|
+
|
|
755
|
+
**Performance analysis** (2 flags) - High impact:
|
|
756
|
+
|
|
757
|
+
- `decoder.debug.showFrequency` - Signal frequency data
|
|
758
|
+
- `decoder.debug.showPattern` - Pattern extraction data
|
|
759
|
+
|
|
760
|
+
**Debugging strategy**: Start with console logging flags, then add visual overlays as needed. Disable all flags in production.
|
|
761
|
+
|
|
762
|
+
## Related {#related}
|
|
763
|
+
|
|
764
|
+
- [Configuration Reference](../reference/configuration.md) - Complete config documentation
|
|
765
|
+
- [Optimize Performance](optimize-performance.md) - Speed up barcode detection
|
|
766
|
+
- [Handle Difficult Barcodes](handle-difficult-barcodes.md) - Improve detection accuracy
|
|
767
|
+
|
|
768
|
+
## Changelog {#changelog}
|
|
769
|
+
|
|
770
|
+
**v1.8.4+** (November 2025): Debug flags introduced to replace always-on console spam
|
|
771
|
+
|
|
772
|
+
Prior versions logged debug information unconditionally, making it difficult to debug application code. The new flag system provides fine-grained control over diagnostic output.
|
|
773
|
+
|
|
774
|
+
---
|
|
775
|
+
|
|
776
|
+
**Questions?** Ask in [Gitter Chat](https://gitter.im/quaggaJS/Lobby) or [open an issue](https://github.com/ericblade/quagga2/issues).
|