@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.
- package/DEPENDENCIES.md +286 -0
- package/HALFSAMPLE_PERFORMANCE_ANALYSIS.md +178 -0
- package/README.md +119 -10
- package/dist/quagga.js +11087 -10681
- package/dist/quagga.min.js +4 -3
- 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 +3140 -2757
- package/package.json +22 -18
- package/type-definitions/quagga.d.ts +111 -9
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
# Quagga2 Dependencies
|
|
2
|
+
|
|
3
|
+
This document explains the dependency structure of Quagga2 and clarifies which packages are runtime code dependencies versus build/test tools.
|
|
4
|
+
|
|
5
|
+
## Background
|
|
6
|
+
|
|
7
|
+
Quagga2 bundles all its code with Webpack, producing standalone browser and Node.js builds. As a result, **all packages are listed as `devDependencies`** in `package.json` because consumers never directly install them - they only use the pre-built bundles in `dist/` and `lib/`.
|
|
8
|
+
|
|
9
|
+
However, this makes it unclear which packages are actual code dependencies (bundled into the final output) versus which are just build/test tools. This document clarifies that distinction.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Runtime Code Dependencies
|
|
14
|
+
|
|
15
|
+
These packages contain code that is **imported by the source code** and **bundled into the final output**:
|
|
16
|
+
|
|
17
|
+
### Core Libraries
|
|
18
|
+
|
|
19
|
+
- **`gl-matrix`** (^3.4.4)
|
|
20
|
+
- **Purpose**: High-performance vector and matrix math operations
|
|
21
|
+
- **Usage**: Used throughout the codebase for geometric calculations
|
|
22
|
+
- **Files**:
|
|
23
|
+
- `src/quagga/quagga.ts` - vec2 operations for bounding boxes
|
|
24
|
+
- `src/quagga/initBuffers.ts` - vec2 for buffer initialization
|
|
25
|
+
- `src/locator/barcode_locator.js` - vec2, mat2 for barcode location
|
|
26
|
+
- `src/common/image_wrapper.ts` - vec2 for image transforms
|
|
27
|
+
- `src/common/cvutils/ImageRef.ts` - vec2, vec3 for computer vision
|
|
28
|
+
- `src/common/cluster.js` - vec2 for clustering algorithms
|
|
29
|
+
|
|
30
|
+
- **`lodash`** (^4.17.21)
|
|
31
|
+
- **Purpose**: Utility functions for object manipulation
|
|
32
|
+
- **Usage**: Primarily `merge()` for config merging, `pick()` for object selection
|
|
33
|
+
- **Files**:
|
|
34
|
+
- `src/quagga.js` - merge() for configuration
|
|
35
|
+
- `src/QuaggaStatic.ts` - merge() for configuration
|
|
36
|
+
- `src/reader/ean_reader.ts` - merge() for config defaults
|
|
37
|
+
- `src/reader/i2of5_reader.ts` - merge() for config defaults
|
|
38
|
+
- `src/input/camera_access.ts` - pick() for MediaTrackConstraints
|
|
39
|
+
- `src/locator/test/barcode_locator.spec.ts` - merge() in tests
|
|
40
|
+
|
|
41
|
+
### Image Processing
|
|
42
|
+
|
|
43
|
+
- **`ndarray`** (^1.0.19)
|
|
44
|
+
- **Purpose**: N-dimensional array manipulation
|
|
45
|
+
- **Usage**: Core data structure for image data processing
|
|
46
|
+
- **Files**:
|
|
47
|
+
- `src/input/input_stream/input_stream_base.ts` - NdArray type definitions
|
|
48
|
+
- `src/input/input_stream/input_stream.ts` - NdArray for frame data
|
|
49
|
+
- `src/input/frame_grabber.ts` - Ndarray for frame manipulation
|
|
50
|
+
- `src/vendor.d.ts` - Type definitions
|
|
51
|
+
|
|
52
|
+
- **`ndarray-linear-interpolate`** (^1.0.0)
|
|
53
|
+
- **Purpose**: Bilinear interpolation for ndarray data
|
|
54
|
+
- **Usage**: Image scaling and transformations
|
|
55
|
+
- **Files**:
|
|
56
|
+
- `src/input/frame_grabber.ts` - `d2()` method for 2D interpolation
|
|
57
|
+
|
|
58
|
+
- **`ndarray-pixels`** (^5.0.1)
|
|
59
|
+
- **Purpose**: Convert between image formats and ndarray
|
|
60
|
+
- **Usage**: Loading image data from various sources
|
|
61
|
+
- **Files**:
|
|
62
|
+
- `src/input/input_stream/input_stream.ts` - `getPixels()` for image loading
|
|
63
|
+
|
|
64
|
+
### Polyfills (Deprecated)
|
|
65
|
+
|
|
66
|
+
- **`@babel/polyfill`** (^7.12.1)
|
|
67
|
+
- **Status**: ⚠️ **DEPRECATED** by Babel team
|
|
68
|
+
- **Purpose**: Legacy polyfill for ES6+ features
|
|
69
|
+
- **Current Usage**: Not directly imported in source code
|
|
70
|
+
- **Recommendation**: Should be removed in favor of `core-js` + `regenerator-runtime` or Babel's automatic polyfill injection
|
|
71
|
+
- **Migration Path**: Use `@babel/preset-env` with `useBuiltIns: 'usage'` and explicit `core-js@3`
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Build & Development Tools
|
|
76
|
+
|
|
77
|
+
These packages are **only used during build/development** and are **not bundled into the final output**:
|
|
78
|
+
|
|
79
|
+
### TypeScript Toolchain
|
|
80
|
+
|
|
81
|
+
- **`typescript`** (^5.9.3) - TypeScript compiler
|
|
82
|
+
- **`@types/*`** packages - Type definitions for TypeScript
|
|
83
|
+
- `@types/chai`, `@types/gl-vec2`, `@types/lodash`, `@types/mocha`, `@types/node`, `@types/sinon`, `@types/sinon-chai`
|
|
84
|
+
|
|
85
|
+
### Webpack & Bundling
|
|
86
|
+
|
|
87
|
+
- **`webpack`** (^4.44.2) - Module bundler (used to create `dist/` and `lib/` outputs)
|
|
88
|
+
- **`webpack-cli`** (^3.3.12) - Webpack command-line interface
|
|
89
|
+
- **`babel-loader`** (^8.2.5) - Webpack loader for Babel transpilation
|
|
90
|
+
- **`source-map-loader`** (^1.1.1) - Webpack loader for source maps
|
|
91
|
+
|
|
92
|
+
### Babel Transpilation
|
|
93
|
+
|
|
94
|
+
- **`@babel/core`** (^7.28.5) - Babel compiler core
|
|
95
|
+
- **`@babel/preset-env`** (^7.28.5) - Smart transpilation based on target environments
|
|
96
|
+
- **`@babel/preset-typescript`** (^7.28.5) - TypeScript support in Babel
|
|
97
|
+
- **`@babel/plugin-*`** - Various syntax plugins:
|
|
98
|
+
- `@babel/plugin-proposal-class-properties`
|
|
99
|
+
- `@babel/plugin-proposal-nullish-coalescing-operator`
|
|
100
|
+
- `@babel/plugin-proposal-object-rest-spread`
|
|
101
|
+
- `@babel/plugin-proposal-optional-chaining`
|
|
102
|
+
- `@babel/plugin-transform-runtime`
|
|
103
|
+
- **`@babel/runtime`** (^7.28.4) - Babel runtime helpers
|
|
104
|
+
- **`babel-plugin-add-module-exports`** (^1.0.4) - CommonJS module.exports handling
|
|
105
|
+
- **`babel-plugin-istanbul`** (^7.0.1) - Code coverage instrumentation
|
|
106
|
+
|
|
107
|
+
### Testing
|
|
108
|
+
|
|
109
|
+
- **`mocha`** (^5.2.0) - Test framework
|
|
110
|
+
- **`chai`** (^4.3.10) - Assertion library
|
|
111
|
+
- **`sinon`** (^21.0.0) - Test spies, stubs, and mocks
|
|
112
|
+
- **`sinon-chai`** (^3.7.0) - Sinon assertions for Chai
|
|
113
|
+
- **`ts-mocha`** (^11.1.0) - TypeScript support for Mocha
|
|
114
|
+
- **`ts-node`** (^10.9.2) - TypeScript execution for Node.js
|
|
115
|
+
- **`cypress`** (^13.1.0) - End-to-end browser testing
|
|
116
|
+
- **`@cypress/webpack-preprocessor`** (6.0.0) - Webpack integration for Cypress
|
|
117
|
+
- **`@cypress/code-coverage`** (^3.12.4) - Code coverage for Cypress tests
|
|
118
|
+
- **`nyc`** (^17.1.0) - Code coverage tool (Istanbul wrapper)
|
|
119
|
+
|
|
120
|
+
### Linting & Code Quality
|
|
121
|
+
|
|
122
|
+
- **`eslint`** (^8.57.1) - JavaScript/TypeScript linter
|
|
123
|
+
- **`@typescript-eslint/eslint-plugin`** (^7.18.0) - TypeScript-specific ESLint rules
|
|
124
|
+
- **`@typescript-eslint/parser`** (^7.18.0) - TypeScript parser for ESLint
|
|
125
|
+
- **`eslint-config-airbnb-base`** (^15.0.0) - Airbnb JavaScript style guide
|
|
126
|
+
- **`eslint-config-airbnb-typescript`** (^18.0.0) - Airbnb style for TypeScript
|
|
127
|
+
- **`eslint-config-airbnb-typescript-base`** (^6.0.1) - Base Airbnb TypeScript config
|
|
128
|
+
- **`eslint-plugin-import`** (^2.32.0) - Import/export validation
|
|
129
|
+
- **`eslint-plugin-jsx-a11y`** (^6.10.2) - Accessibility linting
|
|
130
|
+
- **`eslint-plugin-typescript-sort-keys`** (^3.3.0) - Enforce sorted object keys
|
|
131
|
+
|
|
132
|
+
### Utilities
|
|
133
|
+
|
|
134
|
+
- **`core-js`** (^3.46.0) - Modern JavaScript polyfills (used by Babel)
|
|
135
|
+
- **`cross-env`** (^10.1.0) - Cross-platform environment variable setting
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Optional Dependencies
|
|
140
|
+
|
|
141
|
+
- **`fsevents`** (2.3.3)
|
|
142
|
+
- **Platform**: macOS only
|
|
143
|
+
- **Purpose**: Native file watching for better performance
|
|
144
|
+
- **Usage**: Automatically used by Webpack/build tools on macOS
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Overrides
|
|
149
|
+
|
|
150
|
+
The `overrides` field forces specific versions of transitive dependencies:
|
|
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`.
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## Bundle Size Impact
|
|
164
|
+
|
|
165
|
+
When evaluating dependencies, consider their impact on bundle size:
|
|
166
|
+
|
|
167
|
+
| Package | Approximate Size | Bundled? |
|
|
168
|
+
|---------|-----------------|----------|
|
|
169
|
+
| `gl-matrix` | ~50 KB (minified) | ✅ Yes |
|
|
170
|
+
| `lodash` | ~4 KB (only `merge` + `pick`) | ✅ Yes (tree-shaken) |
|
|
171
|
+
| `ndarray` | ~5 KB | ✅ Yes |
|
|
172
|
+
| `ndarray-linear-interpolate` | ~2 KB | ✅ Yes |
|
|
173
|
+
| `ndarray-pixels` | ~10 KB | ✅ Yes (browser) |
|
|
174
|
+
| `webpack` | ~1.5 MB | ❌ No (dev only) |
|
|
175
|
+
| `typescript` | ~50 MB | ❌ No (dev only) |
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Adding New Dependencies
|
|
180
|
+
|
|
181
|
+
When adding a new dependency, consider:
|
|
182
|
+
|
|
183
|
+
1. **Is it a runtime dependency?**
|
|
184
|
+
- Will the code be `import`ed in `src/` files?
|
|
185
|
+
- Will it be bundled into `dist/` or `lib/` output?
|
|
186
|
+
- → Add to `devDependencies` (all deps go here due to bundling)
|
|
187
|
+
- → Document it in the "Runtime Code Dependencies" section above
|
|
188
|
+
|
|
189
|
+
2. **Is it a build/test tool?**
|
|
190
|
+
- Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
|
|
191
|
+
- → Add to `devDependencies`
|
|
192
|
+
- → Document it in the "Build & Development Tools" section above
|
|
193
|
+
|
|
194
|
+
3. **Bundle size impact?**
|
|
195
|
+
- Run `npm run build` and check the size change in `dist/quagga.min.js`
|
|
196
|
+
- Consider tree-shaking (does the library support ES modules?)
|
|
197
|
+
- Look for lighter alternatives if the package is large
|
|
198
|
+
|
|
199
|
+
4. **Browser compatibility?**
|
|
200
|
+
- Does the package work in browsers?
|
|
201
|
+
- Does it require Node.js-specific APIs (`fs`, `path`, etc.)?
|
|
202
|
+
- → Check if it's already shimmed in `configs/webpack.config.js` (e.g., `node: { fs: 'empty' }`)
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Version Constraints
|
|
207
|
+
|
|
208
|
+
### Pinned Versions
|
|
209
|
+
|
|
210
|
+
Some packages are pinned to specific versions due to compatibility issues:
|
|
211
|
+
|
|
212
|
+
- **`mocha@^5.2.0`** - Pinned to v5 because newer versions have breaking changes
|
|
213
|
+
- **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
|
|
214
|
+
- **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
|
|
215
|
+
- **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
|
|
216
|
+
- **`cypress@^13.1.0`** - Pinned to v13 for stability
|
|
217
|
+
|
|
218
|
+
These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
|
|
219
|
+
|
|
220
|
+
### Upgrade Policy
|
|
221
|
+
|
|
222
|
+
- **TypeScript ecosystem** (`typescript`, `@typescript-eslint/*`, `ts-*`): Keep up-to-date
|
|
223
|
+
- **Babel ecosystem** (`@babel/*`): Keep up-to-date for security and features
|
|
224
|
+
- **Testing tools** (`mocha`, `chai`, `sinon`): Upgrade cautiously, test thoroughly
|
|
225
|
+
- **Webpack & bundlers**: Major version upgrades require careful migration planning
|
|
226
|
+
- **Runtime dependencies** (`gl-matrix`, `lodash`, `ndarray*`): Keep up-to-date unless breaking changes occur
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## Security Considerations
|
|
231
|
+
|
|
232
|
+
### Known Issues
|
|
233
|
+
|
|
234
|
+
1. **`@babel/polyfill` is deprecated** - Should migrate to `core-js@3` + `regenerator-runtime`
|
|
235
|
+
2. **Old `mocha` version** - v5.2.0 is from 2018, may have unpatched vulnerabilities
|
|
236
|
+
3. **Webpack 4** - No longer receives updates, consider upgrading to Webpack 5
|
|
237
|
+
|
|
238
|
+
### Monitoring
|
|
239
|
+
|
|
240
|
+
- Run `npm audit` regularly to check for vulnerabilities
|
|
241
|
+
- Use `npm run check-updates` to see available updates
|
|
242
|
+
- Check GitHub Dependabot alerts
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## FAQ
|
|
247
|
+
|
|
248
|
+
**Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
|
|
249
|
+
|
|
250
|
+
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
|
+
|
|
252
|
+
**Q: How can I tell if a package is actually used in the code?**
|
|
253
|
+
|
|
254
|
+
A: Search the `src/` directory:
|
|
255
|
+
```bash
|
|
256
|
+
# Search for imports
|
|
257
|
+
grep -r "from 'package-name'" src/
|
|
258
|
+
grep -r 'from "package-name"' src/
|
|
259
|
+
grep -r "require('package-name')" src/
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Q: What's the difference between `optionalDependencies` and `devDependencies`?**
|
|
263
|
+
|
|
264
|
+
A: `optionalDependencies` are packages that enhance functionality if available but aren't required (like `fsevents` for macOS file watching). `devDependencies` are required for development but not for using the published package.
|
|
265
|
+
|
|
266
|
+
**Q: Can I remove `@babel/polyfill`?**
|
|
267
|
+
|
|
268
|
+
A: Yes, but carefully. It's deprecated and not directly imported anymore. Remove it from `package.json` and verify that `@babel/preset-env` is configured to polyfill features automatically via `core-js@3`. Test thoroughly in older browsers (IE11, older Safari) after removal.
|
|
269
|
+
|
|
270
|
+
**Q: Why can't I upgrade `chai` to version 5 or 6?**
|
|
271
|
+
|
|
272
|
+
A: `chai@5+` and `chai@6+` are ESM-only (ES modules). Quagga2's tests use CommonJS (`require()`), and `mocha@5` doesn't support ESM. Upgrading `chai` requires also upgrading `mocha` to v9.1.0+ and migrating all test files to ESM syntax.
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Related Files
|
|
277
|
+
|
|
278
|
+
- **`package.json`** - Dependency declarations
|
|
279
|
+
- **`.ncurc.json`** - npm-check-updates configuration (blocks unsafe auto-upgrades)
|
|
280
|
+
- **`configs/webpack.config.js`** - Build configuration showing which dependencies are bundled
|
|
281
|
+
- **`configs/webpack.node.config.js`** - Node.js-specific build configuration
|
|
282
|
+
- **`CHANGELOG.md`** - Version history and dependency changes
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
## Maintenance Notes
|
|
287
|
+
|
|
288
|
+
This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:
|
|
289
|
+
|
|
290
|
+
- A new dependency is added or removed
|
|
291
|
+
- A major version upgrade changes behavior
|
|
292
|
+
- Security vulnerabilities are discovered and patched
|
|
293
|
+
- Build tooling changes significantly
|
|
294
|
+
|
|
295
|
+
Last updated: 2025-11-16
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Reference Documentation
|
|
2
|
+
|
|
3
|
+
Precise technical descriptions of Quagga2's API, configuration, and capabilities. Consult these when you need exact details about how something works.
|
|
4
|
+
|
|
5
|
+
## Core API
|
|
6
|
+
|
|
7
|
+
### [API Documentation](api.md)
|
|
8
|
+
|
|
9
|
+
Complete reference for all Quagga2 methods, callbacks, and events.
|
|
10
|
+
|
|
11
|
+
### [Configuration Options](configuration.md)
|
|
12
|
+
|
|
13
|
+
Detailed documentation of every configuration parameter and its effects.
|
|
14
|
+
|
|
15
|
+
### [Camera Access API](camera-access.md)
|
|
16
|
+
|
|
17
|
+
Methods for controlling camera access, torch/flash, and device enumeration.
|
|
18
|
+
|
|
19
|
+
## Barcode Support
|
|
20
|
+
|
|
21
|
+
### [Supported Barcode Types](readers.md)
|
|
22
|
+
|
|
23
|
+
List of all supported barcode formats with characteristics and use cases.
|
|
24
|
+
|
|
25
|
+
## Compatibility
|
|
26
|
+
|
|
27
|
+
### [Browser Support](browser-support.md)
|
|
28
|
+
|
|
29
|
+
Browser compatibility matrix and required Web APIs.
|
|
30
|
+
|
|
31
|
+
## Development
|
|
32
|
+
|
|
33
|
+
### [Dependencies](dependencies.md)
|
|
34
|
+
|
|
35
|
+
Explanation of all package dependencies - which are bundled vs. dev-only.
|
|
36
|
+
|
|
37
|
+
## Quick Lookup
|
|
38
|
+
|
|
39
|
+
| Need | See |
|
|
40
|
+
|------|-----|
|
|
41
|
+
| Method signatures | [API Documentation](api.md) |
|
|
42
|
+
| Config parameter details | [Configuration Options](configuration.md) |
|
|
43
|
+
| Which browsers work | [Browser Support](browser-support.md) |
|
|
44
|
+
| Which barcodes supported | [Supported Barcode Types](readers.md) |
|
|
45
|
+
| Camera control | [Camera Access API](camera-access.md) |
|
|
46
|
+
| Package versions | [Dependencies](dependencies.md) |
|
|
47
|
+
|
|
48
|
+
## Reading Reference Docs
|
|
49
|
+
|
|
50
|
+
Reference documentation is:
|
|
51
|
+
|
|
52
|
+
- **Information-oriented** - Focuses on describing *what exists*
|
|
53
|
+
- **Accurate** - Every detail matters, kept up-to-date with code
|
|
54
|
+
- **Complete** - Covers all features, even obscure ones
|
|
55
|
+
- **Structured** - Organized for lookup, not linear reading
|
|
56
|
+
|
|
57
|
+
Don't read reference docs cover-to-cover. Instead:
|
|
58
|
+
|
|
59
|
+
1. **Look up** what you need when you need it
|
|
60
|
+
2. **Verify** assumptions about how things work
|
|
61
|
+
3. **Discover** features you didn't know existed
|
|
62
|
+
4. **Confirm** exact method signatures or parameter types
|
|
63
|
+
|
|
64
|
+
## Need Context?
|
|
65
|
+
|
|
66
|
+
Reference docs tell you *what* and *how*, but not *why*:
|
|
67
|
+
|
|
68
|
+
- For **why** something works a certain way → See [Explanation](../explanation/)
|
|
69
|
+
- For **how to use** something in practice → See [How-To Guides](../how-to-guides/)
|
|
70
|
+
- For **learning** from scratch → See [Tutorials](../tutorials/)
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
[← Back to Documentation Home](../index.md)
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# Supported Barcode Types {#supported-barcode-types}
|
|
2
|
+
|
|
3
|
+
Quagga2 supports a wide variety of 1D barcode formats. This page lists all available barcode readers and how to configure them.
|
|
4
|
+
|
|
5
|
+
## Available Readers {#available-readers}
|
|
6
|
+
|
|
7
|
+
Quagga2 includes built-in readers for the following barcode formats:
|
|
8
|
+
|
|
9
|
+
| Reader Name | Barcode Format | Common Uses |
|
|
10
|
+
|-------------|----------------|-------------|
|
|
11
|
+
| `code_128_reader` | [Code 128](https://en.wikipedia.org/wiki/Code_128) | General purpose, shipping, packaging |
|
|
12
|
+
| `ean_reader` | [EAN-13](https://en.wikipedia.org/wiki/International_Article_Number) | Retail products worldwide |
|
|
13
|
+
| `ean_8_reader` | [EAN-8](https://en.wikipedia.org/wiki/EAN-8) | Small retail products |
|
|
14
|
+
| `code_39_reader` | [Code 39](https://en.wikipedia.org/wiki/Code_39) | Automotive, defense, healthcare |
|
|
15
|
+
| `code_39_vin_reader` | Code 39 VIN | Vehicle Identification Numbers |
|
|
16
|
+
| `codabar_reader` | [Codabar](https://en.wikipedia.org/wiki/Codabar) | Libraries, blood banks, logistics |
|
|
17
|
+
| `upc_reader` | [UPC-A](https://en.wikipedia.org/wiki/Universal_Product_Code) | Retail products (North America) |
|
|
18
|
+
| `upc_e_reader` | [UPC-E](https://en.wikipedia.org/wiki/Universal_Product_Code#UPC-E) | Small retail products |
|
|
19
|
+
| `i2of5_reader` | [Interleaved 2 of 5](https://en.wikipedia.org/wiki/Interleaved_2_of_5) | Warehouse, distribution |
|
|
20
|
+
| `2of5_reader` | [Standard 2 of 5](https://en.wikipedia.org/wiki/Two-out-of-five_code) | Industrial, airline tickets |
|
|
21
|
+
| `code_93_reader` | [Code 93](https://en.wikipedia.org/wiki/Code_93) | Logistics, retail |
|
|
22
|
+
| `code_32_reader` | [Code 32](https://en.wikipedia.org/wiki/Pharmacode#Code_32) | Italian pharmaceuticals |
|
|
23
|
+
|
|
24
|
+
## Basic Configuration {#basic-configuration}
|
|
25
|
+
|
|
26
|
+
Specify which barcode types to detect in the `decoder.readers` array:
|
|
27
|
+
|
|
28
|
+
```javascript
|
|
29
|
+
Quagga.init({
|
|
30
|
+
decoder: {
|
|
31
|
+
readers: ["code_128_reader"] // Only detect Code 128
|
|
32
|
+
}
|
|
33
|
+
}, function(err) {
|
|
34
|
+
if (err) {
|
|
35
|
+
console.error(err);
|
|
36
|
+
return;
|
|
37
|
+
}
|
|
38
|
+
Quagga.start();
|
|
39
|
+
});
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Multiple Readers {#multiple-readers}
|
|
43
|
+
|
|
44
|
+
You can enable multiple readers to detect different barcode types:
|
|
45
|
+
|
|
46
|
+
```javascript
|
|
47
|
+
Quagga.init({
|
|
48
|
+
decoder: {
|
|
49
|
+
readers: [
|
|
50
|
+
"code_128_reader",
|
|
51
|
+
"ean_reader",
|
|
52
|
+
"upc_reader"
|
|
53
|
+
]
|
|
54
|
+
}
|
|
55
|
+
});
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Important Considerations {#important-considerations}
|
|
59
|
+
|
|
60
|
+
### Reader Priority and Order {#reader-priority-and-order}
|
|
61
|
+
|
|
62
|
+
**Readers are processed in the exact order they appear in the `readers` array.** The first reader to successfully decode the barcode wins - subsequent readers are not tried.
|
|
63
|
+
|
|
64
|
+
This allows you to prioritize certain formats over others when multiple formats might match the same barcode pattern:
|
|
65
|
+
|
|
66
|
+
```javascript
|
|
67
|
+
decoder: {
|
|
68
|
+
// EAN-13 checked first, then UPC formats
|
|
69
|
+
readers: ['ean_reader', 'upc_reader', 'upc_e_reader']
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**Why order matters:**
|
|
74
|
+
|
|
75
|
+
- Readers are processed sequentially, not in parallel
|
|
76
|
+
- Some readers may return false positives for other formats
|
|
77
|
+
- Example: EAN-13 and UPC-A/UPC-E share similar patterns and can clash
|
|
78
|
+
- The first successful decode is returned immediately
|
|
79
|
+
|
|
80
|
+
**Best practice**: List your most commonly expected barcode types first for best accuracy and performance.
|
|
81
|
+
|
|
82
|
+
### Don't Enable All Readers {#dont-enable-all-readers}
|
|
83
|
+
|
|
84
|
+
**Why not enable all readers by default?**
|
|
85
|
+
|
|
86
|
+
- More readers = more processing time
|
|
87
|
+
- Increased chance of false positives
|
|
88
|
+
- Some formats overlap and can interfere
|
|
89
|
+
|
|
90
|
+
**Best practice**: Only enable the barcode formats you actually need to scan.
|
|
91
|
+
|
|
92
|
+
### Format Conflicts {#format-conflicts}
|
|
93
|
+
|
|
94
|
+
Some barcode formats are subsets or extensions of others:
|
|
95
|
+
|
|
96
|
+
- **UPC-A** is a subset of **EAN-13**
|
|
97
|
+
- **EAN-8** is shorter version of **EAN-13**
|
|
98
|
+
- **Code 39** and **Code 39 VIN** share similar patterns
|
|
99
|
+
|
|
100
|
+
Be careful when enabling multiple related formats together.
|
|
101
|
+
|
|
102
|
+
## EAN Extensions {#ean-extensions}
|
|
103
|
+
|
|
104
|
+
### EAN-2 and EAN-5 Supplements {#ean-supplements}
|
|
105
|
+
|
|
106
|
+
The EAN and UPC barcode formats support a supplement format, adding an additional 2 or 5 digits beyond the main barcode, EAN-2 and EAN-5, respectively. They are typically used for:
|
|
107
|
+
- **Magazines and periodicals**: The main barcode identifies the publication, while the supplement denotes issue numbers or publication dates
|
|
108
|
+
- **Books with ISBN**: The 5-digit supplement often encodes the suggested retail price
|
|
109
|
+
|
|
110
|
+
By default, `ean_reader` does not read and decode these extensions, you must explicitly enable support for them, if you are looking for them. Since UPC-A is a subset of EAN-13 -- UPC-A codes are EAN-13 codes that begin with a 0 -- supplement support configured on `ean_reader` also works for UPC-A codes.
|
|
111
|
+
|
|
112
|
+
To enable supplement decoding:
|
|
113
|
+
|
|
114
|
+
```javascript
|
|
115
|
+
Quagga.init({
|
|
116
|
+
decoder: {
|
|
117
|
+
readers: [{
|
|
118
|
+
format: "ean_reader",
|
|
119
|
+
config: {
|
|
120
|
+
supplements: [
|
|
121
|
+
'ean_5_reader', // 5-digit supplement
|
|
122
|
+
'ean_2_reader' // 2-digit supplement
|
|
123
|
+
]
|
|
124
|
+
}
|
|
125
|
+
}]
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
#### Supplement Result Structure {#supplement-result-structure}
|
|
131
|
+
|
|
132
|
+
When a barcode with a supplement is decoded, the result includes a `supplement` property:
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
{
|
|
136
|
+
codeResult: {
|
|
137
|
+
code: "419871600890101", // Combined: main barcode + supplement
|
|
138
|
+
format: "ean_13", // Main barcode format
|
|
139
|
+
supplement: {
|
|
140
|
+
code: "01", // Supplement digits only
|
|
141
|
+
format: "ean_2" // "ean_2" or "ean_5"
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The main `codeResult.code` contains the full combined value, while `codeResult.supplement` provides the supplement details separately.
|
|
148
|
+
|
|
149
|
+
### Important Notes About Supplements {#supplements-notes}
|
|
150
|
+
|
|
151
|
+
**Supplement order matters**: The reader stops when it finds the first matching supplement. List `ean_5_reader` before `ean_2_reader` if you want to prioritize 5-digit extensions.
|
|
152
|
+
|
|
153
|
+
**Cannot read regular EAN-13 with supplements enabled**: If you configure supplements, that reader instance can **only** decode EAN codes **with** supplements. To read both:
|
|
154
|
+
|
|
155
|
+
```javascript
|
|
156
|
+
Quagga.init({
|
|
157
|
+
decoder: {
|
|
158
|
+
readers: [
|
|
159
|
+
"ean_reader", // Regular EAN-13 without supplements
|
|
160
|
+
{
|
|
161
|
+
format: "ean_reader",
|
|
162
|
+
config: {
|
|
163
|
+
supplements: ['ean_5_reader', 'ean_2_reader']
|
|
164
|
+
}
|
|
165
|
+
} // EAN-13 with supplements
|
|
166
|
+
]
|
|
167
|
+
}
|
|
168
|
+
});
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
This configuration creates two separate reader instances.
|
|
172
|
+
|
|
173
|
+
## External Readers {#external-readers}
|
|
174
|
+
|
|
175
|
+
Quagga2 supports external reader modules for additional barcode formats not built into the core library.
|
|
176
|
+
|
|
177
|
+
### QR Code Reader {#qr-code-reader}
|
|
178
|
+
|
|
179
|
+
For QR code support, see [quagga2-reader-qr](https://github.com/ericblade/quagga2-reader-qr).
|
|
180
|
+
|
|
181
|
+
External readers extend Quagga2's capabilities beyond 1D barcodes:
|
|
182
|
+
|
|
183
|
+
```javascript
|
|
184
|
+
import Quagga from '@ericblade/quagga2';
|
|
185
|
+
import QRReader from 'quagga2-reader-qr';
|
|
186
|
+
|
|
187
|
+
// Register external reader
|
|
188
|
+
Quagga.registerReader('qr', QRReader);
|
|
189
|
+
|
|
190
|
+
Quagga.init({
|
|
191
|
+
decoder: {
|
|
192
|
+
readers: ['qr'] // Use external QR reader
|
|
193
|
+
}
|
|
194
|
+
});
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
### External Reader Priority {#external-reader-priority}
|
|
198
|
+
|
|
199
|
+
External readers follow the **same priority rules** as built-in readers. Once registered with `Quagga.registerReader()`, an external reader can be placed anywhere in the `readers` array, and its position determines when it attempts to decode relative to other readers:
|
|
200
|
+
|
|
201
|
+
```javascript
|
|
202
|
+
// Register external reader first
|
|
203
|
+
Quagga.registerReader('my_custom_reader', MyCustomReader);
|
|
204
|
+
|
|
205
|
+
// Use in config - position determines priority
|
|
206
|
+
Quagga.init({
|
|
207
|
+
decoder: {
|
|
208
|
+
// External reader tried first, then built-in readers
|
|
209
|
+
readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
|
|
210
|
+
}
|
|
211
|
+
});
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**Key points:**
|
|
215
|
+
- External readers must be registered via `registerReader()` before use
|
|
216
|
+
- Their position in `readers` array determines decode priority
|
|
217
|
+
- There is no automatic "internal first, external second" ordering
|
|
218
|
+
- External readers interleave freely with built-in readers
|
|
219
|
+
|
|
220
|
+
### Creating Custom Readers {#creating-custom-readers}
|
|
221
|
+
|
|
222
|
+
You can create your own barcode reader implementations by extending the `BarcodeReader` prototype exported by Quagga2. See [How-To: Create External Readers](../how-to-guides/external-readers.md) for details.
|
|
223
|
+
|
|
224
|
+
## Reader Performance {#reader-performance}
|
|
225
|
+
|
|
226
|
+
Different readers have different performance characteristics:
|
|
227
|
+
|
|
228
|
+
**Fastest readers**:
|
|
229
|
+
|
|
230
|
+
- `code_128_reader` - Optimized, widely used
|
|
231
|
+
- `ean_reader` - Fast and reliable
|
|
232
|
+
|
|
233
|
+
**Slower readers**:
|
|
234
|
+
|
|
235
|
+
- `code_39_reader` - More complex pattern
|
|
236
|
+
- `i2of5_reader` - Requires more validation
|
|
237
|
+
|
|
238
|
+
**Resource intensive**:
|
|
239
|
+
|
|
240
|
+
- Multiple readers enabled simultaneously
|
|
241
|
+
- Readers with supplements configured
|
|
242
|
+
|
|
243
|
+
## Validation {#validation}
|
|
244
|
+
|
|
245
|
+
Some barcode formats include check digits for validation:
|
|
246
|
+
|
|
247
|
+
- **EAN-13/EAN-8**: Built-in check digit
|
|
248
|
+
- **Code 128**: Built-in check digit
|
|
249
|
+
- **UPC-A/UPC-E**: Built-in check digit
|
|
250
|
+
|
|
251
|
+
For additional validation in your application, consider using [barcode-validator](https://github.com/ericblade/barcode-validator).
|
|
252
|
+
|
|
253
|
+
## Related {#related}
|
|
254
|
+
|
|
255
|
+
- [Configuration Reference](configuration.md) - Complete config options
|
|
256
|
+
- [API Documentation](api.md) - How to use Quagga2 methods
|
|
257
|
+
- [Tips & Tricks](../how-to-guides/tips-and-tricks.md) - Handling false positives
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
[← Back to Reference](index.md)
|