0
# ZXing Core Library
1
2
ZXing (Zebra Crossing) is a comprehensive open-source, multi-format 1D/2D barcode image processing library implemented in Java. The core module provides the fundamental barcode encoding and decoding functionality supporting a wide range of barcode formats including QR Code, Data Matrix, Aztec, PDF417, MaxiCode, and all major 1D formats like UPC/EAN and Code 128.
3
4
## Package Information
5
6
- **Package Name**: core
7
- **Package Type**: maven
8
- **Group ID**: com.google.zxing
9
- **Language**: Java
10
- **Installation**: `implementation 'com.google.zxing:core:3.5.3'` (Gradle) or `<dependency><groupId>com.google.zxing</groupId><artifactId>core</artifactId><version>3.5.3</version></dependency>` (Maven)
11
12
## Core Imports
13
14
```java
15
import com.google.zxing.*;
16
import com.google.zxing.common.*;
17
```
18
19
For specific formats:
20
```java
21
import com.google.zxing.qrcode.QRCodeReader;
22
import com.google.zxing.qrcode.QRCodeWriter;
23
import com.google.zxing.datamatrix.DataMatrixReader;
24
import com.google.zxing.pdf417.PDF417Reader;
25
```
26
27
## Basic Usage
28
29
### Decoding Barcodes
30
31
```java
32
import com.google.zxing.*;
33
import com.google.zxing.common.HybridBinarizer;
34
35
// Create a luminance source from your image data
36
LuminanceSource source = new RGBLuminanceSource(width, height, pixels);
37
38
// Convert to binary bitmap
39
BinaryBitmap bitmap = new BinaryBitmap(new HybridBinarizer(source));
40
41
// Decode the barcode
42
MultiFormatReader reader = new MultiFormatReader();
43
Result result = reader.decode(bitmap);
44
45
// Get the decoded text
46
String text = result.getText();
47
BarcodeFormat format = result.getBarcodeFormat();
48
```
49
50
### Encoding Barcodes
51
52
```java
53
import com.google.zxing.*;
54
import com.google.zxing.common.BitMatrix;
55
56
// Create a writer
57
MultiFormatWriter writer = new MultiFormatWriter();
58
59
// Encode content as QR code
60
BitMatrix bitMatrix = writer.encode(
61
"Hello World",
62
BarcodeFormat.QR_CODE,
63
300,
64
300
65
);
66
67
// Convert BitMatrix to image (implementation dependent)
68
```
69
70
## Architecture
71
72
ZXing Core is built around several key architectural components:
73
74
- **Reader/Writer Interfaces**: Primary abstractions for decoding and encoding operations
75
- **Multi-Format Support**: `MultiFormatReader` and `MultiFormatWriter` provide unified entry points that delegate to format-specific implementations
76
- **Image Processing Pipeline**: `LuminanceSource` → `Binarizer` → `BinaryBitmap` for image data processing
77
- **Result Framework**: Structured result objects with metadata and extensible parsing for different data types
78
- **Format-Specific Packages**: Dedicated implementations for each barcode format (QR Code, Data Matrix, etc.)
79
- **Common Utilities**: Shared data structures, error correction, and mathematical utilities
80
81
## Capabilities
82
83
### Core Reading Interface
84
85
Primary interface for barcode decoding operations with support for hints and multi-format detection.
86
87
```java { .api }
88
public interface Reader {
89
Result decode(BinaryBitmap image) throws NotFoundException, ChecksumException, FormatException;
90
Result decode(BinaryBitmap image, Map<DecodeHintType,?> hints) throws NotFoundException, ChecksumException, FormatException;
91
void reset();
92
}
93
94
public final class MultiFormatReader implements Reader {
95
public Result decodeWithState(BinaryBitmap image) throws NotFoundException;
96
public void setHints(Map<DecodeHintType,?> hints);
97
}
98
```
99
100
[Reading and Decoding](./reading-decoding.md)
101
102
### Core Writing Interface
103
104
Primary interface for barcode encoding operations with format-specific delegation and configuration options.
105
106
```java { .api }
107
public interface Writer {
108
BitMatrix encode(String contents, BarcodeFormat format, int width, int height) throws WriterException;
109
BitMatrix encode(String contents, BarcodeFormat format, int width, int height, Map<EncodeHintType,?> hints) throws WriterException;
110
}
111
112
public final class MultiFormatWriter implements Writer {
113
// Supports: QR_CODE, DATA_MATRIX, AZTEC, PDF_417, CODE_128, CODE_39, CODE_93,
114
// EAN_8, EAN_13, UPC_A, UPC_E, ITF, CODABAR
115
}
116
```
117
118
[Writing and Encoding](./writing-encoding.md)
119
120
### Image Processing
121
122
Comprehensive image processing pipeline for converting various image formats to binary representations suitable for barcode detection.
123
124
```java { .api }
125
public abstract class LuminanceSource {
126
public abstract byte[] getRow(int y, byte[] row);
127
public abstract byte[] getMatrix();
128
public abstract int getWidth();
129
public abstract int getHeight();
130
public LuminanceSource crop(int left, int top, int width, int height);
131
public LuminanceSource rotateCounterClockwise();
132
}
133
134
public final class BinaryBitmap {
135
public BinaryBitmap(Binarizer binarizer);
136
public int getWidth();
137
public int getHeight();
138
public BitArray getBlackRow(int y, BitArray row) throws NotFoundException;
139
public BitMatrix getBlackMatrix() throws NotFoundException;
140
public boolean isCropSupported();
141
public BinaryBitmap crop(int left, int top, int width, int height);
142
public boolean isRotateSupported();
143
public BinaryBitmap rotateCounterClockwise();
144
public BinaryBitmap rotateCounterClockwise45();
145
}
146
```
147
148
[Image Processing](./image-processing.md)
149
150
### Result Processing
151
152
Structured result handling with metadata extraction and parsing capabilities for different barcode content types.
153
154
```java { .api }
155
public final class Result {
156
public Result(String text, byte[] rawBytes, ResultPoint[] resultPoints, BarcodeFormat format);
157
public Result(String text, byte[] rawBytes, ResultPoint[] resultPoints, BarcodeFormat format, long timestamp);
158
public Result(String text, byte[] rawBytes, int numBits, ResultPoint[] resultPoints, BarcodeFormat format, long timestamp);
159
public String getText();
160
public byte[] getRawBytes();
161
public int getNumBits();
162
public ResultPoint[] getResultPoints();
163
public BarcodeFormat getBarcodeFormat();
164
public Map<ResultMetadataType,Object> getResultMetadata();
165
public long getTimestamp();
166
public void putMetadata(ResultMetadataType type, Object value);
167
public void putAllMetadata(Map<ResultMetadataType,Object> metadata);
168
public void addResultPoints(ResultPoint[] newPoints);
169
}
170
171
public abstract class ParsedResult {
172
public abstract ParsedResultType getType();
173
public abstract String getDisplayResult();
174
}
175
```
176
177
[Result Processing](./result-processing.md)
178
179
### Data Structures
180
181
Core data structures for bit manipulation, matrix operations, and geometric transformations used throughout the library.
182
183
```java { .api }
184
public final class BitMatrix {
185
public BitMatrix(int width, int height);
186
public boolean get(int x, int y);
187
public void set(int x, int y);
188
public BitArray getRow(int y, BitArray row);
189
}
190
191
public final class BitArray {
192
public BitArray();
193
public BitArray(int size);
194
public boolean get(int i);
195
public void set(int i);
196
public int getNextSet(int from);
197
}
198
```
199
200
[Data Structures](./data-structures.md)
201
202
### QR Code Support
203
204
Complete QR Code implementation with encoding, decoding, error correction, and version management.
205
206
```java { .api }
207
public final class QRCodeReader implements Reader {
208
// QR Code specific decoding
209
}
210
211
public final class QRCodeWriter implements Writer {
212
// QR Code specific encoding
213
}
214
```
215
216
[QR Code Support](./qrcode-support.md)
217
218
### Additional Format Support
219
220
ZXing Core provides comprehensive support for additional barcode formats beyond QR codes:
221
222
- **Data Matrix**: 2D barcodes with configurable symbol sizes and advanced encoding modes
223
- **1D Barcodes**: Complete support for UPC/EAN family, Code family (39, 93, 128), ITF, Codabar, and RSS formats
224
- **Other 2D Formats**: Aztec, PDF417, and MaxiCode with format-specific readers and writers
225
- **Error Correction**: Reed-Solomon implementation for robust data recovery across all 2D formats
226
227
All formats are accessible through the `MultiFormatReader` and `MultiFormatWriter` classes, with format-specific classes available in their respective packages (e.g., `com.google.zxing.datamatrix`, `com.google.zxing.oned`) for advanced configuration.
228
229
## Core Types
230
231
```java { .api }
232
public enum BarcodeFormat {
233
// 1D formats
234
CODABAR, CODE_39, CODE_93, CODE_128, EAN_8, EAN_13, ITF, UPC_A, UPC_E,
235
UPC_EAN_EXTENSION, RSS_14, RSS_EXPANDED,
236
// 2D formats
237
AZTEC, DATA_MATRIX, MAXICODE, PDF_417, QR_CODE
238
}
239
240
public enum DecodeHintType {
241
OTHER, PURE_BARCODE, POSSIBLE_FORMATS, TRY_HARDER, CHARACTER_SET, ALLOWED_LENGTHS,
242
ASSUME_CODE_39_CHECK_DIGIT, ASSUME_GS1, RETURN_CODABAR_START_END,
243
NEED_RESULT_POINT_CALLBACK, ALLOWED_EAN_EXTENSIONS, ALSO_INVERTED
244
}
245
246
public enum EncodeHintType {
247
ERROR_CORRECTION, CHARACTER_SET, DATA_MATRIX_SHAPE, MARGIN,
248
PDF417_COMPACT, AZTEC_LAYERS, QR_VERSION, QR_MASK_PATTERN, GS1_FORMAT
249
}
250
251
public enum ResultMetadataType {
252
ORIENTATION, BYTE_SEGMENTS, ERROR_CORRECTION_LEVEL, ERRORS_CORRECTED,
253
ISSUE_NUMBER, SUGGESTED_PRICE, POSSIBLE_COUNTRY, UPC_EAN_EXTENSION,
254
PDF417_EXTRA_METADATA, STRUCTURED_APPEND_SEQUENCE, SYMBOLOGY_IDENTIFIER
255
}
256
257
public enum ParsedResultType {
258
ADDRESSBOOK, EMAIL_ADDRESS, PRODUCT, URI, TEXT, GEO, TEL, SMS,
259
CALENDAR, WIFI, ISBN, VIN
260
}
261
262
// Exception hierarchy
263
public abstract class ReaderException extends Exception;
264
public final class ChecksumException extends ReaderException;
265
public final class FormatException extends ReaderException;
266
public final class NotFoundException extends ReaderException;
267
public final class WriterException extends Exception;
268
```