0
# QR Code Generator
1

2
A high-quality Java library for generating QR Codes from text strings and byte arrays. This library provides absolute correctness, flexible options, and comprehensive support for all QR Code Model 2 specifications with optimal encoding algorithms.
3

4
## Package Information
5

6
- **Package Name**: io.nayuki:qrcodegen
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to `pom.xml`:
10
  ```xml
11
  <dependency>
12
    <groupId>io.nayuki</groupId>
13
    <artifactId>qrcodegen</artifactId>
14
    <version>1.8.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import io.nayuki.qrcodegen.QrCode;
22
import io.nayuki.qrcodegen.QrSegment;
23
```
24

25
For advanced features:
26
```java
27
import io.nayuki.qrcodegen.QrSegmentAdvanced;
28
import io.nayuki.qrcodegen.DataTooLongException;
29
```
30

31
## Basic Usage
32

33
### Simple Text Encoding
34

35
```java
36
import io.nayuki.qrcodegen.QrCode;
37

38
// Create QR Code from text
39
QrCode qr = QrCode.encodeText("Hello, World!", QrCode.Ecc.MEDIUM);
40

41
// Access the QR code properties
42
int size = qr.size;              // Size in modules (21-177)
43
int version = qr.version;        // Version number (1-40)
44

45
// Read individual modules
46
for (int y = 0; y < qr.size; y++) {
47
    for (int x = 0; x < qr.size; x++) {
48
        boolean isDark = qr.getModule(x, y);
49
        // Use isDark to render the QR code
50
    }
51
}
52
```
53

54
### Binary Data Encoding
55

56
```java
57
import io.nayuki.qrcodegen.QrCode;
58

59
// Encode binary data
60
byte[] data = "Binary data example".getBytes("UTF-8");
61
QrCode qr = QrCode.encodeBinary(data, QrCode.Ecc.HIGH);
62
```
63

64
### Custom Segments
65

66
```java
67
import io.nayuki.qrcodegen.QrCode;
68
import io.nayuki.qrcodegen.QrSegment;
69
import java.util.List;
70

71
// Create optimized segments for mixed content
72
List<QrSegment> segments = QrSegment.makeSegments("ABC123");
73
QrCode qr = QrCode.encodeSegments(segments, QrCode.Ecc.MEDIUM);
74

75
// Manual segment creation with full control
76
segments = QrSegment.makeSegments("3141592653589793238462643383");
77
QrCode qr2 = QrCode.encodeSegments(
78
    segments,
79
    QrCode.Ecc.HIGH,  // Error correction level
80
    5,                // Minimum version
81
    5,                // Maximum version  
82
    2,                // Mask pattern (or -1 for auto)
83
    false             // Don't boost error correction
84
);
85
```
86

87
## Architecture
88

89
The library provides a layered API design:
90

91
- **High-Level**: Simple factory methods (`encodeText`, `encodeBinary`) for common use cases
92
- **Mid-Level**: Segment-based encoding (`encodeSegments`) for custom data organization
93
- **Low-Level**: Direct constructor access for complete manual control
94

95
Key components:
96
- **QrCode**: Immutable QR code representation with grid access
97
- **QrSegment**: Data segments with different encoding modes  
98
- **Error Correction**: Four levels (Low ~7%, Medium ~15%, Quartile ~25%, High ~30%)
99
- **Encoding Modes**: Numeric, Alphanumeric, Byte, Kanji, and ECI
100

101
## Capabilities
102

103
### QR Code Generation
104

105
Core functionality for creating QR codes from various data types with automatic optimization.
106

107
```java { .api }
108
// High-level text encoding
109
public static QrCode encodeText(
110
    CharSequence text,  // text to encode (Unicode supported)
111
    Ecc ecl            // error correction level (boostable)
112
)
113

114
// High-level binary encoding  
115
public static QrCode encodeBinary(
116
    byte[] data,  // binary data to encode
117
    Ecc ecl      // error correction level (boostable)
118
)
119

120
// Mid-level segment encoding with automatic parameters
121
public static QrCode encodeSegments(
122
    List<QrSegment> segs,  // segments to encode
123
    Ecc ecl               // error correction level (boostable)
124
)
125

126
// Mid-level segment encoding with manual control
127
public static QrCode encodeSegments(
128
    List<QrSegment> segs,  // segments to encode (not null, not empty)
129
    Ecc ecl,              // error correction level (not null, boostable)
130
    int minVersion,       // minimum QR version (1 ≤ minVersion ≤ maxVersion ≤ 40)
131
    int maxVersion,       // maximum QR version (minVersion ≤ maxVersion ≤ 40)
132
    int mask,            // mask pattern (0-7 for fixed pattern, -1 for auto-select)
133
    boolean boostEcl     // boost ECC level if no version increase required
134
)
135

136
// Low-level constructor for complete control
137
public QrCode(
138
    int ver,             // version number (1-40)
139
    Ecc ecl,            // error correction level
140
    byte[] dataCodewords, // data bytes (without ECC)
141
    int msk             // mask pattern (-1 for auto, 0-7 for fixed)
142
)
143
```
144

145
### Data Segmentation
146

147
Create and optimize data segments for efficient QR code encoding.
148

149
```java { .api }
150
// Create segments from different data types
151
public static QrSegment makeBytes(byte[] data)  // binary data
152
public static QrSegment makeNumeric(CharSequence digits)  // digits 0-9 only
153
public static QrSegment makeAlphanumeric(CharSequence text)  // 0-9,A-Z,space,$%*+-./:
154
public static List<QrSegment> makeSegments(CharSequence text)  // auto-optimized segments
155
public static QrSegment makeEci(int assignVal)  // ECI assignment number (0 ≤ assignVal < 1000000)
156

157
// Test segment encodability
158
public static boolean isNumeric(CharSequence text)  // test for digits only
159
public static boolean isAlphanumeric(CharSequence text)  // test for alphanumeric chars
160

161
// Manual segment construction
162
public QrSegment(
163
    Mode md,      // segment mode (not null)
164
    int numCh,    // character/byte count (0 ≤ numCh < 2^16 depending on version)
165
    BitBuffer data // segment data bits (not null, cloned defensively)
166
)
167

168
// Access segment data
169
public BitBuffer getData()  // returns defensive copy
170
```
171

172
### Advanced Optimization
173

174
Sophisticated encoding optimization and Japanese kanji support.
175

176
```java { .api }
177
// Optimal segment mode switching for minimal bit length
178
public static List<QrSegment> makeSegmentsOptimally(
179
    CharSequence text,  // text to encode (not null, Unicode supported)
180
    QrCode.Ecc ecl,    // error correction level (not null)
181
    int minVersion,    // minimum QR version (1 ≤ minVersion ≤ maxVersion ≤ 40)
182
    int maxVersion     // maximum QR version (minVersion ≤ maxVersion ≤ 40) 
183
)
184

185
// Japanese kanji mode encoding
186
public static QrSegment makeKanji(CharSequence text)  // kanji-encodable text only
187
public static boolean isEncodableAsKanji(CharSequence text)  // test for kanji chars
188
```
189

190
### QR Code Access
191

192
Access QR code properties and module data for rendering.
193

194
```java { .api }
195
// QR code properties  
196
public final int version      // Version number (1-40)
197
public final int size         // Size in modules (21-177)
198
public final Ecc errorCorrectionLevel  // Error correction level
199
public final int mask         // Mask pattern (0-7)
200

201
// Module access
202
public boolean getModule(
203
    int x,  // x coordinate (0 to size-1)
204
    int y   // y coordinate (0 to size-1)
205
)
206

207
// Version constants - supported QR Code version range
208
public static final int MIN_VERSION = 1   // Minimum supported QR Code version (21×21 modules) 
209
public static final int MAX_VERSION = 40  // Maximum supported QR Code version (177×177 modules)
210
```
211

212
### Bit Buffer Utilities
213

214
Low-level bit manipulation for custom segment creation.
215

216
```java { .api }
217
// Bit buffer construction and access
218
public BitBuffer()  // creates empty buffer (length 0)
219
public int bitLength()  // returns current bit length (≥0)
220
public int getBit(int index)  // returns bit at index (0 ≤ index < bitLength(), returns 0 or 1)
221

222
// Bit buffer modification
223
public void appendBits(
224
    int val,  // value to append (0 ≤ val < 2^len)
225
    int len   // number of low-order bits (0 ≤ len ≤ 31)
226
)
227
public void appendData(BitBuffer bb)  // append another buffer's bits (bb not null)
228
public BitBuffer clone()  // create defensive copy
229
```
230

231
## Types
232

233
### Error Correction Levels
234

235
```java { .api }
236
public enum Ecc {
237
    LOW,        // ~7% error tolerance, format bits: 1
238
    MEDIUM,     // ~15% error tolerance, format bits: 0  
239
    QUARTILE,   // ~25% error tolerance, format bits: 3
240
    HIGH        // ~30% error tolerance, format bits: 2
241
}
242
```
243

244
### Segment Modes
245

246
```java { .api }
247
public enum Mode {
248
    NUMERIC,      // Digits 0-9 only
249
    ALPHANUMERIC, // 0-9, A-Z, space, $%*+-./:
250
    BYTE,         // Arbitrary binary data
251
    KANJI,        // Japanese kanji characters
252
    ECI           // Extended Channel Interpretation
253
}
254
```
255

256
### Exception Types
257

258
```java { .api }
259
public class DataTooLongException extends IllegalArgumentException {
260
    public DataTooLongException()
261
    public DataTooLongException(String msg)
262
}
263
```
264

265
## Usage Examples
266

267
### Numeric Optimization
268

269
```java
270
// Automatically optimized for numeric content
271
QrCode qr = QrCode.encodeText("1234567890", QrCode.Ecc.LOW);
272

273
// Manual numeric segment
274
QrSegment numericSeg = QrSegment.makeNumeric("1234567890");
275
List<QrSegment> segs = Arrays.asList(numericSeg);
276
QrCode qr2 = QrCode.encodeSegments(segs, QrCode.Ecc.LOW);
277
```
278

279
### Mixed Content Optimization
280

281
```java
282
// Automatic mode switching for optimal encoding
283
String mixedData = "ABC123def456";
284
List<QrSegment> segments = QrSegmentAdvanced.makeSegmentsOptimally(
285
    mixedData, 
286
    QrCode.Ecc.MEDIUM, 
287
    1, 
288
    40
289
);
290
QrCode qr = QrCode.encodeSegments(segments, QrCode.Ecc.MEDIUM);
291
```
292

293
### Version and Mask Control
294

295
```java
296
List<QrSegment> segments = QrSegment.makeSegments("Controlled encoding");
297
QrCode qr = QrCode.encodeSegments(
298
    segments,
299
    QrCode.Ecc.QUARTILE,
300
    10,     // Minimum version 10
301
    15,     // Maximum version 15
302
    4,      // Use mask pattern 4
303
    true    // Allow error correction boosting
304
);
305
```
306

307
### Binary Data with ECI
308

309
```java
310
import java.nio.charset.StandardCharsets;
311

312
// Binary data with ECI for character set identification
313
List<QrSegment> segments = new ArrayList<>();
314
segments.add(QrSegment.makeEci(26));  // UTF-8 ECI assignment
315
segments.add(QrSegment.makeBytes("日本語".getBytes(StandardCharsets.UTF_8)));
316

317
QrCode qr = QrCode.encodeSegments(segments, QrCode.Ecc.HIGH);
318
```
319

320
### Error Handling
321

322
```java
323
// Basic error handling for text encoding
324
try {
325
    String longText = "Very long text that might not fit in any QR code version...";
326
    QrCode qr = QrCode.encodeText(longText, QrCode.Ecc.LOW);
327
} catch (DataTooLongException e) {
328
    System.err.println("Text too long: " + e.getMessage());
329
    // Solutions: reduce text, use lower error correction, or split into multiple codes
330
}
331

332
// Error handling with version constraints
333
try {
334
    List<QrSegment> segments = QrSegment.makeSegments("Medium length text");
335
    QrCode qr = QrCode.encodeSegments(segments, QrCode.Ecc.HIGH, 1, 10, -1, false);
336
} catch (DataTooLongException e) {
337
    System.err.println("Data doesn't fit in versions 1-10 at HIGH error correction");
338
    // Solutions: increase maxVersion, reduce error correction level, or optimize segments
339
}
340

341
// Advanced error handling with fallback strategies
342
String data = "Text to encode with fallback strategies";
343
QrCode qr = null;
344

345
// Try HIGH error correction first
346
try {
347
    qr = QrCode.encodeText(data, QrCode.Ecc.HIGH);
348
} catch (DataTooLongException e) {
349
    try {
350
        // Fallback to MEDIUM error correction
351
        qr = QrCode.encodeText(data, QrCode.Ecc.MEDIUM);
352
    } catch (DataTooLongException e2) {
353
        try {
354
            // Final fallback to LOW error correction
355
            qr = QrCode.encodeText(data, QrCode.Ecc.LOW);
356
        } catch (DataTooLongException e3) {
357
            System.err.println("Data too long even for LOW error correction");
358
            // Must reduce data size or split into multiple QR codes
359
        }
360
    }
361
}
362

363
// Parameter validation examples
364
try {
365
    // Invalid version range will throw IllegalArgumentException
366
    List<QrSegment> segs = QrSegment.makeSegments("test");
367
    QrCode qr = QrCode.encodeSegments(segs, QrCode.Ecc.MEDIUM, 5, 3, -1, false); // minVersion > maxVersion
368
} catch (IllegalArgumentException e) {
369
    System.err.println("Invalid parameters: " + e.getMessage());
370
}
371

372
try {
373
    // Invalid mask pattern will throw IllegalArgumentException  
374
    List<QrSegment> segs = QrSegment.makeSegments("test");
375
    QrCode qr = QrCode.encodeSegments(segs, QrCode.Ecc.MEDIUM, 1, 40, 8, false); // mask > 7
376
} catch (IllegalArgumentException e) {
377
    System.err.println("Invalid mask pattern: " + e.getMessage());
378
}
379
```
380

381
## Standards Compliance
382

383
- **QR Code Model 2**: Full compliance with ISO/IEC 18004 standard
384
- **Versions**: All 40 versions supported (21×21 to 177×177 modules)
385
- **Error Correction**: All 4 levels with accurate penalty pattern detection
386
- **Character Modes**: Numeric, Alphanumeric, Byte (UTF-8), Kanji, and ECI
387
- **Mask Patterns**: All 8 mask patterns with automatic optimal selection
388
- **Encoding Optimization**: Advanced algorithms for minimal bit length