0
# Configuration
1
2
ZXing-C++ provides extensive configuration options through the DecodeHints class, allowing fine-tuning of detection performance, accuracy, and behavior for different use cases.
3
4
## DecodeHints Class
5
6
The primary configuration interface for barcode reading operations.
7
8
```cpp { .api }
9
class DecodeHints {
10
public:
11
DecodeHints();
12
13
// Format selection
14
DecodeHints& setFormats(BarcodeFormats formats);
15
BarcodeFormats formats() const noexcept;
16
17
// Performance settings
18
DecodeHints& setTryHarder(bool tryHarder);
19
DecodeHints& setTryRotate(bool tryRotate);
20
DecodeHints& setTryDownscale(bool tryDownscale);
21
DecodeHints& setIsPure(bool isPure);
22
23
// Binarization
24
DecodeHints& setBinarizer(Binarizer binarizer);
25
Binarizer binarizer() const noexcept;
26
27
// Advanced settings
28
DecodeHints& setDownscaleThreshold(uint16_t threshold);
29
DecodeHints& setDownscaleFactor(uint8_t factor);
30
DecodeHints& setMinLineCount(uint8_t count);
31
DecodeHints& setMaxNumberOfSymbols(uint8_t max);
32
DecodeHints& setCharacterSet(std::string charset);
33
34
// Format-specific settings
35
DecodeHints& setTryCode39ExtendedMode(bool enable);
36
DecodeHints& setValidateCode39CheckSum(bool validate);
37
DecodeHints& setValidateITFCheckSum(bool validate);
38
DecodeHints& setReturnCodabarStartEnd(bool returnStartEnd);
39
DecodeHints& setReturnErrors(bool returnErrors);
40
DecodeHints& setEanAddOnSymbol(EanAddOnSymbol addOn);
41
};
42
```
43
44
## Binarization Options
45
46
```cpp { .api }
47
enum class Binarizer : unsigned char {
48
LocalAverage, // Adaptive threshold based on local pixel neighborhoods
49
GlobalHistogram, // Global threshold from histogram analysis
50
FixedThreshold, // Fixed threshold at 127 (fast)
51
BoolCast, // Treat non-zero as black (fastest)
52
};
53
```
54
55
## EAN Add-On Symbol Handling
56
57
```cpp { .api }
58
enum class EanAddOnSymbol : unsigned char {
59
Ignore, // Ignore EAN-2/EAN-5 add-on symbols
60
Read, // Read add-on symbols if present
61
Require, // Require add-on symbols to be present
62
};
63
```
64
65
## Usage Examples
66
67
### Basic Configuration
68
69
```cpp
70
#include "DecodeHints.h"
71
#include "BarcodeFormat.h"
72
73
using namespace ZXing;
74
75
// Default hints (try all formats, moderate performance)
76
DecodeHints defaultHints;
77
78
// Fast scanning for specific formats
79
DecodeHints fastHints;
80
fastHints.setFormats(BarcodeFormat::QRCode | BarcodeFormat::Code128)
81
.setTryHarder(false)
82
.setTryRotate(false)
83
.setTryDownscale(false);
84
85
// High-accuracy scanning
86
DecodeHints accurateHints;
87
accurateHints.setTryHarder(true)
88
.setTryRotate(true)
89
.setMinLineCount(3)
90
.setBinarizer(Binarizer::LocalAverage);
91
```
92
93
### Format-Specific Configuration
94
95
```cpp
96
// QR Code only with high error correction tolerance
97
DecodeHints qrHints;
98
qrHints.setFormats(BarcodeFormat::QRCode)
99
.setReturnErrors(true) // Return results even with errors
100
.setCharacterSet("UTF-8"); // Default character encoding
101
102
// Linear barcodes with validation
103
DecodeHints linearHints;
104
linearHints.setFormats(BarcodeFormat::LinearCodes)
105
.setMinLineCount(2) // Require at least 2 scan lines
106
.setValidateCode39CheckSum(true)
107
.setValidateITFCheckSum(true)
108
.setReturnCodabarStartEnd(true);
109
110
// EAN/UPC with add-on symbols
111
DecodeHints eanHints;
112
eanHints.setFormats(BarcodeFormat::EAN13 | BarcodeFormat::UPCA)
113
.setEanAddOnSymbol(EanAddOnSymbol::Read);
114
```
115
116
### Performance Optimization
117
118
```cpp
119
// Maximum performance for clean images
120
DecodeHints fastClean;
121
fastClean.setFormats(BarcodeFormat::QRCode)
122
.setIsPure(true) // Perfect barcode only
123
.setTryHarder(false)
124
.setTryRotate(false)
125
.setTryDownscale(false)
126
.setBinarizer(Binarizer::FixedThreshold);
127
128
// Performance for large images
129
DecodeHints largeImage;
130
largeImage.setTryDownscale(true)
131
.setDownscaleThreshold(800) // Start downscaling at 800px
132
.setDownscaleFactor(3) // Scale by 1/3
133
.setMaxNumberOfSymbols(5); // Limit to 5 barcodes
134
135
// Performance for poor quality images
136
DecodeHints poorQuality;
137
poorQuality.setTryHarder(true)
138
.setBinarizer(Binarizer::LocalAverage)
139
.setTryRotate(true)
140
.setMinLineCount(1); // Accept single scan line
141
```
142
143
### Binarization Strategies
144
145
```cpp
146
// For images with varying lighting conditions
147
DecodeHints variableLighting;
148
variableLighting.setBinarizer(Binarizer::LocalAverage);
149
150
// For high-contrast, well-lit images
151
DecodeHints highContrast;
152
highContrast.setBinarizer(Binarizer::GlobalHistogram);
153
154
// For already processed/thresholded images
155
DecodeHints preprocessed;
156
preprocessed.setBinarizer(Binarizer::BoolCast);
157
158
// For consistent lighting, fast processing
159
DecodeHints consistent;
160
consistent.setBinarizer(Binarizer::FixedThreshold);
161
```
162
163
### Error Handling Configuration
164
165
```cpp
166
// Return partial results with errors
167
DecodeHints tolerant;
168
tolerant.setReturnErrors(true)
169
.setFormats(BarcodeFormat::QRCode | BarcodeFormat::DataMatrix);
170
171
Result result = ReadBarcode(imageView, tolerant);
172
if (result.error()) {
173
std::cout << "Error type: " << static_cast<int>(result.error().type()) << std::endl;
174
std::cout << "Error message: " << result.error().msg() << std::endl;
175
176
// May still have partial data
177
if (!result.text().empty()) {
178
std::cout << "Partial data: " << result.text() << std::endl;
179
}
180
}
181
```
182
183
### Multiple Symbol Detection
184
185
```cpp
186
// Find up to 10 barcodes in image
187
DecodeHints multiSymbol;
188
multiSymbol.setMaxNumberOfSymbols(10)
189
.setFormats(BarcodeFormat::QRCode | BarcodeFormat::DataMatrix);
190
191
Results results = ReadBarcodes(imageView, multiSymbol);
192
std::cout << "Found " << results.size() << " barcodes" << std::endl;
193
194
// Process all results
195
for (const auto& result : results) {
196
if (result.isValid()) {
197
std::cout << ToString(result.format()) << ": " << result.text() << std::endl;
198
}
199
}
200
```
201
202
### Advanced Format Settings
203
204
```cpp
205
// Code 39 extended mode
206
DecodeHints code39Extended;
207
code39Extended.setFormats(BarcodeFormat::Code39)
208
.setTryCode39ExtendedMode(true)
209
.setValidateCode39CheckSum(true);
210
211
// ITF with GS1 validation
212
DecodeHints itfGS1;
213
itfGS1.setFormats(BarcodeFormat::ITF)
214
.setValidateITFCheckSum(true);
215
216
// Codabar with start/end characters
217
DecodeHints codabar;
218
codabar.setFormats(BarcodeFormat::Codabar)
219
.setReturnCodabarStartEnd(true);
220
```
221
222
## Configuration Patterns
223
224
### Mobile/Camera Applications
225
226
```cpp
227
DecodeHints mobileHints;
228
mobileHints.setFormats(BarcodeFormat::QRCode | BarcodeFormat::EAN13 | BarcodeFormat::UPCA)
229
.setTryRotate(true) // Handle device rotation
230
.setTryDownscale(true) // Handle high-res cameras
231
.setBinarizer(Binarizer::LocalAverage)
232
.setMaxNumberOfSymbols(3); // Limit for real-time performance
233
```
234
235
### Industrial Scanning
236
237
```cpp
238
DecodeHints industrialHints;
239
industrialHints.setFormats(BarcodeFormat::DataMatrix | BarcodeFormat::Code128)
240
.setTryHarder(true) // Maximum accuracy
241
.setMinLineCount(3) // Reliable detection
242
.setValidateITFCheckSum(true)
243
.setBinarizer(Binarizer::LocalAverage);
244
```
245
246
### Document Processing
247
248
```cpp
249
DecodeHints documentHints;
250
documentHints.setFormats(BarcodeFormat::PDF417 | BarcodeFormat::QRCode)
251
.setTryRotate(true) // Documents may be rotated
252
.setTryDownscale(false) // Preserve text quality
253
.setCharacterSet("UTF-8") // Support international text
254
.setReturnErrors(true); // Get partial results
255
```
256
257
### Retail/POS Systems
258
259
```cpp
260
DecodeHints retailHints;
261
retailHints.setFormats(BarcodeFormat::EAN13 | BarcodeFormat::UPCA |
262
BarcodeFormat::EAN8 | BarcodeFormat::UPCE)
263
.setEanAddOnSymbol(EanAddOnSymbol::Read)
264
.setTryHarder(false) // Speed over accuracy
265
.setBinarizer(Binarizer::GlobalHistogram);
266
```
267
268
## Performance vs. Accuracy Trade-offs
269
270
### Maximum Speed Configuration
271
272
```cpp
273
DecodeHints fastest;
274
fastest.setFormats(BarcodeFormat::QRCode) // Single format
275
.setIsPure(true) // Perfect barcode
276
.setTryHarder(false)
277
.setTryRotate(false)
278
.setTryDownscale(false)
279
.setBinarizer(Binarizer::BoolCast) // Fastest binarization
280
.setMaxNumberOfSymbols(1); // Single barcode
281
```
282
283
### Maximum Accuracy Configuration
284
285
```cpp
286
DecodeHints mostAccurate;
287
mostAccurate.setFormats(BarcodeFormat::Any) // All formats
288
.setTryHarder(true) // Thorough search
289
.setTryRotate(true) // All orientations
290
.setTryDownscale(true) // Multiple scales
291
.setBinarizer(Binarizer::LocalAverage)
292
.setMinLineCount(3) // Multiple confirmations
293
.setReturnErrors(true); // Partial results
294
```
295
296
### Balanced Configuration
297
298
```cpp
299
DecodeHints balanced;
300
balanced.setFormats(BarcodeFormat::QRCode | BarcodeFormat::Code128 |
301
BarcodeFormat::EAN13)
302
.setTryHarder(true)
303
.setTryRotate(false) // Skip rotation for speed
304
.setBinarizer(Binarizer::LocalAverage)
305
.setMaxNumberOfSymbols(3);
306
```
307
308
## Best Practices
309
310
1. **Limit formats** to only what you need - dramatically improves performance
311
2. **Use isPure=true** for generated/printed barcodes in controlled environments
312
3. **Choose appropriate binarizer** based on lighting conditions:
313
- LocalAverage: Variable lighting, shadows
314
- GlobalHistogram: Consistent lighting
315
- FixedThreshold: High contrast images
316
- BoolCast: Pre-processed binary images
317
4. **Set realistic symbol limits** for multi-barcode detection
318
5. **Enable error returns** when you need partial/damaged barcode data
319
6. **Configure format-specific options** for better validation
320
7. **Test with representative images** to find optimal settings for your use case