0
# ZXing-C++
1
2
ZXing-C++ ("zebra crossing") is an open-source, multi-format linear/matrix barcode image processing library implemented in C++. Originally ported from the Java ZXing Library, it has evolved to include many improvements in terms of quality and performance. The library provides comprehensive barcode reading and writing capabilities for 17 different barcode formats.
3
4
## Package Information
5
6
- **Package Name**: zxing-cpp
7
- **Package Type**: C++ Library (CMake)
8
- **Language**: C++17
9
- **License**: Apache-2.0
10
- **Repository**: https://github.com/zxing-cpp/zxing-cpp
11
- **Installation**: CMake integration (see repository README for build instructions)
12
13
## Core Includes
14
15
For reading barcodes:
16
17
```cpp
18
#include "ReadBarcode.h"
19
#include "ImageView.h"
20
#include "DecodeHints.h"
21
```
22
23
For writing barcodes:
24
25
```cpp
26
#include "MultiFormatWriter.h"
27
#include "BitMatrix.h"
28
#include "BarcodeFormat.h"
29
```
30
31
Essential data types:
32
33
```cpp
34
#include "Result.h"
35
#include "Error.h"
36
```
37
38
## Basic Usage
39
40
### Reading Barcodes
41
42
```cpp
43
#define ZX_USE_UTF8 1 // Enable UTF-8 text support
44
#include "ReadBarcode.h"
45
#include "ImageView.h"
46
47
using namespace ZXing;
48
49
// Read single barcode from image data
50
const uint8_t* imageData = /* your image data */;
51
int width = /* image width */;
52
int height = /* image height */;
53
54
ImageView imageView(imageData, width, height, ImageFormat::Lum);
55
Result result = ReadBarcode(imageView);
56
57
if (result.isValid()) {
58
std::string text = result.text();
59
BarcodeFormat format = result.format();
60
std::cout << "Found " << ToString(format) << ": " << text << std::endl;
61
} else {
62
std::cout << "Error: " << result.error().msg() << std::endl;
63
}
64
65
// Read multiple barcodes
66
Results results = ReadBarcodes(imageView);
67
for (const auto& result : results) {
68
if (result.isValid()) {
69
std::cout << "Found: " << result.text() << std::endl;
70
}
71
}
72
```
73
74
### Writing Barcodes
75
76
```cpp
77
#include "MultiFormatWriter.h"
78
#include "BitMatrix.h"
79
80
using namespace ZXing;
81
82
// Create a QR Code
83
MultiFormatWriter writer(BarcodeFormat::QRCode);
84
writer.setMargin(10).setEccLevel(2);
85
86
BitMatrix matrix = writer.encode("Hello World", 200, 200);
87
88
// Convert BitMatrix to your image format
89
// matrix.get(x, y) returns true for black pixels, false for white
90
for (int y = 0; y < matrix.height(); ++y) {
91
for (int x = 0; x < matrix.width(); ++x) {
92
bool isBlack = matrix.get(x, y);
93
// Set pixel in your image format
94
}
95
}
96
```
97
98
## Architecture
99
100
ZXing-C++ is designed around several key components:
101
102
- **Entry Point Functions**: `ReadBarcode()` and `ReadBarcodes()` provide simple, high-level APIs
103
- **Image Handling**: `ImageView` class provides format-agnostic image data access
104
- **Configuration System**: `DecodeHints` class allows fine-tuning of detection behavior
105
- **Result System**: `Result` class encapsulates detection results with comprehensive metadata
106
- **Format Writers**: `MultiFormatWriter` provides unified encoding interface
107
- **Error Handling**: Comprehensive error reporting through `Error` class
108
- **Thread Safety**: All readers and writers are stateless and thread-safe
109
110
## Supported Formats
111
112
### Linear (1D) Barcodes
113
- UPC-A, UPC-E
114
- EAN-8, EAN-13
115
- Code 39, Code 93, Code 128
116
- Codabar
117
- ITF (Interleaved Two of Five)
118
- DataBar (RSS), DataBar Expanded
119
120
### Matrix (2D) Barcodes
121
- QR Code, Micro QR Code
122
- DataMatrix
123
- Aztec
124
- PDF417
125
- MaxiCode (partial support)
126
127
Note: DataBar formats support reading only, not writing.
128
129
## Capabilities
130
131
### Barcode Reading
132
133
High-performance barcode detection and decoding with configurable optimization hints and support for multiple formats simultaneously.
134
135
```cpp { .api }
136
Result ReadBarcode(const ImageView& buffer, const DecodeHints& hints = {});
137
Results ReadBarcodes(const ImageView& buffer, const DecodeHints& hints = {});
138
```
139
140
[Reading Barcodes](./reading.md)
141
142
### Barcode Writing
143
144
Multi-format barcode generation with customizable encoding parameters and output as binary matrix representation.
145
146
```cpp { .api }
147
class MultiFormatWriter {
148
public:
149
explicit MultiFormatWriter(BarcodeFormat format);
150
MultiFormatWriter& setEncoding(CharacterSet encoding);
151
MultiFormatWriter& setEccLevel(int level);
152
MultiFormatWriter& setMargin(int margin);
153
BitMatrix encode(const std::wstring& contents, int width, int height) const;
154
BitMatrix encode(const std::string& contents, int width, int height) const;
155
};
156
```
157
158
[Writing Barcodes](./writing.md)
159
160
### Image Processing
161
162
Flexible image data handling supporting multiple pixel formats with built-in transformations and optimization features.
163
164
```cpp { .api }
165
class ImageView {
166
public:
167
ImageView(const uint8_t* data, int width, int height, ImageFormat format,
168
int rowStride = 0, int pixStride = 0);
169
170
int width() const;
171
int height() const;
172
ImageFormat format() const;
173
174
ImageView cropped(int left, int top, int width, int height) const;
175
ImageView rotated(int degree) const;
176
ImageView subsampled(int scale) const;
177
};
178
```
179
180
[Image Processing](./image-processing.md)
181
182
### Configuration and Hints
183
184
Comprehensive configuration system for optimizing detection performance and accuracy based on specific use cases.
185
186
```cpp { .api }
187
class DecodeHints {
188
public:
189
DecodeHints& setFormats(BarcodeFormats formats);
190
DecodeHints& setTryHarder(bool tryHarder);
191
DecodeHints& setTryRotate(bool tryRotate);
192
DecodeHints& setBinarizer(Binarizer binarizer);
193
DecodeHints& setIsPure(bool isPure);
194
// ... additional configuration methods
195
};
196
```
197
198
[Configuration](./configuration.md)
199
200
### Result Processing
201
202
Rich result metadata including position information, error details, structured append support, and content type detection.
203
204
```cpp { .api }
205
class Result {
206
public:
207
bool isValid() const;
208
const Error& error() const;
209
BarcodeFormat format() const;
210
std::string text() const;
211
const ByteArray& bytes() const;
212
const Position& position() const;
213
ContentType contentType() const;
214
bool hasECI() const;
215
// ... additional result methods
216
};
217
```
218
219
[Result Processing](./results.md)
220
221
## Types
222
223
### Core Enums and Constants
224
225
```cpp { .api }
226
enum class BarcodeFormat {
227
None, Aztec, Codabar, Code39, Code93, Code128,
228
DataBar, DataBarExpanded, DataMatrix, EAN8, EAN13,
229
ITF, MaxiCode, PDF417, QRCode, UPCA, UPCE, MicroQRCode
230
};
231
232
enum class ImageFormat : uint32_t {
233
None, Lum, RGB, BGR, RGBX, XRGB, BGRX, XBGR
234
};
235
236
enum class Binarizer : unsigned char {
237
LocalAverage, GlobalHistogram, FixedThreshold, BoolCast
238
};
239
240
enum class ContentType {
241
Text, Binary, Mixed, GS1, ISO15434, UnknownECI
242
};
243
```
244
245
### Utility Types
246
247
```cpp { .api }
248
class Error {
249
public:
250
enum class Type { None, Format, Checksum, Unsupported };
251
Type type() const noexcept;
252
const std::string& msg() const noexcept;
253
explicit operator bool() const noexcept;
254
};
255
256
using Results = std::vector<Result>;
257
using Position = QuadrilateralI;
258
using BarcodeFormats = Flags<BarcodeFormat>;
259
using ByteArray = std::vector<uint8_t>;
260
```
261
262
### Utility Functions
263
264
```cpp { .api }
265
const char* ToString(BarcodeFormat format);
266
std::string ToString(BarcodeFormats formats);
267
std::string ToString(ContentType type);
268
269
BarcodeFormat BarcodeFormatFromString(const std::string& str);
270
BarcodeFormats BarcodeFormatsFromString(const std::string& str);
271
```