0
# Configuration
1

2
ZXing-C++ provides extensive configuration options through the `ReaderOptions` class, allowing you to optimize barcode detection for specific use cases, image characteristics, and performance requirements.
3

4
## ReaderOptions Class
5

6
The `ReaderOptions` class provides a fluent interface for configuring barcode reading behavior:
7

8
```cpp { .api }
9
class ReaderOptions {
10
    ReaderOptions();
11
    
12
    // Format selection
13
    ReaderOptions& setFormats(BarcodeFormats formats);
14
    BarcodeFormats formats() const noexcept;
15
    
16
    // Performance vs accuracy trade-offs
17
    ReaderOptions& setTryHarder(bool tryHarder);
18
    ReaderOptions& setTryRotate(bool tryRotate);
19
    ReaderOptions& setTryInvert(bool tryInvert);
20
    ReaderOptions& setTryDownscale(bool tryDownscale);
21
    
22
    // Binarization
23
    ReaderOptions& setBinarizer(Binarizer binarizer);
24
    Binarizer binarizer() const noexcept;
25
    
26
    // Image characteristics
27
    ReaderOptions& setIsPure(bool isPure);
28
    ReaderOptions& setDownscaleThreshold(uint16_t threshold);
29
    ReaderOptions& setDownscaleFactor(uint8_t factor);
30
    
31
    // Result filtering
32
    ReaderOptions& setMinLineCount(uint8_t count);
33
    ReaderOptions& setMaxNumberOfSymbols(uint8_t max);
34
    ReaderOptions& setReturnErrors(bool returnErrors);
35
    
36
    // Text processing
37
    ReaderOptions& setTextMode(TextMode mode);
38
    ReaderOptions& setCharacterSet(CharacterSet charset);
39
    ReaderOptions& setCharacterSet(std::string_view charset);
40
    
41
    // Format-specific options
42
    ReaderOptions& setTryCode39ExtendedMode(bool tryExtended);
43
    ReaderOptions& setEanAddOnSymbol(EanAddOnSymbol mode);
44
    
45
    // Experimental features
46
    ReaderOptions& setTryDenoise(bool tryDenoise);  // Requires ZXING_EXPERIMENTAL_API
47
};
48
```
49

50
## Configuration Categories
51

52
### Format Selection
53

54
Control which barcode formats to detect for improved performance:
55

56
```cpp
57
// Detect all formats (default)
58
auto options = ZXing::ReaderOptions().setFormats(ZXing::BarcodeFormat::Any);
59

60
// Detect only QR codes
61
auto qrOptions = ZXing::ReaderOptions()
62
    .setFormats(ZXing::BarcodeFormat::QRCode);
63

64
// Detect multiple specific formats
65
auto retailOptions = ZXing::ReaderOptions()
66
    .setFormats(ZXing::BarcodeFormat::EAN13 | 
67
                ZXing::BarcodeFormat::EAN8 | 
68
                ZXing::BarcodeFormat::UPCA | 
69
                ZXing::BarcodeFormat::UPCE);
70

71
// Detect all linear formats
72
auto linearOptions = ZXing::ReaderOptions()
73
    .setFormats(ZXing::BarcodeFormat::LinearCodes);
74

75
// Detect all 2D matrix formats
76
auto matrixOptions = ZXing::ReaderOptions()
77
    .setFormats(ZXing::BarcodeFormat::MatrixCodes);
78
```
79

80
### Performance vs Accuracy Trade-offs
81

82
Balance speed and detection accuracy based on your requirements:
83

84
```cpp
85
// Maximum accuracy (slower)
86
auto accurateOptions = ZXing::ReaderOptions()
87
    .setTryHarder(true)     // More intensive scanning algorithms
88
    .setTryRotate(true)     // Try 90°, 180°, 270° rotations
89
    .setTryInvert(true)     // Try inverted (negative) images
90
    .setTryDownscale(true); // Try different image scales
91

92
// Maximum speed (less accurate)
93
auto fastOptions = ZXing::ReaderOptions()
94
    .setTryHarder(false)
95
    .setTryRotate(false)
96
    .setTryInvert(false)
97
    .setTryDownscale(false)
98
    .setMaxNumberOfSymbols(1); // Stop after first detection
99

100
// Balanced approach
101
auto balancedOptions = ZXing::ReaderOptions()
102
    .setTryHarder(false)
103
    .setTryRotate(true)      // Rotation is often necessary
104
    .setTryInvert(false)
105
    .setTryDownscale(true);  // Helps with high-res images
106
```
107

108
### Binarization Methods
109

110
Choose the algorithm for converting grayscale images to binary:
111

112
```cpp { .api }
113
enum class Binarizer : unsigned char {
114
    LocalAverage,    // Adaptive local thresholding (default, best quality)
115
    GlobalHistogram, // Global histogram-based threshold
116
    FixedThreshold,  // Fixed threshold at 127
117
    BoolCast         // Fastest, treats non-zero as white
118
};
119
```
120

121
```cpp
122
// High quality (default)
123
auto qualityOptions = ZXing::ReaderOptions()
124
    .setBinarizer(ZXing::Binarizer::LocalAverage);
125

126
// Good for uniform lighting
127
auto globalOptions = ZXing::ReaderOptions()
128
    .setBinarizer(ZXing::Binarizer::GlobalHistogram);
129

130
// When you know the threshold
131
auto fixedOptions = ZXing::ReaderOptions()
132
    .setBinarizer(ZXing::Binarizer::FixedThreshold);
133

134
// Maximum speed for binary images
135
auto binaryOptions = ZXing::ReaderOptions()
136
    .setBinarizer(ZXing::Binarizer::BoolCast);
137
```
138

139
### Image Characteristics
140

141
Optimize for specific image properties:
142

143
```cpp
144
// For perfect, computer-generated barcodes
145
auto pureOptions = ZXing::ReaderOptions()
146
    .setIsPure(true)
147
    .setBinarizer(ZXing::Binarizer::BoolCast)
148
    .setTryHarder(false);
149

150
// For high-resolution images (starts downscaling at 500px)
151
auto highResOptions = ZXing::ReaderOptions()
152
    .setDownscaleThreshold(1000)  // Start downscaling at 1000px
153
    .setDownscaleFactor(2)        // Scale by factor of 2
154
    .setTryDownscale(true);
155

156
// For low-resolution images
157
auto lowResOptions = ZXing::ReaderOptions()
158
    .setTryDownscale(false)       // Don't downscale further
159
    .setTryHarder(true);          // Use more intensive algorithms
160
```
161

162
### Result Filtering
163

164
Control which results are returned:
165

166
```cpp
167
// Strict quality requirements
168
auto strictOptions = ZXing::ReaderOptions()
169
    .setMinLineCount(3)           // Require 3 confirming scan lines
170
    .setReturnErrors(false);      // Only return valid barcodes
171

172
// Include questionable results
173
auto permissiveOptions = ZXing::ReaderOptions()
174
    .setMinLineCount(1)           // Accept single scan line
175
    .setReturnErrors(true);       // Include barcodes with errors
176

177
// Multiple barcode scanning
178
auto multiOptions = ZXing::ReaderOptions()
179
    .setMaxNumberOfSymbols(10)    // Find up to 10 barcodes
180
    .setReturnErrors(true);       // Include partial results
181
```
182

183
### Text Processing
184

185
Configure how decoded text is processed and returned:
186

187
```cpp { .api }
188
enum class TextMode : unsigned char {
189
    Plain,   // Standard transcoding (default)
190
    ECI,     // ECI protocol compliant
191
    HRI,     // Human Readable Interpretation
192
    Hex,     // Hexadecimal representation
193
    Escaped  // Escape non-printable characters
194
};
195
```
196

197
```cpp
198
// Human-readable output
199
auto readableOptions = ZXing::ReaderOptions()
200
    .setTextMode(ZXing::TextMode::HRI);
201

202
// ECI-compliant text processing
203
auto eciOptions = ZXing::ReaderOptions()
204
    .setTextMode(ZXing::TextMode::ECI);
205

206
// Debug mode with hex output
207
auto debugOptions = ZXing::ReaderOptions()
208
    .setTextMode(ZXing::TextMode::Hex);
209

210
// Handle special characters
211
auto escapedOptions = ZXing::ReaderOptions()
212
    .setTextMode(ZXing::TextMode::Escaped);
213

214
// Fallback character set
215
auto charsetOptions = ZXing::ReaderOptions()
216
    .setCharacterSet(ZXing::CharacterSet::UTF8);
217
```
218

219
### Format-Specific Options
220

221
Special options for specific barcode formats:
222

223
```cpp
224
// Code 39 extended mode
225
auto code39Options = ZXing::ReaderOptions()
226
    .setFormats(ZXing::BarcodeFormat::Code39)
227
    .setTryCode39ExtendedMode(true);
228

229
// EAN add-on symbol handling
230
auto eanOptions = ZXing::ReaderOptions()
231
    .setFormats(ZXing::BarcodeFormat::EAN13 | ZXing::BarcodeFormat::EAN8)
232
    .setEanAddOnSymbol(ZXing::EanAddOnSymbol::Read); // or Ignore, Require
233
```
234

235
## Common Configuration Patterns
236

237
### Mobile Camera Scanning
238

239
```cpp
240
auto mobileOptions = ZXing::ReaderOptions()
241
    .setFormats(ZXing::BarcodeFormat::QRCode | 
242
                ZXing::BarcodeFormat::EAN13 |
243
                ZXing::BarcodeFormat::Code128)
244
    .setTryHarder(false)          // Optimize for speed
245
    .setTryRotate(true)           // Camera can be at any angle
246
    .setTryInvert(false)          // Cameras usually don't invert
247
    .setTryDownscale(true)        // High-res camera images
248
    .setDownscaleThreshold(800)
249
    .setBinarizer(ZXing::Binarizer::LocalAverage)
250
    .setMaxNumberOfSymbols(1);    // Usually scanning one at a time
251
```
252

253
### Document Scanning
254

255
```cpp
256
auto documentOptions = ZXing::ReaderOptions()
257
    .setFormats(ZXing::BarcodeFormat::QRCode | 
258
                ZXing::BarcodeFormat::DataMatrix |
259
                ZXing::BarcodeFormat::PDF417)
260
    .setTryHarder(true)           // Documents may have poor quality
261
    .setTryRotate(true)           // Document orientation varies
262
    .setTryInvert(true)           // Some documents use inverted codes
263
    .setBinarizer(ZXing::Binarizer::LocalAverage)
264
    .setTextMode(ZXing::TextMode::Plain)
265
    .setReturnErrors(false);      // Only accept clean reads
266
```
267

268
### Industrial/Production Scanning
269

270
```cpp
271
auto industrialOptions = ZXing::ReaderOptions()
272
    .setFormats(ZXing::BarcodeFormat::Code128 |
273
                ZXing::BarcodeFormat::DataMatrix)
274
    .setIsPure(true)              // Controlled printing environment
275
    .setTryHarder(false)          // Speed is critical
276
    .setTryRotate(false)          // Controlled positioning
277
    .setBinarizer(ZXing::Binarizer::GlobalHistogram)
278
    .setMinLineCount(2)           // Require confirmation
279
    .setMaxNumberOfSymbols(1);
280
```
281

282
### Retail Point-of-Sale
283

284
```cpp
285
auto retailOptions = ZXing::ReaderOptions()
286
    .setFormats(ZXing::BarcodeFormat::EAN13 |
287
                ZXing::BarcodeFormat::EAN8 |
288
                ZXing::BarcodeFormat::UPCA |
289
                ZXing::BarcodeFormat::UPCE)
290
    .setTryHarder(false)          // Speed for checkout
291
    .setTryRotate(true)           // Products at various angles
292
    .setTryInvert(false)
293
    .setEanAddOnSymbol(ZXing::EanAddOnSymbol::Read)
294
    .setBinarizer(ZXing::Binarizer::LocalAverage)
295
    .setMaxNumberOfSymbols(1);
296
```
297

298
### Batch Processing
299

300
```cpp
301
auto batchOptions = ZXing::ReaderOptions()
302
    .setFormats(ZXing::BarcodeFormat::Any)  // Unknown formats
303
    .setTryHarder(true)           // Quality over speed
304
    .setTryRotate(true)
305
    .setTryInvert(true)
306
    .setTryDownscale(true)
307
    .setMaxNumberOfSymbols(20)    // Multiple barcodes per image
308
    .setReturnErrors(true)        // Log all attempts
309
    .setTextMode(ZXing::TextMode::Escaped); // Handle special chars
310
```
311

312
## Dynamic Configuration
313

314
### Adaptive Configuration
315

316
```cpp
317
ZXing::ReaderOptions createAdaptiveOptions(int imageWidth, int imageHeight, 
318
                                          bool isMobile, bool requireSpeed) {
319
    auto options = ZXing::ReaderOptions();
320
    
321
    // Adjust for image size
322
    if (imageWidth * imageHeight > 2000000) {  // High resolution
323
        options.setTryDownscale(true)
324
               .setDownscaleThreshold(1000)
325
               .setDownscaleFactor(2);
326
    }
327
    
328
    // Adjust for platform
329
    if (isMobile) {
330
        options.setTryRotate(true)
331
               .setBinarizer(ZXing::Binarizer::LocalAverage);
332
    } else {
333
        options.setBinarizer(ZXing::Binarizer::GlobalHistogram);
334
    }
335
    
336
    // Adjust for performance requirements
337
    if (requireSpeed) {
338
        options.setTryHarder(false)
339
               .setMaxNumberOfSymbols(1);
340
    } else {
341
        options.setTryHarder(true)
342
               .setReturnErrors(true);
343
    }
344
    
345
    return options;
346
}
347
```
348

349
### Progressive Scanning
350

351
```cpp
352
std::vector<ZXing::Barcode> progressiveScan(const ZXing::ImageView& image) {
353
    // Try fast options first
354
    auto fastOptions = ZXing::ReaderOptions()
355
        .setTryHarder(false)
356
        .setTryRotate(false)
357
        .setMaxNumberOfSymbols(5);
358
    
359
    auto results = ZXing::ReadBarcodes(image, fastOptions);
360
    if (!results.empty()) {
361
        return results;
362
    }
363
    
364
    // Try medium options
365
    auto mediumOptions = ZXing::ReaderOptions()
366
        .setTryHarder(false)
367
        .setTryRotate(true)
368
        .setMaxNumberOfSymbols(5);
369
    
370
    results = ZXing::ReadBarcodes(image, mediumOptions);
371
    if (!results.empty()) {
372
        return results;
373
    }
374
    
375
    // Try intensive options
376
    auto intensiveOptions = ZXing::ReaderOptions()
377
        .setTryHarder(true)
378
        .setTryRotate(true)
379
        .setTryInvert(true)
380
        .setMaxNumberOfSymbols(10);
381
    
382
    return ZXing::ReadBarcodes(image, intensiveOptions);
383
}
384
```
385

386
## Performance Optimization
387

388
### Format-Specific Optimization
389

390
```cpp
391
// When you know the expected format
392
ZXing::Barcode scanSpecificFormat(const ZXing::ImageView& image, 
393
                                 ZXing::BarcodeFormat expectedFormat) {
394
    auto options = ZXing::ReaderOptions()
395
        .setFormats(expectedFormat)
396
        .setMaxNumberOfSymbols(1);
397
    
398
    // Format-specific optimizations
399
    switch (expectedFormat) {
400
        case ZXing::BarcodeFormat::QRCode:
401
            options.setTryRotate(true)     // QR codes can be rotated
402
                   .setTryInvert(false);   // Usually not inverted
403
            break;
404
            
405
        case ZXing::BarcodeFormat::Code128:
406
            options.setTryRotate(false)    // Linear codes have orientation
407
                   .setMinLineCount(2);    // Require confirmation
408
            break;
409
            
410
        case ZXing::BarcodeFormat::DataMatrix:
411
            options.setTryHarder(true)     // Small symbols need more effort
412
                   .setTryRotate(true);
413
            break;
414
    }
415
    
416
    return ZXing::ReadBarcode(image, options);
417
}
418
```
419

420
### Memory and Threading
421

422
```cpp
423
// Thread-local options for concurrent processing
424
thread_local ZXing::ReaderOptions tlsOptions;
425

426
void initializeThreadOptions() {
427
    tlsOptions = ZXing::ReaderOptions()
428
        .setFormats(ZXing::BarcodeFormat::Any)
429
        .setTryHarder(true);
430
}
431

432
ZXing::Barcode threadSafeScan(const ZXing::ImageView& image) {
433
    // Each thread uses its own options instance
434
    return ZXing::ReadBarcode(image, tlsOptions);
435
}
436
```