@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,254 @@
1
+ # Working with Box Coordinates {#working-with-box-coordinates}
2
+
3
+ This guide explains how Quagga2's coordinate system works and how to properly use `box`, `boxes`, and `line` coordinates for overlay rendering, especially when using `inputStream.size` to scale processing.
4
+
5
+ ## Understanding the Coordinate System {#understanding-coordinate-system}
6
+
7
+ Quagga2 returns `box`, `boxes`, and `line` coordinates in **processed canvas coordinates**, not original image/video coordinates. This is important to understand when:
8
+
9
+ - Drawing overlay boxes on a video element
10
+ - Using `inputStream.size` to reduce processing resolution
11
+ - Cropping detected barcode regions from the original image
12
+
13
+ ### Key Concepts {#key-concepts}
14
+
15
+ | Term | Description |
16
+ |------|-------------|
17
+ | **Real Size** | The actual dimensions of the source image/video |
18
+ | **Processed Size** | The scaled dimensions used for barcode detection (controlled by `inputStream.size`) |
19
+ | **Canvas Size** | The dimensions of the processing canvas (typically matches processed size) |
20
+
21
+ ### How Coordinates are Generated {#how-coordinates-generated}
22
+
23
+ 1. **Image Scaling**: When `inputStream.size` is set, the image is scaled so the longest side equals that value
24
+ 2. **Localization**: Barcode regions are found in the scaled image
25
+ 3. **Box Coordinates**: Returned coordinates are relative to the scaled/processed image
26
+ 4. **halfSample Adjustment**: If `halfSample: true`, coordinates are automatically scaled 2x
27
+
28
+ ## Converting Coordinates to Original Image Space {#converting-coordinates}
29
+
30
+ When you need to draw boxes on the original video/image (not the processed canvas), you must scale the coordinates.
31
+
32
+ ### For Live Video Streams {#live-video-streams}
33
+
34
+ ```javascript
35
+ Quagga.onDetected(function(result) {
36
+ if (!result.box) return;
37
+
38
+ // Get the video element
39
+ const video = document.querySelector('video');
40
+ const videoWidth = video.videoWidth; // Real video dimensions
41
+ const videoHeight = video.videoHeight;
42
+
43
+ // Get processed dimensions from Quagga
44
+ const canvas = Quagga.canvas.dom.image;
45
+ const processedWidth = canvas.width;
46
+ const processedHeight = canvas.height;
47
+
48
+ // Calculate scale factors
49
+ const scaleX = videoWidth / processedWidth;
50
+ const scaleY = videoHeight / processedHeight;
51
+
52
+ // Convert box coordinates to video space
53
+ const scaledBox = result.box.map(function(point) {
54
+ return [
55
+ point[0] * scaleX,
56
+ point[1] * scaleY
57
+ ];
58
+ });
59
+
60
+ // Now use scaledBox for drawing on video overlay
61
+ drawBoxOnVideo(scaledBox);
62
+ });
63
+ ```
64
+
65
+ ### For Static Images with decodeSingle {#static-images-decodesingle}
66
+
67
+ ```javascript
68
+ Quagga.decodeSingle({
69
+ src: './barcode.jpg',
70
+ inputStream: {
71
+ size: 800 // Process at 800px max dimension
72
+ },
73
+ // ... other config
74
+ }, function(result) {
75
+ if (!result || !result.box) return;
76
+
77
+ // Load original image to get real dimensions
78
+ const img = new Image();
79
+ img.onload = function() {
80
+ const realWidth = img.naturalWidth;
81
+ const realHeight = img.naturalHeight;
82
+
83
+ // Calculate what the processed size was
84
+ const aspectRatio = realWidth / realHeight;
85
+ let processedWidth, processedHeight;
86
+
87
+ if (aspectRatio > 1) {
88
+ // Landscape: width is the longest side
89
+ processedWidth = 800;
90
+ processedHeight = Math.floor(800 / aspectRatio);
91
+ } else {
92
+ // Portrait: height is the longest side
93
+ processedHeight = 800;
94
+ processedWidth = Math.floor(800 * aspectRatio);
95
+ }
96
+
97
+ // Calculate scale factors
98
+ const scaleX = realWidth / processedWidth;
99
+ const scaleY = realHeight / processedHeight;
100
+
101
+ // Convert coordinates
102
+ const scaledBox = result.box.map(function(point) {
103
+ return [
104
+ point[0] * scaleX,
105
+ point[1] * scaleY
106
+ ];
107
+ });
108
+
109
+ // Use scaledBox for original image operations
110
+ cropBarcodeFromOriginal(scaledBox);
111
+ };
112
+ img.src = './barcode.jpg';
113
+ });
114
+ ```
115
+
116
+ ## Complete Example: Drawing Boxes on Live Video {#complete-example}
117
+
118
+ Here's a complete example showing how to draw accurate bounding boxes on a live video stream:
119
+
120
+ ```javascript
121
+ // Initialize Quagga with reduced processing size for performance
122
+ Quagga.init({
123
+ inputStream: {
124
+ name: "Live",
125
+ type: "LiveStream",
126
+ target: document.querySelector('#scanner-container'),
127
+ constraints: {
128
+ width: 1280,
129
+ height: 720,
130
+ facingMode: "environment"
131
+ },
132
+ size: 640 // Process at 640px for better performance
133
+ },
134
+ locator: {
135
+ patchSize: "medium",
136
+ halfSample: true
137
+ },
138
+ decoder: {
139
+ readers: ["code_128_reader", "ean_reader"]
140
+ }
141
+ }, function(err) {
142
+ if (err) {
143
+ console.error(err);
144
+ return;
145
+ }
146
+ Quagga.start();
147
+ });
148
+
149
+ // Handle detections with coordinate scaling
150
+ Quagga.onDetected(function(result) {
151
+ const video = document.querySelector('video');
152
+ const overlay = document.querySelector('#overlay-canvas');
153
+ const ctx = overlay.getContext('2d');
154
+
155
+ // Match overlay to video size
156
+ overlay.width = video.videoWidth;
157
+ overlay.height = video.videoHeight;
158
+
159
+ // Get processed canvas size
160
+ const processedCanvas = Quagga.canvas.dom.image;
161
+
162
+ // Calculate scale factors
163
+ const scaleX = video.videoWidth / processedCanvas.width;
164
+ const scaleY = video.videoHeight / processedCanvas.height;
165
+
166
+ // Clear previous drawings
167
+ ctx.clearRect(0, 0, overlay.width, overlay.height);
168
+
169
+ // Draw all detected boxes
170
+ if (result.boxes) {
171
+ result.boxes.forEach(function(box) {
172
+ drawScaledBox(ctx, box, scaleX, scaleY, '#00ff00');
173
+ });
174
+ }
175
+
176
+ // Highlight the successfully decoded box
177
+ if (result.box) {
178
+ drawScaledBox(ctx, result.box, scaleX, scaleY, '#ff0000');
179
+ }
180
+ });
181
+
182
+ function drawScaledBox(ctx, box, scaleX, scaleY, color) {
183
+ ctx.strokeStyle = color;
184
+ ctx.lineWidth = 2;
185
+ ctx.beginPath();
186
+
187
+ // Scale and draw each point
188
+ const scaledPoints = box.map(p => [p[0] * scaleX, p[1] * scaleY]);
189
+
190
+ ctx.moveTo(scaledPoints[0][0], scaledPoints[0][1]);
191
+ for (let i = 1; i < scaledPoints.length; i++) {
192
+ ctx.lineTo(scaledPoints[i][0], scaledPoints[i][1]);
193
+ }
194
+ ctx.closePath();
195
+ ctx.stroke();
196
+ }
197
+ ```
198
+
199
+ ## When Coordinates Don't Need Scaling {#no-scaling-needed}
200
+
201
+ If you're drawing on Quagga's own overlay canvas (`Quagga.canvas.dom.overlay`), coordinates are already in the correct space:
202
+
203
+ ```javascript
204
+ Quagga.onDetected(function(result) {
205
+ const ctx = Quagga.canvas.ctx.overlay;
206
+ const canvas = Quagga.canvas.dom.overlay;
207
+
208
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
209
+
210
+ // No scaling needed - coordinates match the overlay canvas
211
+ if (result.box) {
212
+ Quagga.ImageDebug.drawPath(result.box, { x: 0, y: 1 }, ctx, {
213
+ color: "#00ff00",
214
+ lineWidth: 2
215
+ });
216
+ }
217
+ });
218
+ ```
219
+
220
+ ## Common Pitfalls {#common-pitfalls}
221
+
222
+ ### 1. Forgetting halfSample Adjustment {#forgetting-halfsample}
223
+
224
+ If you're manually calculating processed size, remember that `halfSample: true` doesn't affect the returned coordinates (they're already adjusted).
225
+
226
+ ### 2. Using Wrong Canvas Reference {#wrong-canvas-reference}
227
+
228
+ ```javascript
229
+ // ❌ Wrong - using overlay canvas for scale calculation
230
+ const wrongWidth = Quagga.canvas.dom.overlay.width;
231
+
232
+ // ✅ Correct - using image canvas for scale calculation
233
+ const correctWidth = Quagga.canvas.dom.image.width;
234
+ ```
235
+
236
+ ### 3. Assuming Square Pixels {#assuming-square-pixels}
237
+
238
+ Always calculate scaleX and scaleY separately, as aspect ratios may differ:
239
+
240
+ ```javascript
241
+ // ❌ Wrong - using single scale factor
242
+ const scale = videoWidth / canvasWidth;
243
+
244
+ // ✅ Correct - separate scale factors
245
+ const scaleX = videoWidth / canvasWidth;
246
+ const scaleY = videoHeight / canvasHeight;
247
+ ```
248
+
249
+ ## Performance Tips {#performance-tips}
250
+
251
+ 1. **Use smaller `inputStream.size`** (e.g., 640-800) for live video to reduce CPU usage
252
+ 2. **Cache scale factors** - recalculate only when video dimensions change
253
+ 3. **Use requestAnimationFrame** for smooth overlay rendering
254
+ 4. **Consider using Quagga's built-in overlay** when possible to avoid manual scaling
package/docs/index.md ADDED
@@ -0,0 +1,118 @@
1
+ # Quagga2 Documentation
2
+
3
+
4
+ Welcome to the Quagga2 documentation! Quagga2 is a JavaScript barcode scanner library supporting real-time location (localization) and decoding of various barcode types in both browser and Node.js environments.
5
+
6
+ ![Badge](https://hitscounter.dev/api/hit?url=https%3A%2F%2Fericblade.github.io%2Fquagga2%2F&label=Views+%28Today%2FTotal%29&icon=link&color=%23198754&message=&style=plastic&tz=US%2FEastern)
7
+ [![Join the chat at https://gitter.im/quaggaJS/Lobby](https://badges.gitter.im/quaggaJS/Lobby.svg)](https://gitter.im/quaggaJS/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
8
+
9
+ ## Quick Links
10
+
11
+ - [GitHub Repository](https://github.com/ericblade/quagga2)
12
+ - [Changelog](https://github.com/ericblade/quagga2/releases)
13
+ - [npm Package](https://www.npmjs.com/package/@ericblade/quagga2)
14
+ - [Live Examples](examples/)
15
+
16
+ ## Getting Started
17
+
18
+ New to Quagga2? Start here:
19
+
20
+ - **[Installation & Quick Start](getting-started.md)** - Get up and running in minutes
21
+
22
+ ---
23
+
24
+ ## Documentation Structure
25
+
26
+ This documentation follows the [Divio Documentation System](https://documentation.divio.com/), organizing content into four types based on what you need:
27
+
28
+ ### 📚 [Tutorials](tutorials/) - *Learning-oriented*
29
+
30
+ Step-by-step lessons to help you learn by doing. Perfect if you're just getting started.
31
+
32
+ - [Your First Barcode Scan](tutorials/first-scan.md) - Scan barcodes with your camera
33
+ - [Decoding Static Images](tutorials/static-image.md) - Process image files
34
+ - [Using with React](tutorials/react-integration.md) - React integration guide
35
+ - [Using with Node.js](tutorials/node-usage.md) - Server-side barcode scanning
36
+
37
+ ### 🛠️ [How-To Guides](how-to-guides/) - *Task-oriented*
38
+
39
+ Practical guides for accomplishing specific goals. Use these when you have a problem to solve.
40
+
41
+ - [Configure Barcode Readers](how-to-guides/configure-readers.md) - Select which barcode types to scan
42
+ - [Optimize Performance](how-to-guides/optimize-performance.md) - Improve speed and accuracy
43
+ - [Handle Difficult Barcodes](how-to-guides/handle-difficult-barcodes.md) - Deal with poor lighting, rotation, etc.
44
+ - [Use Debug Flags](how-to-guides/use-debug-flags.md) - Enable diagnostic output
45
+ - [Create External Readers](how-to-guides/external-readers.md) - Build custom barcode decoder plugins
46
+
47
+ ### 📖 [Reference](reference/) - *Information-oriented*
48
+
49
+ Technical descriptions and API documentation. Look here when you need precise details.
50
+
51
+ - [API Documentation](reference/api.md) - Complete API reference
52
+ - [Configuration Options](reference/configuration.md) - All config parameters explained
53
+ - [Camera Access API](reference/camera-access.md) - Camera control methods
54
+ - [Supported Barcode Types](reference/readers.md) - Available decoders
55
+ - [Browser Support](reference/browser-support.md) - Compatibility information
56
+ - [Dependencies](reference/dependencies.md) - Package dependencies explained
57
+
58
+ ### 💡 [Explanation](explanation/) - *Understanding-oriented*
59
+
60
+ Background, context, and deeper understanding. Read these to learn *why* things work the way they do.
61
+
62
+ - [How Barcode Localization Works](explanation/how-barcode-localization-works.md) - The algorithm behind barcode detection
63
+ - [Algorithm Overview](explanation/algorithm-overview.md) - Image processing pipeline
64
+ - [Architecture](explanation/architecture.md) - Code structure and design decisions
65
+
66
+ ---
67
+
68
+ ## Additional Resources
69
+
70
+ - [Contributing Guide](contributing.md) - How to contribute to Quagga2
71
+ - [Gitter Chat](https://gitter.im/quaggaJS/Lobby) - Ask questions and get help
72
+
73
+ ---
74
+
75
+ ## Framework Integration
76
+
77
+ Using Quagga2 with a specific framework?
78
+
79
+ - **React**: [quagga2-react-example](https://github.com/ericblade/quagga2-react-example/) and [quagga2-redux-middleware](https://github.com/ericblade/quagga2-redux-middleware/)
80
+ - **Angular**: [ngx-barcode-scanner](https://github.com/julienboulay/ngx-barcode-scanner) or [mobile-scanning-demo](https://github.com/classycodeoss/mobile-scanning-demo)
81
+ - **Vue 2**: [vue-quagga-2](https://github.com/DevinNorgarb/vue-quagga-2)
82
+ - **Vue 3**: [vue3-quagga-2](https://github.com/nick-0101/vue3-quagga-2)
83
+ - **ThingWorx**: [ThingworxBarcodeScannerWidget](https://github.com/ptc-iot-sharing/ThingworxBarcodeScannerWidget)
84
+
85
+ ---
86
+
87
+ ## External Readers and Other Related Projects {#external-readers}
88
+
89
+ - **DataMatrix Reader**: [hackathi/quagga2-reader-datamatrix](https://github.com/hackathi/quagga2-reader-datamatrix)
90
+ - **QR Code Reader**: [ericblade/quagga2-qr-code-reader](https://github.com/ericblade/quagga2-qr-code-reader)
91
+ - **PDFBarcodeJS**: [rexshijaku/PDFBarcodeJS](https://github.com/rexshijaku/PDFBarcodeJS)
92
+
93
+ ---
94
+
95
+ ## Who Uses Quagga2? {#who-uses}
96
+ Quagga2 is used by developers worldwide in various applications, including inventory management, retail point-of-sale systems, library systems, and mobile scanning apps. If you're using Quagga2 in your project, let us know!
97
+
98
+ - **Internet Archive Open Library**: [internetarchive/openlibrary](https://github.com/internetarchive/openlibrary)
99
+ - **Grocy**: [grocy/grocy](https://github.com/grocy/grocy)
100
+ - **German Federal Agency For Technical Relief**: [mziech/thw-inventory](https://github.com/mziech/thw-inventory)
101
+ - **Food Coop Shop**: [foodcoopshop/foodcoopshop](https://github.com/foodcoopshop/foodcoopshop)
102
+ - **Rintagi**: [Rintagi/Low-Code-Development-Platform](https://github.com/Rintagi/Low-Code-Development-Platform)
103
+ - **LINE**: [line/line-api-use-case-smart-retail](https://github.com/line/line-api-use-case-smart-retail)
104
+ - **Veganify**: [frontendnetwork/veganify](https://github.com/frontendnetwork/veganify)
105
+ - **Appsemble**: [Appsemble](https://gitlab.com/appsemble/appsemble)
106
+ - **Intake24**: [intake24/intake24](https://github.com/intake24/intake24)
107
+ - **FridgeToPlate**: [COS301-SE-2023/FridgeToPlate](https://github.com/COS301-SE-2023/FridgeToPlate)
108
+ - **Nutri-Scanner**: [kishan9535/Nutri-Scanner](https://github.com/kishan9535/Nutri-Scanner)
109
+ - **Musclog**: [blopa/musclog-app](https://github.com/blopa/musclog-app)
110
+
111
+
112
+ ---
113
+
114
+ ## About This Documentation
115
+
116
+ This documentation is maintained alongside the Quagga2 codebase. If you find errors or have suggestions for improvement, please [open an issue](https://github.com/ericblade/quagga2/issues) or submit a pull request.
117
+
118
+ **Last Updated**: November 2025