0
# Reading and Decoding
1

2
Core barcode reading and decoding functionality providing the primary interface for extracting data from barcode images across all supported formats.
3

4
## Capabilities
5

6
### Reader Interface
7

8
Primary interface that all barcode readers implement for decoding operations.
9

10
```java { .api }
11
/**
12
 * Main interface for barcode decoding implementations
13
 */
14
public interface Reader {
15
    /**
16
     * Decode a barcode from an image without hints
17
     * @param image Binary bitmap containing the barcode
18
     * @return Result containing decoded text and metadata
19
     * @throws NotFoundException if no barcode is found
20
     * @throws ChecksumException if checksum validation fails
21
     * @throws FormatException if barcode format is invalid
22
     */
23
    Result decode(BinaryBitmap image) throws NotFoundException, ChecksumException, FormatException;
24
    
25
    /**
26
     * Decode a barcode from an image with configuration hints
27
     * @param image Binary bitmap containing the barcode
28
     * @param hints Map of decoding hints for configuration
29
     * @return Result containing decoded text and metadata
30
     * @throws NotFoundException if no barcode is found
31
     * @throws ChecksumException if checksum validation fails
32
     * @throws FormatException if barcode format is invalid
33
     */
34
    Result decode(BinaryBitmap image, Map<DecodeHintType,?> hints) throws NotFoundException, ChecksumException, FormatException;
35
    
36
    /**
37
     * Reset any internal state for reuse
38
     */
39
    void reset();
40
}
41
```
42

43
### MultiFormatReader
44

45
Main entry point for decoding that attempts to detect and decode multiple barcode formats automatically.
46

47
```java { .api }
48
/**
49
 * Convenience class and main entry point for most decoding use cases
50
 * Attempts to decode all supported barcode formats by default
51
 */
52
public final class MultiFormatReader implements Reader {
53
    /**
54
     * Standard constructor
55
     */
56
    public MultiFormatReader();
57
    
58
    /**
59
     * Decode with state optimization for continuous scanning
60
     * Use after calling setHints() for better performance
61
     * @param image Binary bitmap to decode
62
     * @return Decoded result
63
     * @throws NotFoundException if no barcode found
64
     */
65
    public Result decodeWithState(BinaryBitmap image) throws NotFoundException;
66
    
67
    /**
68
     * Configure decoding behavior and reader selection
69
     * Call once, then use decodeWithState() for optimal performance
70
     * @param hints Configuration hints for decoding behavior
71
     */
72
    public void setHints(Map<DecodeHintType,?> hints);
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
import com.google.zxing.*;
80
import com.google.zxing.common.HybridBinarizer;
81
import java.util.Map;
82
import java.util.HashMap;
83
import java.util.EnumSet;
84

85
// Basic decoding - attempts all formats
86
MultiFormatReader reader = new MultiFormatReader();
87
Result result = reader.decode(binaryBitmap);
88
String decodedText = result.getText();
89

90
// Optimized for continuous scanning
91
reader.setHints(hints);
92
for (BinaryBitmap bitmap : imagesToDecode) {
93
    try {
94
        Result result = reader.decodeWithState(bitmap);
95
        System.out.println("Decoded: " + result.getText());
96
    } catch (NotFoundException e) {
97
        // No barcode found in this image
98
    }
99
}
100

101
// Configure for specific formats only
102
Map<DecodeHintType, Object> hints = new HashMap<>();
103
hints.put(DecodeHintType.POSSIBLE_FORMATS, 
104
    EnumSet.of(BarcodeFormat.QR_CODE, BarcodeFormat.DATA_MATRIX));
105
hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE);
106

107
reader.setHints(hints);
108
Result result = reader.decodeWithState(bitmap);
109
```
110

111
### Format-Specific Readers
112

113
Individual readers for specific barcode formats when you know the expected format.
114

115
```java { .api }
116
// QR Code
117
public final class QRCodeReader implements Reader {
118
    public QRCodeReader();
119
}
120

121
// Data Matrix  
122
public final class DataMatrixReader implements Reader {
123
    public DataMatrixReader();
124
}
125

126
// Aztec
127
public final class AztecReader implements Reader {
128
    public AztecReader();
129
}
130

131
// PDF417
132
public final class PDF417Reader implements Reader {
133
    public PDF417Reader();
134
}
135

136
// MaxiCode
137
public final class MaxiCodeReader implements Reader {
138
    public MaxiCodeReader();
139
}
140

141
// 1D formats
142
public final class MultiFormatOneDReader extends OneDReader {
143
    public MultiFormatOneDReader(Map<DecodeHintType,?> hints);
144
}
145
```
146

147
### Decoding Hints
148

149
Configuration options to control decoding behavior and performance.
150

151
```java { .api }
152
public enum DecodeHintType {
153
    /**
154
     * Collection of BarcodeFormat to restrict decoding to specific formats
155
     * Value: Collection<BarcodeFormat>
156
     */
157
    POSSIBLE_FORMATS,
158
    
159
    /**
160
     * Enable more thorough detection at cost of performance
161
     * Value: Boolean
162
     */
163
    TRY_HARDER,
164
    
165
    /**
166
     * Character encoding for decoded text
167
     * Value: String (charset name)
168
     */
169
    CHARACTER_SET,
170
    
171
    /**
172
     * Allowed lengths for variable-length formats
173
     * Value: int[]
174
     */
175
    ALLOWED_LENGTHS,
176
    
177
    /**
178
     * Assume Code 39 barcodes have check digits
179
     * Value: Boolean
180
     */
181
    ASSUME_CODE_39_CHECK_DIGIT,
182
    
183
    /**
184
     * Assume GS1 encoding (affects FNC1 handling)
185
     * Value: Boolean
186
     */
187
    ASSUME_GS1,
188
    
189
    /**
190
     * Return start/end characters for Codabar
191
     * Value: Boolean
192
     */
193
    RETURN_CODABAR_START_END,
194
    
195
    /**
196
     * Callback for intermediate result points during detection
197
     * Value: ResultPointCallback
198
     */
199
    NEED_RESULT_POINT_CALLBACK,
200
    
201
    /**
202
     * Allowed UPC/EAN extension lengths
203
     * Value: int[]
204
     */
205
    ALLOWED_EAN_EXTENSIONS,
206
    
207
    /**
208
     * Also try decoding inverted (negative) images
209
     * Value: Boolean
210
     */
211
    ALSO_INVERTED,
212
    
213
    /**
214
     * Image contains only the barcode, no surrounding content
215
     * Value: Boolean
216
     */
217
    PURE_BARCODE
218
}
219
```
220

221
**Hint Usage Examples:**
222

223
```java
224
Map<DecodeHintType, Object> hints = new HashMap<>();
225

226
// Restrict to QR codes only
227
hints.put(DecodeHintType.POSSIBLE_FORMATS, EnumSet.of(BarcodeFormat.QR_CODE));
228

229
// Enable more thorough detection
230
hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE);
231

232
// Specify character encoding
233
hints.put(DecodeHintType.CHARACTER_SET, "UTF-8");
234

235
// Handle pure barcode images (no border/background)
236
hints.put(DecodeHintType.PURE_BARCODE, Boolean.TRUE);
237

238
// Try both normal and inverted images
239
hints.put(DecodeHintType.ALSO_INVERTED, Boolean.TRUE);
240

241
MultiFormatReader reader = new MultiFormatReader();
242
Result result = reader.decode(bitmap, hints);
243
```
244

245
### Exception Handling
246

247
Specific exceptions thrown during decoding operations.
248

249
```java { .api }
250
/**
251
 * Base class for all reader exceptions
252
 */
253
public abstract class ReaderException extends Exception {
254
    public static ReaderException getInstance();
255
}
256

257
/**
258
 * Thrown when no barcode is found in the image
259
 */
260
public final class NotFoundException extends ReaderException {
261
    public static NotFoundException getNotFoundInstance();
262
}
263

264
/**
265
 * Thrown when barcode is found but checksum validation fails
266
 */
267
public final class ChecksumException extends ReaderException {
268
    public static ChecksumException getChecksumInstance();
269
}
270

271
/**
272
 * Thrown when barcode format is invalid or corrupted
273
 */
274
public final class FormatException extends ReaderException {
275
    public static FormatException getFormatInstance();
276
}
277
```
278

279
**Exception Handling Examples:**
280

281
```java
282
try {
283
    Result result = reader.decode(bitmap);
284
    System.out.println("Decoded: " + result.getText());
285
} catch (NotFoundException e) {
286
    System.out.println("No barcode found in image");
287
} catch (ChecksumException e) {
288
    System.out.println("Barcode found but checksum failed");
289
} catch (FormatException e) {
290
    System.out.println("Barcode format is invalid");
291
} catch (ReaderException e) {
292
    System.out.println("General reading error: " + e.getMessage());
293
}
294
```
295

296
### Result Point Callback
297

298
Interface for receiving intermediate detection points during barcode scanning.
299

300
```java { .api }
301
/**
302
 * Callback interface for result point notifications during detection
303
 */
304
public interface ResultPointCallback {
305
    /**
306
     * Called when a potential result point is found
307
     * @param point Potential result point coordinates
308
     */
309
    void foundPossibleResultPoint(ResultPoint point);
310
}
311
```
312

313
**Callback Usage Example:**
314

315
```java
316
ResultPointCallback callback = new ResultPointCallback() {
317
    @Override
318
    public void foundPossibleResultPoint(ResultPoint point) {
319
        System.out.println("Found point at: " + point.getX() + ", " + point.getY());
320
    }
321
};
322

323
Map<DecodeHintType, Object> hints = new HashMap<>();
324
hints.put(DecodeHintType.NEED_RESULT_POINT_CALLBACK, callback);
325

326
MultiFormatReader reader = new MultiFormatReader();
327
Result result = reader.decode(bitmap, hints);
328
```
329

330
## Performance Considerations
331

332
### Continuous Scanning Optimization
333

334
For applications that decode multiple images in succession:
335

336
1. Create one `MultiFormatReader` instance
337
2. Call `setHints()` once with your configuration
338
3. Use `decodeWithState()` for subsequent images
339
4. Call `reset()` only when switching contexts
340

341
### Format Restriction
342

343
Restrict `POSSIBLE_FORMATS` to only the formats you expect to improve performance:
344

345
```java
346
// Only QR codes and Data Matrix
347
hints.put(DecodeHintType.POSSIBLE_FORMATS, 
348
    EnumSet.of(BarcodeFormat.QR_CODE, BarcodeFormat.DATA_MATRIX));
349
```
350

351
### TRY_HARDER Mode
352

353
Enable `TRY_HARDER` only when necessary as it significantly impacts performance but improves detection accuracy for difficult images.