@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.
- package/DEPENDENCIES.md +44 -13
- package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
- package/README.md +115 -10
- package/dist/quagga.js +7611 -5195
- 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 +119 -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 +758 -0
- package/docs/reference/browser-support.md +109 -0
- package/docs/reference/camera-access.md +376 -0
- package/docs/reference/configuration.md +1009 -0
- package/docs/reference/dependencies.md +295 -0
- package/docs/reference/index.md +74 -0
- package/docs/reference/readers.md +326 -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 +9362 -5793
- package/package.json +21 -12
- package/type-definitions/quagga.d.ts +91 -10
package/DEPENDENCIES.md
CHANGED
|
@@ -19,6 +19,7 @@ These packages contain code that is **imported by the source code** and **bundle
|
|
|
19
19
|
- **`gl-matrix`** (^3.4.4)
|
|
20
20
|
- **Purpose**: High-performance vector and matrix math operations
|
|
21
21
|
- **Usage**: Used throughout the codebase for geometric calculations
|
|
22
|
+
- **Location**: Listed in `dependencies` (not `devDependencies`) - see [Type Definition Dependencies](#type-definition-dependencies) below
|
|
22
23
|
- **Files**:
|
|
23
24
|
- `src/quagga/quagga.ts` - vec2 operations for bounding boxes
|
|
24
25
|
- `src/quagga/initBuffers.ts` - vec2 for buffer initialization
|
|
@@ -26,6 +27,7 @@ These packages contain code that is **imported by the source code** and **bundle
|
|
|
26
27
|
- `src/common/image_wrapper.ts` - vec2 for image transforms
|
|
27
28
|
- `src/common/cvutils/ImageRef.ts` - vec2, vec3 for computer vision
|
|
28
29
|
- `src/common/cluster.js` - vec2 for clustering algorithms
|
|
30
|
+
- `type-definitions/quagga.d.ts` - vec2 type import for `Moment.vec` property
|
|
29
31
|
|
|
30
32
|
- **`lodash`** (^4.17.21)
|
|
31
33
|
- **Purpose**: Utility functions for object manipulation
|
|
@@ -112,7 +114,7 @@ These packages are **only used during build/development** and are **not bundled
|
|
|
112
114
|
- **`sinon-chai`** (^3.7.0) - Sinon assertions for Chai
|
|
113
115
|
- **`ts-mocha`** (^11.1.0) - TypeScript support for Mocha
|
|
114
116
|
- **`ts-node`** (^10.9.2) - TypeScript execution for Node.js
|
|
115
|
-
- **`cypress`** (^13.
|
|
117
|
+
- **`cypress`** (^13.17.0) - End-to-end browser testing
|
|
116
118
|
- **`@cypress/webpack-preprocessor`** (6.0.0) - Webpack integration for Cypress
|
|
117
119
|
- **`@cypress/code-coverage`** (^3.12.4) - Code coverage for Cypress tests
|
|
118
120
|
- **`nyc`** (^17.1.0) - Code coverage tool (Istanbul wrapper)
|
|
@@ -147,16 +149,7 @@ These packages are **only used during build/development** and are **not bundled
|
|
|
147
149
|
|
|
148
150
|
## Overrides
|
|
149
151
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
```json
|
|
153
|
-
"overrides": {
|
|
154
|
-
"@cypress/request": "^3.0.9"
|
|
155
|
-
}
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
- **Purpose**: Security fix for `form-data` vulnerability (CVE in versions < 2.5.4)
|
|
159
|
-
- **Details**: Cypress 13.1.0 bundles `@cypress/request@3.0.0` which depends on vulnerable `form-data@2.3.3`. This override forces `@cypress/request@^3.0.9` which uses safe `form-data@~4.0.4`.
|
|
152
|
+
No package overrides are currently needed. Cypress 13.17.0+ uses `@cypress/request@^3.0.6` which includes the security fix for the `form-data` vulnerability (versions >= 3.0.6 use `form-data@~4.0.0` which is safe).
|
|
160
153
|
|
|
161
154
|
---
|
|
162
155
|
|
|
@@ -213,7 +206,7 @@ Some packages are pinned to specific versions due to compatibility issues:
|
|
|
213
206
|
- **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
|
|
214
207
|
- **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
|
|
215
208
|
- **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
|
|
216
|
-
- **`cypress@^13.
|
|
209
|
+
- **`cypress@^13.17.0`** - Pinned to v13 for stability
|
|
217
210
|
|
|
218
211
|
These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
|
|
219
212
|
|
|
@@ -243,12 +236,50 @@ These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-ch
|
|
|
243
236
|
|
|
244
237
|
---
|
|
245
238
|
|
|
239
|
+
## Type Definition Dependencies
|
|
240
|
+
|
|
241
|
+
### Exception: `gl-matrix` in `dependencies`
|
|
242
|
+
|
|
243
|
+
While most packages in Quagga2 are listed in `devDependencies` because they are bundled (see [Background](#background)), **`gl-matrix` is an exception** and is listed in `dependencies`.
|
|
244
|
+
|
|
245
|
+
**Why?**
|
|
246
|
+
|
|
247
|
+
The TypeScript type definition file (`type-definitions/quagga.d.ts`) imports `vec2` from `gl-matrix`:
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
import { vec2 } from 'gl-matrix';
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
This type is used in the `Moment` interface:
|
|
254
|
+
|
|
255
|
+
```typescript
|
|
256
|
+
export type Moment = {
|
|
257
|
+
// ... other properties
|
|
258
|
+
vec?: vec2;
|
|
259
|
+
};
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
When TypeScript consumers use Quagga2 with type checking, the TypeScript compiler needs to resolve this import to provide proper type information. If `gl-matrix` were in `devDependencies`, it would not be installed when consumers run `npm install @ericblade/quagga2`, causing TypeScript compilation errors.
|
|
263
|
+
|
|
264
|
+
**Key distinction:**
|
|
265
|
+
|
|
266
|
+
- **Runtime bundling**: `gl-matrix` code IS bundled into `dist/quagga.min.js` - consumers don't need it at runtime
|
|
267
|
+
- **Type resolution**: TypeScript consumers DO need `gl-matrix` installed to resolve types in `quagga.d.ts`
|
|
268
|
+
|
|
269
|
+
This is a special case where type definitions create a true development-time dependency for consumers using TypeScript.
|
|
270
|
+
|
|
271
|
+
---
|
|
272
|
+
|
|
246
273
|
## FAQ
|
|
247
274
|
|
|
248
275
|
**Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
|
|
249
276
|
|
|
250
277
|
A: Quagga2 is a **bundled library**. Consumers install the package and use the pre-built files (`dist/quagga.min.js` or `lib/quagga.js`), not the source code. They never run `npm install` on Quagga2's dependencies. Therefore, from npm's perspective, all packages are development dependencies (used during build), not runtime dependencies (used after install).
|
|
251
278
|
|
|
279
|
+
**Q: Why is `gl-matrix` in `dependencies` if everything else is in `devDependencies`?**
|
|
280
|
+
|
|
281
|
+
A: This is an exception for TypeScript type resolution. The type definition file (`type-definitions/quagga.d.ts`) imports `vec2` from `gl-matrix` to provide proper typing for the `Moment.vec` property. TypeScript consumers need `gl-matrix` installed to resolve these types during compilation. See [Type Definition Dependencies](#type-definition-dependencies) for details.
|
|
282
|
+
|
|
252
283
|
**Q: How can I tell if a package is actually used in the code?**
|
|
253
284
|
|
|
254
285
|
A: Search the `src/` directory:
|
|
@@ -292,4 +323,4 @@ This document was created in November 2025 following the TypeScript 5.9.3 upgrad
|
|
|
292
323
|
- Security vulnerabilities are discovered and patched
|
|
293
324
|
- Build tooling changes significantly
|
|
294
325
|
|
|
295
|
-
Last updated: 2025-
|
|
326
|
+
Last updated: 2025-12-01
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# HalfSample Performance and Accuracy Analysis
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
This document summarizes the results of comprehensive testing of all Quagga2 decoders with both `halfSample: true` and `halfSample: false` configurations.
|
|
6
|
+
|
|
7
|
+
## Test Results Summary
|
|
8
|
+
|
|
9
|
+
**Total Tests**: 283 passing, 38 pending, 26 failing
|
|
10
|
+
**Test Duration**: ~24 seconds
|
|
11
|
+
|
|
12
|
+
All 13 decoder types were tested with both halfSample configurations:
|
|
13
|
+
- ean
|
|
14
|
+
- ean_extended
|
|
15
|
+
- code_128
|
|
16
|
+
- code_128_external (external reader)
|
|
17
|
+
- code_39
|
|
18
|
+
- code_39_vin
|
|
19
|
+
- code_32
|
|
20
|
+
- ean_8
|
|
21
|
+
- upc
|
|
22
|
+
- upc_e
|
|
23
|
+
- codabar
|
|
24
|
+
- i2of5
|
|
25
|
+
- 2of5
|
|
26
|
+
- code_93
|
|
27
|
+
|
|
28
|
+
## Performance Comparison
|
|
29
|
+
|
|
30
|
+
### Summary
|
|
31
|
+
|
|
32
|
+
**Key Finding**: `halfSample: true` is consistently faster across ALL decoders, with performance improvements ranging from 13% to 50%.
|
|
33
|
+
|
|
34
|
+
| Decoder | halfSample: true Avg | halfSample: false Avg | Performance Gain | Tests Passed (both) |
|
|
35
|
+
|---------|---------------------|----------------------|------------------|---------------------|
|
|
36
|
+
| ean | 38.20ms | 48.90ms | 21.9% faster | 10/10 |
|
|
37
|
+
| ean_extended | 51.80ms | 87.10ms | **40.5% faster** | 10/10 |
|
|
38
|
+
| code_128 | 43.00ms | 68.90ms | **37.6% faster** | 10/10 |
|
|
39
|
+
| code_128_external | 41.60ms | 68.20ms | 39.0% faster | 10/10 |
|
|
40
|
+
| code_39 | 50.90ms | 60.10ms | 15.3% faster | 10/10 |
|
|
41
|
+
| code_39_vin | 91.27ms | 172.27ms | **47.0% faster** | 11/11 |
|
|
42
|
+
| code_32 | 351.20ms | 492.10ms | 28.6% faster | 10/10 |
|
|
43
|
+
| ean_8 | 32.38ms | 49.50ms | 34.6% faster | 8/8 |
|
|
44
|
+
| upc | 35.80ms | 44.40ms | 19.4% faster | 10/10 |
|
|
45
|
+
| upc_e | 32.30ms | 46.90ms | 31.1% faster | 10/10 |
|
|
46
|
+
| codabar | 34.20ms | 50.40ms | 32.1% faster | 10/10 |
|
|
47
|
+
| i2of5 | 54.40ms | 64.00ms | 15.0% faster | 5/5 |
|
|
48
|
+
| 2of5 | 51.10ms | 69.40ms | 26.4% faster | 10/10 |
|
|
49
|
+
| code_93 | 48.73ms | 63.82ms | 23.6% faster | 11/11 |
|
|
50
|
+
|
|
51
|
+
### Performance Insights
|
|
52
|
+
|
|
53
|
+
1. **Biggest Performance Gains** (>40% faster):
|
|
54
|
+
- `code_39_vin`: 47.0% faster with halfSample: true
|
|
55
|
+
- `ean_extended`: 40.5% faster with halfSample: true
|
|
56
|
+
- `code_128`: 37.6% faster with halfSample: true
|
|
57
|
+
|
|
58
|
+
2. **Moderate Performance Gains** (25-40% faster):
|
|
59
|
+
- `code_128_external`: 39.0% faster
|
|
60
|
+
- `ean_8`: 34.6% faster
|
|
61
|
+
- `codabar`: 32.1% faster
|
|
62
|
+
- `upc_e`: 31.1% faster
|
|
63
|
+
- `code_32`: 28.6% faster
|
|
64
|
+
- `2of5`: 26.4% faster
|
|
65
|
+
- `code_93`: 23.6% faster
|
|
66
|
+
|
|
67
|
+
3. **Smaller Performance Gains** (<25% faster):
|
|
68
|
+
- `ean`: 21.9% faster
|
|
69
|
+
- `upc`: 19.4% faster
|
|
70
|
+
- `code_39`: 15.3% faster
|
|
71
|
+
- `i2of5`: 15.0% faster
|
|
72
|
+
|
|
73
|
+
## Accuracy Comparison
|
|
74
|
+
|
|
75
|
+
### Failing Tests Analysis
|
|
76
|
+
|
|
77
|
+
**26 total failures** across both configurations, distributed as follows:
|
|
78
|
+
|
|
79
|
+
#### halfSample: false failures (more failures):
|
|
80
|
+
- Some decoders show reduced accuracy with halfSample: false
|
|
81
|
+
- Examples:
|
|
82
|
+
- `ean_extended` with halfSample: false had several failures (images 001, 003, 005, 006)
|
|
83
|
+
- `ean_8` with halfSample: false had incorrect decoding (image-009: got '57790770' instead of '42242215')
|
|
84
|
+
- `code_93` with halfSample: false had multiple failures (images 003, 004, 005, 007, 008, 010)
|
|
85
|
+
- `2of5` with halfSample: false had failures (images 005, 006)
|
|
86
|
+
|
|
87
|
+
#### halfSample: true failures:
|
|
88
|
+
- `code_128` with halfSample: true had one failure (image-004)
|
|
89
|
+
- `i2of5` with halfSample: true had failures (images 002, 004, 005)
|
|
90
|
+
|
|
91
|
+
### Accuracy Insights
|
|
92
|
+
|
|
93
|
+
1. **halfSample: true generally maintains or improves accuracy** while providing significant performance gains
|
|
94
|
+
2. Some specific images fail with halfSample: false that pass with halfSample: true
|
|
95
|
+
3. A few edge cases exist where halfSample: true may have issues (e.g., i2of5, code_128)
|
|
96
|
+
|
|
97
|
+
## Decoder-Specific Recommendations
|
|
98
|
+
|
|
99
|
+
Based on test results, here are recommendations for each decoder:
|
|
100
|
+
|
|
101
|
+
### Decoders that work BEST with halfSample: true
|
|
102
|
+
|
|
103
|
+
These decoders show excellent performance and accuracy with halfSample: true:
|
|
104
|
+
|
|
105
|
+
- **ean** - 21.9% faster, no new failures
|
|
106
|
+
- **ean_extended** - 40.5% faster, significantly better accuracy (4 images fail with halfSample: false)
|
|
107
|
+
- **code_39** - 15.3% faster, no new failures
|
|
108
|
+
- **code_39_vin** - 47.0% faster, no new failures
|
|
109
|
+
- **code_32** - 28.6% faster, no new failures
|
|
110
|
+
- **ean_8** - 34.6% faster, better accuracy (1 image fails with halfSample: false)
|
|
111
|
+
- **upc** - 19.4% faster, better accuracy (2 images fail with halfSample: false)
|
|
112
|
+
- **upc_e** - 31.1% faster, significantly better accuracy (6 images fail with halfSample: false)
|
|
113
|
+
- **codabar** - 32.1% faster, no new failures
|
|
114
|
+
- **2of5** - 26.4% faster, better accuracy (2 images fail with halfSample: false)
|
|
115
|
+
- **code_93** - 23.6% faster, significantly better accuracy (6 images fail with halfSample: false)
|
|
116
|
+
|
|
117
|
+
### Decoders with minor issues on halfSample: true
|
|
118
|
+
|
|
119
|
+
- **code_128** - 37.6% faster, but 2 images fail with halfSample: true (images 003, 004)
|
|
120
|
+
- **Recommendation**: Use halfSample: true for best performance, but be aware of potential edge cases
|
|
121
|
+
|
|
122
|
+
- **i2of5** - 15.0% faster, but 4 images fail with halfSample: true (images 001, 002, 004, 005)
|
|
123
|
+
- **Recommendation**: Consider halfSample: false if accuracy is critical, otherwise use halfSample: true for performance
|
|
124
|
+
|
|
125
|
+
### Summary by Use Case
|
|
126
|
+
|
|
127
|
+
**For maximum performance** (15-47% speed gains):
|
|
128
|
+
- Use `halfSample: true` for all decoders
|
|
129
|
+
- Accept minor accuracy tradeoffs for code_128 and i2of5
|
|
130
|
+
|
|
131
|
+
**For maximum accuracy**:
|
|
132
|
+
- Use `halfSample: true` for: ean, ean_extended, code_39, code_39_vin, code_32, ean_8, upc, upc_e, codabar, 2of5, code_93
|
|
133
|
+
- Consider `halfSample: false` only for i2of5 if accuracy is absolutely critical
|
|
134
|
+
|
|
135
|
+
**Balanced (RECOMMENDED)**:
|
|
136
|
+
- Use `halfSample: true` as default for all decoders
|
|
137
|
+
- Only switch to `halfSample: false` if you encounter specific accuracy issues in production
|
|
138
|
+
|
|
139
|
+
## Recommendations
|
|
140
|
+
|
|
141
|
+
### When to use halfSample: true (RECOMMENDED DEFAULT)
|
|
142
|
+
|
|
143
|
+
✅ **Use halfSample: true for:**
|
|
144
|
+
- **Performance-critical applications** - provides 15-47% speed improvement
|
|
145
|
+
- **Most barcode types** - works reliably across all tested decoders
|
|
146
|
+
- **General use cases** - better balance of speed and accuracy
|
|
147
|
+
|
|
148
|
+
### When to consider halfSample: false
|
|
149
|
+
|
|
150
|
+
⚠️ **Consider halfSample: false only if:**
|
|
151
|
+
- Working specifically with i2of5 barcodes where accuracy is critical
|
|
152
|
+
- Specific accuracy issues are observed with halfSample: true for your use case
|
|
153
|
+
- You have very high-resolution images and can afford the performance penalty
|
|
154
|
+
- You're working with edge cases similar to the failing tests
|
|
155
|
+
|
|
156
|
+
## Conclusion
|
|
157
|
+
|
|
158
|
+
**The data strongly supports using `halfSample: true` as the default configuration** for Quagga2. It provides:
|
|
159
|
+
|
|
160
|
+
1. **Consistent performance improvements** across all decoder types (15-47% faster)
|
|
161
|
+
2. **Equal or better accuracy** in 11 out of 13 decoder types
|
|
162
|
+
3. **Significant speed gains** for complex decoders like code_39_vin (47%), ean_extended (40.5%), and code_128 (37.6%)
|
|
163
|
+
|
|
164
|
+
The only exceptions are:
|
|
165
|
+
- **code_128**: 2 edge case failures with halfSample: true (but much faster)
|
|
166
|
+
- **i2of5**: 4 test failures with halfSample: true (consider halfSample: false if accuracy is critical)
|
|
167
|
+
|
|
168
|
+
For the vast majority of use cases, halfSample: true provides the best balance of performance and accuracy.
|
|
169
|
+
|
|
170
|
+
## Implementation Changes
|
|
171
|
+
|
|
172
|
+
The test suite has been enhanced to:
|
|
173
|
+
- Test all decoders with both halfSample: true and false
|
|
174
|
+
- Collect timing data for performance analysis
|
|
175
|
+
- Provide clear labeling of which configuration is being tested
|
|
176
|
+
- Generate performance summaries after test execution
|
|
177
|
+
|
|
178
|
+
This ensures ongoing monitoring of halfSample impact on both performance and accuracy.
|
package/README.md
CHANGED
|
@@ -10,6 +10,13 @@ This is a fork of the original QuaggaJS library, that will be maintained until s
|
|
|
10
10
|
original author and maintainer returns, or it has been completely replaced by built-in browser and
|
|
11
11
|
node functionality.
|
|
12
12
|
|
|
13
|
+
## 📚 Documentation
|
|
14
|
+
|
|
15
|
+
**[Complete Documentation](https://ericblade.github.io/quagga2/)** - Tutorials, guides, API reference, and more
|
|
16
|
+
(UNDER CONSTRUCTION!!!)
|
|
17
|
+
|
|
18
|
+
Quick links from this README:
|
|
19
|
+
|
|
13
20
|
- [Changelog](https://github.com/ericblade/quagga2/releases)
|
|
14
21
|
- [Browser Support](#browser-support)
|
|
15
22
|
- [Installing](#installing)
|
|
@@ -23,7 +30,7 @@ node functionality.
|
|
|
23
30
|
|
|
24
31
|
## Using React / Redux?
|
|
25
32
|
|
|
26
|
-
Please see also <https://github.com/ericblade/quagga2-react-example/> and <https://github.com/ericblade/quagga2-redux-middleware
|
|
33
|
+
Please see also <https://github.com/ericblade/quagga2-react-example/> and <https://github.com/ericblade/quagga2-redux-middleware/>. For live browser examples, see [docs/examples/](docs/examples/).
|
|
27
34
|
|
|
28
35
|
## Using Angular?
|
|
29
36
|
|
|
@@ -35,18 +42,19 @@ Please see <https://github.com/ptc-iot-sharing/ThingworxBarcodeScannerWidget>
|
|
|
35
42
|
|
|
36
43
|
## Using Vue?
|
|
37
44
|
|
|
38
|
-
|
|
45
|
+
- **Vue 2**: <https://github.com/DevinNorgarb/vue-quagga-2>
|
|
46
|
+
- **Vue 3**: <https://github.com/nick-0101/vue3-quagga-2>
|
|
39
47
|
|
|
40
48
|
## What is QuaggaJS?
|
|
41
49
|
|
|
42
50
|
QuaggaJS is a barcode-scanner entirely written in JavaScript supporting real-time localization and decoding of various types of barcodes such as __EAN__,
|
|
43
51
|
__CODE 128__, __CODE 39__, __EAN 8__, __UPC-A__, __UPC-C__, __I2of5__,
|
|
44
|
-
__2of5__, __CODE 93__, __CODE 32__ and
|
|
52
|
+
__2of5__, __CODE 93__, __CODE 32__, __CODABAR__, and __PHARMACODE__. The library is also capable of using
|
|
45
53
|
`getUserMedia` to get direct access to the user's camera stream. Although the
|
|
46
54
|
code relies on heavy image-processing even recent smartphones are capable of
|
|
47
55
|
locating and decoding barcodes in real-time.
|
|
48
56
|
|
|
49
|
-
Try some [examples](https://
|
|
57
|
+
Try some [examples](https://ericblade.github.io/quagga2/examples) and check out
|
|
50
58
|
the blog post ([How barcode-localization works in QuaggaJS][oberhofer_co_how])
|
|
51
59
|
if you want to dive deeper into this topic.
|
|
52
60
|
|
|
@@ -199,6 +207,25 @@ Quagga2 exports the BarcodeReader prototype, which should also allow you to crea
|
|
|
199
207
|
reader implementations using the base BarcodeReader implementation inside Quagga2. The QR reader
|
|
200
208
|
does not make use of this functionality, as QR is not picked up as a barcode in BarcodeReader.
|
|
201
209
|
|
|
210
|
+
### External Reader Priority
|
|
211
|
+
|
|
212
|
+
External readers follow the same priority rules as built-in readers. Once registered with
|
|
213
|
+
`Quagga.registerReader()`, an external reader can be placed anywhere in the `readers` array,
|
|
214
|
+
and its position determines when it attempts to decode relative to other readers.
|
|
215
|
+
|
|
216
|
+
```javascript
|
|
217
|
+
// Register external reader first
|
|
218
|
+
Quagga.registerReader('my_custom_reader', MyCustomReader);
|
|
219
|
+
|
|
220
|
+
// Use in config - position determines priority
|
|
221
|
+
Quagga.init({
|
|
222
|
+
decoder: {
|
|
223
|
+
// External reader tried first, then built-in readers
|
|
224
|
+
readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
|
|
225
|
+
}
|
|
226
|
+
});
|
|
227
|
+
```
|
|
228
|
+
|
|
202
229
|
## <a name="Building">Building</a>
|
|
203
230
|
|
|
204
231
|
You can build the library yourself by simply cloning the repo and typing:
|
|
@@ -329,6 +356,13 @@ In contrast to the calls described above, this method does not rely on
|
|
|
329
356
|
`getUserMedia` and operates on a single image instead. The provided callback
|
|
330
357
|
is the same as in `onDetected` and contains the result `data` object.
|
|
331
358
|
|
|
359
|
+
**Important**: `decodeSingle` has a built-in default of `inputStream.size: 800`.
|
|
360
|
+
This means images are automatically scaled to 800px on their longest side (both
|
|
361
|
+
larger images scaled down AND smaller images scaled up). The `box`, `boxes`, and
|
|
362
|
+
`line` coordinates in the result are returned in this scaled coordinate space,
|
|
363
|
+
not the original image dimensions. To disable scaling and use original dimensions,
|
|
364
|
+
set `inputStream.size` to `0`.
|
|
365
|
+
|
|
332
366
|
### Quagga.offProcessed(handler)
|
|
333
367
|
|
|
334
368
|
In case the `onProcessed` event is no longer relevant, `offProcessed` removes
|
|
@@ -417,6 +451,8 @@ empty.
|
|
|
417
451
|
Quagga2 exposes a CameraAccess API that is available for performing some shortcut access to commonly
|
|
418
452
|
used camera functions. This API is available as `Quagga.CameraAccess` and is documented below.
|
|
419
453
|
|
|
454
|
+
**[Full CameraAccess API Documentation](https://ericblade.github.io/quagga2/reference/camera-access.html)** - Detailed reference with examples, error handling, and advanced usage.
|
|
455
|
+
|
|
420
456
|
## CameraAccess.request(HTMLVideoElement | null, MediaTrackConstraints?)
|
|
421
457
|
|
|
422
458
|
Will attempt to initialize the camera and start playback given the specified video element. Camera
|
|
@@ -430,11 +466,31 @@ This function will return a Promise that resolves when completed, or rejects on
|
|
|
430
466
|
If a video element is known to be running, this will pause the video element, then return a Promise
|
|
431
467
|
that when resolved will have stopped all tracks in the video element, and released all resources.
|
|
432
468
|
|
|
433
|
-
## CameraAccess.enumerateVideoDevices()
|
|
469
|
+
## CameraAccess.enumerateVideoDevices(constraints?)
|
|
434
470
|
|
|
435
471
|
This will send out a call to navigator.mediaDevices.enumerateDevices(), filter out any mediadevices
|
|
436
472
|
that do not have a kind of 'videoinput', and resolve the promise with an array of MediaDeviceInfo.
|
|
437
473
|
|
|
474
|
+
Optionally, you can pass MediaTrackConstraints to filter devices. When constraints are provided,
|
|
475
|
+
only devices that can satisfy the given constraints will be returned. This is useful for filtering
|
|
476
|
+
out cameras that don't meet your requirements (e.g., eliminating wide-angle cameras).
|
|
477
|
+
|
|
478
|
+
```javascript
|
|
479
|
+
// Get all video devices
|
|
480
|
+
const devices = await Quagga.CameraAccess.enumerateVideoDevices();
|
|
481
|
+
|
|
482
|
+
// Get only devices that support minimum resolution
|
|
483
|
+
const hdDevices = await Quagga.CameraAccess.enumerateVideoDevices({
|
|
484
|
+
width: { min: 1280 },
|
|
485
|
+
height: { min: 720 }
|
|
486
|
+
});
|
|
487
|
+
|
|
488
|
+
// Get only back-facing cameras
|
|
489
|
+
const backCameras = await Quagga.CameraAccess.enumerateVideoDevices({
|
|
490
|
+
facingMode: 'environment'
|
|
491
|
+
});
|
|
492
|
+
```
|
|
493
|
+
|
|
438
494
|
## CameraAccess.getActiveStreamLabel()
|
|
439
495
|
|
|
440
496
|
Returns the label for the active video track
|
|
@@ -447,7 +503,7 @@ Returns the MediaStreamTrack for the active video track
|
|
|
447
503
|
|
|
448
504
|
Turns off Torch. (Camera Flash) Resolves when complete, throws on error. Does not work on iOS devices of at least version 16.4 and earlier. May or may not work on later versions.
|
|
449
505
|
|
|
450
|
-
## CameraAccess
|
|
506
|
+
## CameraAccess.enableTorch()
|
|
451
507
|
|
|
452
508
|
Turns on Torch. (Camera Flash) Resolves when complete, throws on error. Does not work on iOS devices of at least version 16.4 and earlier. May or may not work on later versions.
|
|
453
509
|
|
|
@@ -543,6 +599,12 @@ optional and defines the maximum number of scans per second. This renders
|
|
|
543
599
|
useful for cases where the scan-session is long-running and resources such as
|
|
544
600
|
CPU power are of concern.
|
|
545
601
|
|
|
602
|
+
Note: `frequency` specifies a maximum, not an absolute rate. If the system
|
|
603
|
+
cannot achieve the requested frequency due to CPU limitations, decoding
|
|
604
|
+
complexity, or other factors, scans will occur as fast as the system allows.
|
|
605
|
+
For example, if you set `frequency: 10` but your system can only process 8
|
|
606
|
+
scans per second, you will get approximately 8 scans per second.
|
|
607
|
+
|
|
546
608
|
### decoder
|
|
547
609
|
|
|
548
610
|
QuaggaJS usually runs in a two-stage manner (`locate` is set to `true`) where,
|
|
@@ -581,6 +643,7 @@ barcodes which should be decoded during the session. Possible values are:
|
|
|
581
643
|
- 2of5_reader
|
|
582
644
|
- code_93_reader
|
|
583
645
|
- code_32_reader
|
|
646
|
+
- pharmacode_reader
|
|
584
647
|
|
|
585
648
|
Why are not all types activated by default? Simply because one should
|
|
586
649
|
explicitly define the set of barcodes for their use-case. More decoders means
|
|
@@ -588,6 +651,26 @@ more possible clashes, or false-positives. One should take care of the order
|
|
|
588
651
|
the readers are given, since some might return a value even though it is not
|
|
589
652
|
the correct type (EAN-13 vs. UPC-A).
|
|
590
653
|
|
|
654
|
+
#### Reader Priority and Order
|
|
655
|
+
|
|
656
|
+
**Readers are processed in the exact order they appear in the `readers` array.**
|
|
657
|
+
The first reader to successfully decode the barcode wins. This allows you to
|
|
658
|
+
prioritize certain formats over others when multiple formats might match the
|
|
659
|
+
same barcode pattern.
|
|
660
|
+
|
|
661
|
+
For example, if you know most of your barcodes are EAN-13, place `ean_reader`
|
|
662
|
+
first to ensure it attempts to decode before other readers:
|
|
663
|
+
|
|
664
|
+
```javascript
|
|
665
|
+
decoder: {
|
|
666
|
+
readers: ['ean_reader', 'upc_reader', 'upc_e_reader'] // EAN-13 checked first
|
|
667
|
+
}
|
|
668
|
+
```
|
|
669
|
+
|
|
670
|
+
This is particularly important when dealing with barcode formats that share
|
|
671
|
+
similar patterns (like EAN-13 and UPC-A/UPC-E), where incorrect matches might
|
|
672
|
+
occur if the wrong reader attempts to decode first.
|
|
673
|
+
|
|
591
674
|
The `multiple` property tells the decoder if it should continue decoding after
|
|
592
675
|
finding a valid barcode. If multiple is set to `true`, the results will be
|
|
593
676
|
returned as an array of result objects. Each object in the array will have a
|
|
@@ -689,6 +772,7 @@ Quagga.decodeSingle({
|
|
|
689
772
|
},
|
|
690
773
|
locate: true, // try to locate the barcode in the image
|
|
691
774
|
src: '/test/fixtures/code_128/image-001.jpg' // or 'data:image/jpg;base64,' + data
|
|
775
|
+
// Note: inputStream.size defaults to 800; images are scaled to 800px (up or down).
|
|
692
776
|
}, function(result){
|
|
693
777
|
if(result.codeResult) {
|
|
694
778
|
console.log("result", result.codeResult.code);
|
|
@@ -712,7 +796,7 @@ Quagga.decodeSingle({
|
|
|
712
796
|
src: "image-abc-123.jpg",
|
|
713
797
|
numOfWorkers: 0, // Needs to be 0 when used within node
|
|
714
798
|
inputStream: {
|
|
715
|
-
size: 800 //
|
|
799
|
+
size: 800 // This is the default; shown explicitly for clarity
|
|
716
800
|
},
|
|
717
801
|
decoder: {
|
|
718
802
|
readers: ["code_128_reader"] // List of active readers
|
|
@@ -750,7 +834,7 @@ false-positives.
|
|
|
750
834
|
|
|
751
835
|
Starting in Chrome 59 you can now make use of `capabilities` and directly
|
|
752
836
|
control the zoom of the camera. Head over to the
|
|
753
|
-
[web-cam demo](https://
|
|
837
|
+
[web-cam demo](https://ericblade.github.io/quagga2/examples/live_w_locator.html)
|
|
754
838
|
and check out the __Zoom__ feature.
|
|
755
839
|
|
|
756
840
|
You can read more about those `capabilities` in
|
|
@@ -763,7 +847,7 @@ recognition logic.
|
|
|
763
847
|
|
|
764
848
|
Since Chrome 59 you can turn on/off the __Torch__ of your device and vastly
|
|
765
849
|
improve the quality of the images. Head over to the
|
|
766
|
-
[web-cam demo](https://
|
|
850
|
+
[web-cam demo](https://ericblade.github.io/quagga2/examples/live_w_locator.html)
|
|
767
851
|
and check out the __Torch__ feature.
|
|
768
852
|
|
|
769
853
|
To find out more about this feature [read on](https://www.oberhofer.co/mediastreamtrack-and-its-capabilities).
|
|
@@ -885,8 +969,29 @@ on the ``singleChannel`` flag in the configuration when using ``decodeSingle``.
|
|
|
885
969
|
[upc_wiki]: http://en.wikipedia.org/wiki/Universal_Product_Code
|
|
886
970
|
[ean_8_wiki]: http://en.wikipedia.org/wiki/EAN-8
|
|
887
971
|
[oberhofer_co_how]: http://www.oberhofer.co/how-barcode-localization-works-in-quaggajs/
|
|
888
|
-
[github_examples]: https://
|
|
972
|
+
[github_examples]: https://ericblade.github.io/quagga2/examples
|
|
889
973
|
[i2of5_wiki]: https://en.wikipedia.org/wiki/Interleaved_2_of_5
|
|
890
974
|
[enumerateDevices]: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
|
|
891
975
|
[reactExample]: https://github.com/ericblade/quagga2-react-example
|
|
892
976
|
[issue-94-comment]: https://github.com/serratus/quaggajs/issues/94#issuecomment-571478711
|
|
977
|
+
#### Sequence Mode
|
|
978
|
+
|
|
979
|
+
Quagga2 supports loading a sequence of images for batch processing using the `inputStream.sequence` option. When enabled, Quagga will attempt to load images named in the pattern `image-001.jpg`, `image-002.jpg`, etc., from the specified directory.
|
|
980
|
+
|
|
981
|
+
**Example:**
|
|
982
|
+
```javascript
|
|
983
|
+
Quagga.init({
|
|
984
|
+
inputStream: {
|
|
985
|
+
type: 'ImageStream',
|
|
986
|
+
sequence: true,
|
|
987
|
+
size: 3, // Number of images to load
|
|
988
|
+
offset: 1, // Starting index (optional)
|
|
989
|
+
src: '/path/to/images/', // Base path for images
|
|
990
|
+
},
|
|
991
|
+
decoder: { readers: ['code_128_reader'] }
|
|
992
|
+
});
|
|
993
|
+
```
|
|
994
|
+
|
|
995
|
+
This will load `/path/to/images/image-001.jpg`, `/path/to/images/image-002.jpg`, `/path/to/images/image-003.jpg` for processing.
|
|
996
|
+
|
|
997
|
+
Sequence mode is useful for batch testing or processing multiple images with predictable filenames.
|