@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,286 @@
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.17.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
+ 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).
151
+
152
+ ---
153
+
154
+ ## Bundle Size Impact
155
+
156
+ When evaluating dependencies, consider their impact on bundle size:
157
+
158
+ | Package | Approximate Size | Bundled? |
159
+ |---------|-----------------|----------|
160
+ | `gl-matrix` | ~50 KB (minified) | ✅ Yes |
161
+ | `lodash` | ~4 KB (only `merge` + `pick`) | ✅ Yes (tree-shaken) |
162
+ | `ndarray` | ~5 KB | ✅ Yes |
163
+ | `ndarray-linear-interpolate` | ~2 KB | ✅ Yes |
164
+ | `ndarray-pixels` | ~10 KB | ✅ Yes (browser) |
165
+ | `webpack` | ~1.5 MB | ❌ No (dev only) |
166
+ | `typescript` | ~50 MB | ❌ No (dev only) |
167
+
168
+ ---
169
+
170
+ ## Adding New Dependencies
171
+
172
+ When adding a new dependency, consider:
173
+
174
+ 1. **Is it a runtime dependency?**
175
+ - Will the code be `import`ed in `src/` files?
176
+ - Will it be bundled into `dist/` or `lib/` output?
177
+ - → Add to `devDependencies` (all deps go here due to bundling)
178
+ - → Document it in the "Runtime Code Dependencies" section above
179
+
180
+ 2. **Is it a build/test tool?**
181
+ - Is it only used by Webpack, Babel, ESLint, Mocha, etc.?
182
+ - → Add to `devDependencies`
183
+ - → Document it in the "Build & Development Tools" section above
184
+
185
+ 3. **Bundle size impact?**
186
+ - Run `npm run build` and check the size change in `dist/quagga.min.js`
187
+ - Consider tree-shaking (does the library support ES modules?)
188
+ - Look for lighter alternatives if the package is large
189
+
190
+ 4. **Browser compatibility?**
191
+ - Does the package work in browsers?
192
+ - Does it require Node.js-specific APIs (`fs`, `path`, etc.)?
193
+ - → Check if it's already shimmed in `configs/webpack.config.js` (e.g., `node: { fs: 'empty' }`)
194
+
195
+ ---
196
+
197
+ ## Version Constraints
198
+
199
+ ### Pinned Versions
200
+
201
+ Some packages are pinned to specific versions due to compatibility issues:
202
+
203
+ - **`mocha@^5.2.0`** - Pinned to v5 because newer versions have breaking changes
204
+ - **`chai@^4.3.10`** - Pinned to v4 because v5+ and v6+ are ESM-only, incompatible with CommonJS tests
205
+ - **`sinon-chai@^3.7.0`** - Pinned to match `chai@4.x` compatibility
206
+ - **`webpack@^4.44.2`** - Pinned to v4 because v5 requires significant config migration
207
+ - **`cypress@^13.17.0`** - Pinned to v13 for stability
208
+
209
+ These are configured in `.ncurc.json` to prevent accidental upgrades via `npm-check-updates`.
210
+
211
+ ### Upgrade Policy
212
+
213
+ - **TypeScript ecosystem** (`typescript`, `@typescript-eslint/*`, `ts-*`): Keep up-to-date
214
+ - **Babel ecosystem** (`@babel/*`): Keep up-to-date for security and features
215
+ - **Testing tools** (`mocha`, `chai`, `sinon`): Upgrade cautiously, test thoroughly
216
+ - **Webpack & bundlers**: Major version upgrades require careful migration planning
217
+ - **Runtime dependencies** (`gl-matrix`, `lodash`, `ndarray*`): Keep up-to-date unless breaking changes occur
218
+
219
+ ---
220
+
221
+ ## Security Considerations
222
+
223
+ ### Known Issues
224
+
225
+ 1. **`@babel/polyfill` is deprecated** - Should migrate to `core-js@3` + `regenerator-runtime`
226
+ 2. **Old `mocha` version** - v5.2.0 is from 2018, may have unpatched vulnerabilities
227
+ 3. **Webpack 4** - No longer receives updates, consider upgrading to Webpack 5
228
+
229
+ ### Monitoring
230
+
231
+ - Run `npm audit` regularly to check for vulnerabilities
232
+ - Use `npm run check-updates` to see available updates
233
+ - Check GitHub Dependabot alerts
234
+
235
+ ---
236
+
237
+ ## FAQ
238
+
239
+ **Q: Why are runtime dependencies in `devDependencies` instead of `dependencies`?**
240
+
241
+ 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).
242
+
243
+ **Q: How can I tell if a package is actually used in the code?**
244
+
245
+ A: Search the `src/` directory:
246
+ ```bash
247
+ # Search for imports
248
+ grep -r "from 'package-name'" src/
249
+ grep -r 'from "package-name"' src/
250
+ grep -r "require('package-name')" src/
251
+ ```
252
+
253
+ **Q: What's the difference between `optionalDependencies` and `devDependencies`?**
254
+
255
+ 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.
256
+
257
+ **Q: Can I remove `@babel/polyfill`?**
258
+
259
+ 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.
260
+
261
+ **Q: Why can't I upgrade `chai` to version 5 or 6?**
262
+
263
+ 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.
264
+
265
+ ---
266
+
267
+ ## Related Files
268
+
269
+ - **`package.json`** - Dependency declarations
270
+ - **`.ncurc.json`** - npm-check-updates configuration (blocks unsafe auto-upgrades)
271
+ - **`configs/webpack.config.js`** - Build configuration showing which dependencies are bundled
272
+ - **`configs/webpack.node.config.js`** - Node.js-specific build configuration
273
+ - **`CHANGELOG.md`** - Version history and dependency changes
274
+
275
+ ---
276
+
277
+ ## Maintenance Notes
278
+
279
+ This document was created in November 2025 following the TypeScript 5.9.3 upgrade. It should be updated whenever:
280
+
281
+ - A new dependency is added or removed
282
+ - A major version upgrade changes behavior
283
+ - Security vulnerabilities are discovered and patched
284
+ - Build tooling changes significantly
285
+
286
+ Last updated: 2025-11-22
@@ -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.