@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,234 @@
|
|
|
1
|
+
# How-To: Create and Use External Readers {#create-and-use-external-readers}
|
|
2
|
+
|
|
3
|
+
This guide explains how to create custom barcode reader plugins and integrate them into Quagga2.
|
|
4
|
+
|
|
5
|
+
## Using Existing External Readers {#using-existing-external-readers}
|
|
6
|
+
|
|
7
|
+
### QR Code Reader {#qr-code-reader}
|
|
8
|
+
|
|
9
|
+
The most common external reader is [quagga2-reader-qr](https://github.com/ericblade/quagga2-reader-qr) for QR code support:
|
|
10
|
+
|
|
11
|
+
```javascript
|
|
12
|
+
import Quagga from '@ericblade/quagga2';
|
|
13
|
+
import QRReader from 'quagga2-reader-qr';
|
|
14
|
+
|
|
15
|
+
// Register the external reader
|
|
16
|
+
Quagga.registerReader('qr', QRReader);
|
|
17
|
+
|
|
18
|
+
// Use it in your config
|
|
19
|
+
Quagga.init({
|
|
20
|
+
decoder: {
|
|
21
|
+
readers: ['qr']
|
|
22
|
+
}
|
|
23
|
+
});
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## External Reader Priority {#external-reader-priority}
|
|
27
|
+
|
|
28
|
+
External readers follow the **same priority rules** as built-in readers:
|
|
29
|
+
|
|
30
|
+
1. **Registration first**: Call `Quagga.registerReader(name, ReaderClass)` before using the reader
|
|
31
|
+
2. **Position determines priority**: The reader's position in the `readers` array determines when it attempts to decode
|
|
32
|
+
3. **First success wins**: The first reader to return a valid result is used
|
|
33
|
+
|
|
34
|
+
### Example: Prioritizing External Readers {#prioritizing-external-readers}
|
|
35
|
+
|
|
36
|
+
```javascript
|
|
37
|
+
// Register external reader
|
|
38
|
+
Quagga.registerReader('my_custom_reader', MyCustomReader);
|
|
39
|
+
|
|
40
|
+
// External reader tried first, then built-in readers
|
|
41
|
+
Quagga.init({
|
|
42
|
+
decoder: {
|
|
43
|
+
readers: ['my_custom_reader', 'ean_reader', 'code_128_reader']
|
|
44
|
+
}
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Example: External Reader as Fallback {#external-reader-fallback}
|
|
49
|
+
|
|
50
|
+
```javascript
|
|
51
|
+
// Register external reader
|
|
52
|
+
Quagga.registerReader('my_fallback_reader', MyFallbackReader);
|
|
53
|
+
|
|
54
|
+
// Built-in readers tried first, external as fallback
|
|
55
|
+
Quagga.init({
|
|
56
|
+
decoder: {
|
|
57
|
+
readers: ['ean_reader', 'code_128_reader', 'my_fallback_reader']
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Creating Custom Readers {#creating-custom-readers}
|
|
63
|
+
|
|
64
|
+
Quagga2 exports the `BarcodeReader` prototype that you can extend to create custom readers.
|
|
65
|
+
|
|
66
|
+
### Basic Reader Structure {#basic-reader-structure}
|
|
67
|
+
|
|
68
|
+
```javascript
|
|
69
|
+
import { Readers } from '@ericblade/quagga2';
|
|
70
|
+
|
|
71
|
+
const { BarcodeReader } = Readers;
|
|
72
|
+
|
|
73
|
+
class MyCustomReader extends BarcodeReader {
|
|
74
|
+
FORMAT = 'my_custom_format';
|
|
75
|
+
|
|
76
|
+
constructor(config, supplements) {
|
|
77
|
+
super(config, supplements);
|
|
78
|
+
// Custom initialization
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
decode(row, start) {
|
|
82
|
+
// Implement barcode decoding logic
|
|
83
|
+
// row: Array<number> - binary line data
|
|
84
|
+
// start: number - starting position
|
|
85
|
+
|
|
86
|
+
// Return null if no barcode found
|
|
87
|
+
// Return Barcode object if successful
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export default MyCustomReader;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Reader Return Format {#reader-return-format}
|
|
96
|
+
|
|
97
|
+
Your `decode()` method should return either `null` (no match) or a result object:
|
|
98
|
+
|
|
99
|
+
```javascript
|
|
100
|
+
{
|
|
101
|
+
code: '1234567890', // The decoded barcode value
|
|
102
|
+
start: 0, // Start position in the row
|
|
103
|
+
end: 100, // End position in the row
|
|
104
|
+
startInfo: { start: 0, end: 10 }, // Start pattern info
|
|
105
|
+
format: 'my_custom_format', // Your reader's format name
|
|
106
|
+
decodedCodes: [...] // Optional: decoded character info
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Pattern Matching Utilities {#pattern-matching-utilities}
|
|
111
|
+
|
|
112
|
+
BarcodeReader provides useful methods for pattern matching:
|
|
113
|
+
|
|
114
|
+
- `_nextSet(line, offset)` - Find next set (1) bit
|
|
115
|
+
- `_nextUnset(line, offset)` - Find next unset (0) bit
|
|
116
|
+
- `_matchPattern(counter, code, maxSingleError)` - Match bar patterns
|
|
117
|
+
- `_fillCounters(offset, end, isWhite)` - Count consecutive bars/spaces
|
|
118
|
+
|
|
119
|
+
### Example: Simple Pattern Reader {#simple-pattern-reader}
|
|
120
|
+
|
|
121
|
+
```javascript
|
|
122
|
+
class SimpleBarReader extends BarcodeReader {
|
|
123
|
+
FORMAT = 'simple_bar';
|
|
124
|
+
START_PATTERN = [1, 1, 1]; // Three bars pattern
|
|
125
|
+
|
|
126
|
+
decode(row, start) {
|
|
127
|
+
if (row) {
|
|
128
|
+
this._row = row;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
// Find start pattern
|
|
132
|
+
const startInfo = this._findPattern(this.START_PATTERN, 0, false);
|
|
133
|
+
if (!startInfo) {
|
|
134
|
+
return null;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// Decode the barcode content
|
|
138
|
+
const result = this._decodeContent(startInfo.end);
|
|
139
|
+
if (!result) {
|
|
140
|
+
return null;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
return {
|
|
144
|
+
code: result.code,
|
|
145
|
+
start: startInfo.start,
|
|
146
|
+
end: result.end,
|
|
147
|
+
startInfo: startInfo,
|
|
148
|
+
format: this.FORMAT
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
_decodeContent(offset) {
|
|
153
|
+
// Implement your decoding logic
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Image-Based Readers {#image-based-readers}
|
|
160
|
+
|
|
161
|
+
For non-linear barcodes (like QR codes), implement `decodeImage()` instead:
|
|
162
|
+
|
|
163
|
+
```javascript
|
|
164
|
+
class MyImageReader extends BarcodeReader {
|
|
165
|
+
FORMAT = 'my_image_format';
|
|
166
|
+
|
|
167
|
+
// Override decode to return null (not a linear barcode)
|
|
168
|
+
decode() {
|
|
169
|
+
return null;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// Implement image-based decoding
|
|
173
|
+
async decodeImage(imageWrapper) {
|
|
174
|
+
// imageWrapper.data - pixel data
|
|
175
|
+
// imageWrapper.size - { x, y } dimensions
|
|
176
|
+
|
|
177
|
+
// Process the image and decode
|
|
178
|
+
const result = await this.processImage(imageWrapper);
|
|
179
|
+
|
|
180
|
+
if (!result) {
|
|
181
|
+
return null;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
return {
|
|
185
|
+
codeResult: {
|
|
186
|
+
code: result.data,
|
|
187
|
+
format: this.FORMAT
|
|
188
|
+
}
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## Testing Your Reader {#testing-your-reader}
|
|
195
|
+
|
|
196
|
+
1. **Unit tests**: Test pattern matching and decoding logic in isolation
|
|
197
|
+
2. **Integration tests**: Use `Quagga.decodeSingle()` with test images
|
|
198
|
+
3. **Live testing**: Test with real camera input
|
|
199
|
+
|
|
200
|
+
### Example Test {#example-test}
|
|
201
|
+
|
|
202
|
+
```javascript
|
|
203
|
+
import Quagga from '@ericblade/quagga2';
|
|
204
|
+
import MyCustomReader from './my-custom-reader';
|
|
205
|
+
|
|
206
|
+
Quagga.registerReader('my_custom', MyCustomReader);
|
|
207
|
+
|
|
208
|
+
const result = await Quagga.decodeSingle({
|
|
209
|
+
src: './test-image.jpg',
|
|
210
|
+
decoder: {
|
|
211
|
+
readers: ['my_custom']
|
|
212
|
+
}
|
|
213
|
+
});
|
|
214
|
+
|
|
215
|
+
console.log('Result:', result?.codeResult?.code);
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
## Best Practices {#best-practices}
|
|
219
|
+
|
|
220
|
+
1. **Set unique FORMAT**: Use a distinctive format name to identify your reader
|
|
221
|
+
2. **Handle edge cases**: Return `null` gracefully when patterns don't match
|
|
222
|
+
3. **Validate checksums**: Implement checksum validation when the format supports it
|
|
223
|
+
4. **Consider performance**: Optimize pattern matching for real-time scanning
|
|
224
|
+
5. **Test thoroughly**: Test with various image qualities and conditions
|
|
225
|
+
|
|
226
|
+
## Related {#related}
|
|
227
|
+
|
|
228
|
+
- [Supported Barcode Types](../reference/readers.md) - Built-in readers
|
|
229
|
+
- [Configuration Reference](../reference/configuration.md) - Full config options
|
|
230
|
+
- [quagga2-reader-qr](https://github.com/ericblade/quagga2-reader-qr) - Example external reader
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
[← Back to How-To Guides](index.md)
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# Handle Difficult Barcodes {#handle-difficult-barcodes}
|
|
2
|
+
|
|
3
|
+
This guide provides techniques for improving barcode detection in challenging conditions.
|
|
4
|
+
|
|
5
|
+
## Common Challenges {#common-challenges}
|
|
6
|
+
|
|
7
|
+
- Poor lighting or shadows
|
|
8
|
+
- Blurry or out-of-focus images
|
|
9
|
+
- Small or distant barcodes
|
|
10
|
+
- Damaged or partially obscured barcodes
|
|
11
|
+
- Low contrast between bars and background
|
|
12
|
+
|
|
13
|
+
## Improving Detection {#improving-detection}
|
|
14
|
+
|
|
15
|
+
### Adjust Patch Size {#adjust-patch-size}
|
|
16
|
+
|
|
17
|
+
For small or distant barcodes, use a smaller patch size:
|
|
18
|
+
|
|
19
|
+
```javascript
|
|
20
|
+
locator: {
|
|
21
|
+
patchSize: "small" // or "x-small" for very small barcodes
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
### Increase Resolution {#increase-resolution}
|
|
26
|
+
|
|
27
|
+
Higher resolution provides more detail:
|
|
28
|
+
|
|
29
|
+
```javascript
|
|
30
|
+
inputStream: {
|
|
31
|
+
size: 1280, // Larger processing size
|
|
32
|
+
constraints: {
|
|
33
|
+
width: { ideal: 1920 },
|
|
34
|
+
height: { ideal: 1080 }
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Disable Half Sampling {#disable-half-sampling}
|
|
40
|
+
|
|
41
|
+
For fine details, process at full resolution:
|
|
42
|
+
|
|
43
|
+
```javascript
|
|
44
|
+
locator: {
|
|
45
|
+
halfSample: false
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Handling False Positives {#handling-false-positives}
|
|
50
|
+
|
|
51
|
+
### Validate Results {#validate-results}
|
|
52
|
+
|
|
53
|
+
Check result confidence and format:
|
|
54
|
+
|
|
55
|
+
```javascript
|
|
56
|
+
Quagga.onDetected(function(result) {
|
|
57
|
+
// Check if result has expected format
|
|
58
|
+
if (result.codeResult.format !== 'ean_13') {
|
|
59
|
+
return; // Ignore unexpected formats
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// Validate checksum externally if needed
|
|
63
|
+
if (!validateBarcode(result.codeResult.code)) {
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
processBarcode(result.codeResult.code);
|
|
68
|
+
});
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Require Multiple Reads {#require-multiple-reads}
|
|
72
|
+
|
|
73
|
+
Confirm detection across multiple frames:
|
|
74
|
+
|
|
75
|
+
```javascript
|
|
76
|
+
let lastCode = null;
|
|
77
|
+
let readCount = 0;
|
|
78
|
+
|
|
79
|
+
Quagga.onDetected(function(result) {
|
|
80
|
+
const code = result.codeResult.code;
|
|
81
|
+
|
|
82
|
+
if (code === lastCode) {
|
|
83
|
+
readCount++;
|
|
84
|
+
if (readCount >= 3) {
|
|
85
|
+
// Confirmed detection
|
|
86
|
+
processBarcode(code);
|
|
87
|
+
readCount = 0;
|
|
88
|
+
}
|
|
89
|
+
} else {
|
|
90
|
+
lastCode = code;
|
|
91
|
+
readCount = 1;
|
|
92
|
+
}
|
|
93
|
+
});
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Using Debug Flags {#using-debug-flags}
|
|
97
|
+
|
|
98
|
+
Enable visual debugging to understand detection issues:
|
|
99
|
+
|
|
100
|
+
```javascript
|
|
101
|
+
Quagga.init({
|
|
102
|
+
debug: true,
|
|
103
|
+
decoder: {
|
|
104
|
+
debug: {
|
|
105
|
+
drawBoundingBox: true,
|
|
106
|
+
drawScanline: true
|
|
107
|
+
}
|
|
108
|
+
},
|
|
109
|
+
locator: {
|
|
110
|
+
debug: {
|
|
111
|
+
showFoundPatches: true
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
See [Use Debug Flags](use-debug-flags.md) for complete details.
|
|
118
|
+
|
|
119
|
+
## Related {#related}
|
|
120
|
+
|
|
121
|
+
- [Configuration Reference](../reference/configuration.md) - All configuration options
|
|
122
|
+
- [Optimize Performance](optimize-performance.md) - Balance accuracy vs speed
|
|
123
|
+
- [Use Debug Flags](use-debug-flags.md) - Diagnostic tools
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
[← Back to How-To Guides](index.md)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# How-To Guides
|
|
2
|
+
|
|
3
|
+
Task-oriented guides for solving specific problems with Quagga2. These assume you have basic familiarity with the library and focus on getting things done.
|
|
4
|
+
|
|
5
|
+
## Configuration & Setup
|
|
6
|
+
|
|
7
|
+
### [Configure Barcode Readers](configure-readers.md)
|
|
8
|
+
|
|
9
|
+
Select which barcode formats to scan (EAN, CODE 128, UPC, etc.) and understand the trade-offs.
|
|
10
|
+
|
|
11
|
+
### [Use Debug Flags](use-debug-flags.md) 🆕
|
|
12
|
+
|
|
13
|
+
Enable diagnostic output to troubleshoot issues with localization, decoding, or camera setup.
|
|
14
|
+
|
|
15
|
+
## Performance & Quality
|
|
16
|
+
|
|
17
|
+
### [Optimize Performance](optimize-performance.md)
|
|
18
|
+
|
|
19
|
+
Improve scanning speed and reduce CPU usage through configuration tuning.
|
|
20
|
+
|
|
21
|
+
### [Handle Difficult Barcodes](handle-difficult-barcodes.md)
|
|
22
|
+
|
|
23
|
+
Techniques for decoding barcodes with poor lighting, damage, rotation, or small size.
|
|
24
|
+
|
|
25
|
+
## Advanced Features
|
|
26
|
+
|
|
27
|
+
### [Create External Readers](external-readers.md)
|
|
28
|
+
|
|
29
|
+
Build custom barcode decoder plugins to support additional formats.
|
|
30
|
+
|
|
31
|
+
## Camera & Input
|
|
32
|
+
|
|
33
|
+
### [Select Specific Camera](select-camera.md) *(Coming Soon)*
|
|
34
|
+
|
|
35
|
+
Choose between front/back cameras on mobile devices or select from multiple USB cameras.
|
|
36
|
+
|
|
37
|
+
### [Adjust Camera Settings](camera-settings.md) *(Coming Soon)*
|
|
38
|
+
|
|
39
|
+
Control focus, zoom, flash/torch, and other camera parameters.
|
|
40
|
+
|
|
41
|
+
## Drawing & Visualization
|
|
42
|
+
|
|
43
|
+
### [Working with Box Coordinates](working-with-coordinates.md) 🆕
|
|
44
|
+
|
|
45
|
+
Understand how `box`, `boxes`, and `line` coordinates relate to processed vs. original image dimensions, and how to properly scale coordinates for overlay rendering on video elements.
|
|
46
|
+
|
|
47
|
+
## Tips & Best Practices
|
|
48
|
+
|
|
49
|
+
### [Tips and Tricks](tips-and-tricks.md)
|
|
50
|
+
|
|
51
|
+
Practical advice for getting the best results with Quagga2, including camera setup, user experience, and handling results.
|
|
52
|
+
|
|
53
|
+
## Integration
|
|
54
|
+
|
|
55
|
+
### [Handle Multiple Barcodes](multiple-barcodes.md) *(Coming Soon)*
|
|
56
|
+
|
|
57
|
+
Detect and decode several barcodes in a single frame simultaneously.
|
|
58
|
+
|
|
59
|
+
### [Scan in Background](background-scanning.md) *(Coming Soon)*
|
|
60
|
+
|
|
61
|
+
Continue scanning while users interact with other UI elements.
|
|
62
|
+
|
|
63
|
+
## Differences from Tutorials
|
|
64
|
+
|
|
65
|
+
**Tutorials** are for learning - they're comprehensive, beginner-friendly, and explain *why* you're doing each step.
|
|
66
|
+
|
|
67
|
+
**How-To Guides** are for doing - they're focused, assume knowledge, and show *how* to accomplish specific goals.
|
|
68
|
+
|
|
69
|
+
If you're new to Quagga2, start with [Tutorials](../tutorials/) instead.
|
|
70
|
+
|
|
71
|
+
## Contributing
|
|
72
|
+
|
|
73
|
+
Have a useful technique or solution to share? We welcome contributions! See the [Contributing Guide](../contributing.md).
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
[← Back to Documentation Home](../index.md)
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Optimize Performance {#optimize-performance}
|
|
2
|
+
|
|
3
|
+
This guide covers techniques to improve Quagga2's barcode scanning performance.
|
|
4
|
+
|
|
5
|
+
## Overview {#overview}
|
|
6
|
+
|
|
7
|
+
Performance optimization in Quagga2 involves balancing accuracy against speed. The key areas to optimize are:
|
|
8
|
+
|
|
9
|
+
- Input resolution and scaling
|
|
10
|
+
- Locator configuration
|
|
11
|
+
- Reader selection
|
|
12
|
+
- Processing frequency
|
|
13
|
+
|
|
14
|
+
## Input Resolution {#input-resolution}
|
|
15
|
+
|
|
16
|
+
### Using `inputStream.size` {#inputstream-size}
|
|
17
|
+
|
|
18
|
+
Reducing the processing resolution is the most effective way to improve performance:
|
|
19
|
+
|
|
20
|
+
```javascript
|
|
21
|
+
Quagga.init({
|
|
22
|
+
inputStream: {
|
|
23
|
+
size: 640 // Process at 640px max dimension instead of full resolution
|
|
24
|
+
}
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
**Recommended values:**
|
|
29
|
+
- **1280px** - High quality, slower (good for static images)
|
|
30
|
+
- **800px** - Balanced (default for `decodeSingle`)
|
|
31
|
+
- **640px** - Fast (recommended for live scanning)
|
|
32
|
+
- **480px** - Very fast (may reduce accuracy)
|
|
33
|
+
|
|
34
|
+
### Camera Constraints {#camera-constraints}
|
|
35
|
+
|
|
36
|
+
Request only the resolution you need:
|
|
37
|
+
|
|
38
|
+
```javascript
|
|
39
|
+
inputStream: {
|
|
40
|
+
constraints: {
|
|
41
|
+
width: { ideal: 1280 },
|
|
42
|
+
height: { ideal: 720 }
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Locator Configuration {#locator-configuration}
|
|
48
|
+
|
|
49
|
+
### Half Sampling {#half-sampling}
|
|
50
|
+
|
|
51
|
+
Keep `halfSample: true` (default) for faster localization:
|
|
52
|
+
|
|
53
|
+
```javascript
|
|
54
|
+
locator: {
|
|
55
|
+
halfSample: true // Processes at half resolution
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Patch Size {#patch-size}
|
|
60
|
+
|
|
61
|
+
Larger patch sizes are faster but may miss small barcodes:
|
|
62
|
+
|
|
63
|
+
```javascript
|
|
64
|
+
locator: {
|
|
65
|
+
patchSize: "large" // Options: x-small, small, medium, large, x-large
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Reader Selection {#reader-selection}
|
|
70
|
+
|
|
71
|
+
Only enable the barcode formats you need:
|
|
72
|
+
|
|
73
|
+
```javascript
|
|
74
|
+
decoder: {
|
|
75
|
+
readers: ["code_128_reader"] // Don't enable all readers
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Processing Frequency {#processing-frequency}
|
|
80
|
+
|
|
81
|
+
Limit scan rate to reduce CPU usage:
|
|
82
|
+
|
|
83
|
+
```javascript
|
|
84
|
+
Quagga.init({
|
|
85
|
+
frequency: 10 // Max 10 scans per second
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Disable Localization {#disable-localization}
|
|
90
|
+
|
|
91
|
+
If barcode position is fixed, disable localization entirely:
|
|
92
|
+
|
|
93
|
+
```javascript
|
|
94
|
+
Quagga.init({
|
|
95
|
+
locate: false,
|
|
96
|
+
inputStream: {
|
|
97
|
+
area: {
|
|
98
|
+
top: "25%",
|
|
99
|
+
right: "25%",
|
|
100
|
+
bottom: "25%",
|
|
101
|
+
left: "25%"
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Related {#related}
|
|
108
|
+
|
|
109
|
+
- [Configuration Reference](../reference/configuration.md) - All configuration options
|
|
110
|
+
- [How Barcode Localization Works](../explanation/how-barcode-localization-works.md) - Understanding the algorithm
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
[← Back to How-To Guides](index.md)
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Tips and Tricks {#tips-and-tricks}
|
|
2
|
+
|
|
3
|
+
Practical advice for getting the best results with Quagga2.
|
|
4
|
+
|
|
5
|
+
## Camera Setup {#camera-setup}
|
|
6
|
+
|
|
7
|
+
### Choosing the Right Camera {#choosing-camera}
|
|
8
|
+
|
|
9
|
+
- Use the **back camera** on mobile devices (higher resolution, autofocus)
|
|
10
|
+
- Request environment-facing camera: `facingMode: "environment"`
|
|
11
|
+
- Avoid wide-angle cameras for barcode scanning
|
|
12
|
+
|
|
13
|
+
### Optimal Distance {#optimal-distance}
|
|
14
|
+
|
|
15
|
+
- Barcode should fill 50-80% of the frame width
|
|
16
|
+
- Too close: barcode may be out of focus
|
|
17
|
+
- Too far: insufficient resolution for small bars
|
|
18
|
+
|
|
19
|
+
## Lighting {#lighting}
|
|
20
|
+
|
|
21
|
+
- Ensure even lighting across the barcode
|
|
22
|
+
- Avoid harsh shadows or reflections
|
|
23
|
+
- Enable torch/flash for dark environments:
|
|
24
|
+
|
|
25
|
+
```javascript
|
|
26
|
+
await Quagga.CameraAccess.enableTorch();
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## User Experience {#user-experience}
|
|
30
|
+
|
|
31
|
+
### Visual Feedback {#visual-feedback}
|
|
32
|
+
|
|
33
|
+
Show users the scan area:
|
|
34
|
+
|
|
35
|
+
```javascript
|
|
36
|
+
inputStream: {
|
|
37
|
+
area: {
|
|
38
|
+
top: "25%",
|
|
39
|
+
right: "10%",
|
|
40
|
+
bottom: "25%",
|
|
41
|
+
left: "10%",
|
|
42
|
+
borderColor: "rgba(0, 255, 0, 0.7)",
|
|
43
|
+
borderWidth: 2
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Audio Feedback {#audio-feedback}
|
|
49
|
+
|
|
50
|
+
Play a sound on successful scan:
|
|
51
|
+
|
|
52
|
+
```javascript
|
|
53
|
+
Quagga.onDetected(function(result) {
|
|
54
|
+
new Audio('/beep.mp3').play();
|
|
55
|
+
processBarcode(result.codeResult.code);
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Performance {#performance}
|
|
60
|
+
|
|
61
|
+
### Reduce CPU Usage {#reduce-cpu-usage}
|
|
62
|
+
|
|
63
|
+
```javascript
|
|
64
|
+
Quagga.init({
|
|
65
|
+
frequency: 10, // Limit to 10 scans/second
|
|
66
|
+
inputStream: {
|
|
67
|
+
size: 640 // Reduce processing resolution
|
|
68
|
+
}
|
|
69
|
+
});
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Stop When Not Needed {#stop-when-not-needed}
|
|
73
|
+
|
|
74
|
+
```javascript
|
|
75
|
+
// Stop scanning when modal closes
|
|
76
|
+
Quagga.stop();
|
|
77
|
+
|
|
78
|
+
// Remove event handlers
|
|
79
|
+
Quagga.offDetected();
|
|
80
|
+
Quagga.offProcessed();
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Handling Results {#handling-results}
|
|
84
|
+
|
|
85
|
+
### Debounce Detections {#debounce-detections}
|
|
86
|
+
|
|
87
|
+
Avoid processing the same barcode multiple times:
|
|
88
|
+
|
|
89
|
+
```javascript
|
|
90
|
+
let lastScanned = '';
|
|
91
|
+
let lastTime = 0;
|
|
92
|
+
|
|
93
|
+
Quagga.onDetected(function(result) {
|
|
94
|
+
const code = result.codeResult.code;
|
|
95
|
+
const now = Date.now();
|
|
96
|
+
|
|
97
|
+
if (code === lastScanned && now - lastTime < 2000) {
|
|
98
|
+
return; // Same barcode within 2 seconds
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
lastScanned = code;
|
|
102
|
+
lastTime = now;
|
|
103
|
+
processBarcode(code);
|
|
104
|
+
});
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Related {#related}
|
|
108
|
+
|
|
109
|
+
- [Optimize Performance](optimize-performance.md) - Detailed performance guide
|
|
110
|
+
- [Handle Difficult Barcodes](handle-difficult-barcodes.md) - Improve detection
|
|
111
|
+
- [Camera Access API](../reference/camera-access.md) - Camera control
|
|
112
|
+
|
|
113
|
+
---
|
|
114
|
+
|
|
115
|
+
[← Back to How-To Guides](index.md)
|