0
# Reading Barcodes
1

2
ZXing-C++ provides powerful barcode reading capabilities through a simple, high-level API that supports all major barcode formats with extensive configuration options.
3

4
## Core Reading Functions
5

6
### Single Barcode Reading
7

8
Read the first barcode found in an image.
9

10
```cpp { .api }
11
Result ReadBarcode(const ImageView& buffer, const DecodeHints& hints = {});
12
```
13

14
**Parameters:**
15
- `buffer`: ImageView containing the image data with format information
16
- `hints`: Optional DecodeHints for configuration (defaults to try all formats)
17

18
**Returns:** Result object containing the decoded barcode or error information
19

20
### Multiple Barcode Reading
21

22
Read all barcodes found in an image.
23

24
```cpp { .api }
25
Results ReadBarcodes(const ImageView& buffer, const DecodeHints& hints = {});
26
```
27

28
**Parameters:**
29
- `buffer`: ImageView containing the image data with format information  
30
- `hints`: Optional DecodeHints for configuration (defaults to try all formats)
31

32
**Returns:** Vector of Result objects, may be empty if no barcodes found
33

34
## Usage Examples
35

36
### Basic Reading
37

38
```cpp
39
#define ZX_USE_UTF8 1
40
#include "ReadBarcode.h"
41
#include "ImageView.h"
42

43
using namespace ZXing;
44

45
// Load your image data (using your preferred image library)
46
const uint8_t* imageData = loadImageData("barcode.png");
47
int width = getImageWidth();
48
int height = getImageHeight();
49

50
// Create ImageView for grayscale image
51
ImageView imageView(imageData, width, height, ImageFormat::Lum);
52

53
// Read barcode
54
Result result = ReadBarcode(imageView);
55

56
if (result.isValid()) {
57
    std::cout << "Format: " << ToString(result.format()) << std::endl;
58
    std::cout << "Text: " << result.text() << std::endl;
59
    
60
    // Get position information
61
    Position pos = result.position();
62
    std::cout << "Found at: (" << pos.topLeft().x << "," << pos.topLeft().y << ")" << std::endl;
63
} else {
64
    std::cout << "No barcode found or error: " << result.error().msg() << std::endl;
65
}
66
```
67

68
### Reading with Configuration
69

70
```cpp
71
#include "ReadBarcode.h"
72
#include "DecodeHints.h"
73

74
using namespace ZXing;
75

76
// Configure reading hints for better performance
77
DecodeHints hints;
78
hints.setFormats(BarcodeFormat::QRCode | BarcodeFormat::Code128)  // Only look for these formats
79
     .setTryHarder(true)                                          // More thorough search
80
     .setTryRotate(false)                                         // Don't try rotated images (faster)
81
     .setBinarizer(Binarizer::GlobalHistogram);                   // Use specific binarization
82

83
ImageView imageView(imageData, width, height, ImageFormat::RGB);
84
Result result = ReadBarcode(imageView, hints);
85
```
86

87
### Reading Multiple Barcodes
88

89
```cpp
90
#include "ReadBarcode.h"
91

92
using namespace ZXing;
93

94
// Read all barcodes in the image
95
Results results = ReadBarcodes(imageView);
96

97
std::cout << "Found " << results.size() << " barcodes:" << std::endl;
98

99
for (const auto& result : results) {
100
    if (result.isValid()) {
101
        std::cout << "- " << ToString(result.format()) << ": " << result.text() << std::endl;
102
    } else {
103
        std::cout << "- Error: " << result.error().msg() << std::endl;
104
    }
105
}
106
```
107

108
### Handling Different Image Formats
109

110
```cpp
111
// RGB image (3 bytes per pixel)
112
ImageView rgbView(rgbData, width, height, ImageFormat::RGB);
113

114
// BGR image (3 bytes per pixel, blue-green-red order)
115
ImageView bgrView(bgrData, width, height, ImageFormat::BGR);
116

117
// RGBA image (4 bytes per pixel)
118
ImageView rgbaView(rgbaData, width, height, ImageFormat::RGBX);
119

120
// Grayscale image (1 byte per pixel) - fastest
121
ImageView grayView(grayData, width, height, ImageFormat::Lum);
122

123
// All formats work with the same API
124
Result result = ReadBarcode(grayView);
125
```
126

127
### Error Handling
128

129
```cpp
130
Result result = ReadBarcode(imageView);
131

132
if (!result.isValid()) {
133
    const Error& error = result.error();
134
    
135
    switch (error.type()) {
136
        case Error::Type::Format:
137
            std::cout << "Format error: " << error.msg() << std::endl;
138
            break;
139
        case Error::Type::Checksum:
140
            std::cout << "Checksum error: " << error.msg() << std::endl;
141
            break;
142
        case Error::Type::Unsupported:
143
            std::cout << "Unsupported feature: " << error.msg() << std::endl;
144
            break;
145
        case Error::Type::None:
146
            std::cout << "No barcode found" << std::endl;
147
            break;
148
    }
149
}
150
```
151

152
### Advanced Configuration
153

154
```cpp
155
DecodeHints hints;
156

157
// Performance optimizations
158
hints.setTryHarder(false)          // Faster, less thorough
159
     .setTryRotate(false)          // Don't try rotated images
160
     .setTryDownscale(false)       // Don't try downscaled images
161
     .setIsPure(true);             // Image contains only a perfect barcode
162

163
// Format-specific settings
164
hints.setFormats(BarcodeFormat::QRCode)
165
     .setReturnErrors(true)        // Return results even with errors
166
     .setMaxNumberOfSymbols(5);    // Limit number of barcodes to find
167

168
// Linear barcode settings
169
hints.setMinLineCount(3)           // Require 3 scan lines for linear codes
170
     .setTryCode39ExtendedMode(true)
171
     .setValidateCode39CheckSum(true)
172
     .setReturnCodabarStartEnd(true);
173

174
// EAN/UPC add-on handling
175
hints.setEanAddOnSymbol(EanAddOnSymbol::Read);  // Read EAN-2/5 add-ons
176

177
Result result = ReadBarcode(imageView, hints);
178
```
179

180
## Supported Formats for Reading
181

182
All formats support reading:
183

184
### Linear Barcodes
185
- **UPC-A / UPC-E**: Universal Product Codes
186
- **EAN-8 / EAN-13**: European Article Numbers
187
- **Code 39**: Alphanumeric format with start/stop characters
188
- **Code 93**: Compressed version of Code 39
189
- **Code 128**: High-density alphanumeric format
190
- **Codabar**: Numeric format used in libraries and blood banks
191
- **ITF**: Interleaved Two of Five for numeric data
192
- **DataBar / DataBar Expanded**: GS1 standard formats
193

194
### Matrix Barcodes
195
- **QR Code**: Square format with high error correction
196
- **Micro QR Code**: Smaller version of QR Code
197
- **DataMatrix**: Square or rectangular ECC200 format
198
- **Aztec**: Compact square format with centering pattern
199
- **PDF417**: Stacked linear format with high data capacity
200
- **MaxiCode**: Fixed-size format used by UPS (partial support)
201

202
## Performance Tips
203

204
1. **Use grayscale images** (ImageFormat::Lum) for best performance
205
2. **Limit formats** in DecodeHints to only what you need
206
3. **Disable rotation/downscaling** if images are already properly oriented and sized
207
4. **Use isPure=true** for generated/printed barcodes
208
5. **Set appropriate binarizer** based on image characteristics:
209
   - `LocalAverage`: Good for varied lighting conditions
210
   - `GlobalHistogram`: Good for consistent lighting
211
   - `FixedThreshold`: Fastest for high-contrast images
212
   - `BoolCast`: Fastest for already binarized images