io.nayuki.qrcodegen

Class QrCode

java.lang.Object

io.nayuki.qrcodegen.QrCode

public final class QrCode
extends Object

Represents an immutable square grid of black and white cells for a QR Code symbol, and provides static functions to create a QR Code from user-supplied textual or binary data.

This class covers the QR Code model 2 specification, supporting all versions (sizes) from 1 to 40, all 4 error correction levels, and only 3 character encoding modes.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QrCode.Ecc Represents the error correction level used in a QR Code symbol.

Field Summary

Fields

Modifier and Type	Field and Description
QrCode.Ecc	errorCorrectionLevel The error correction level used in this QR Code symbol.
int	mask The mask pattern used in this QR Code symbol, in the range 0 to 7 (i.e.
static int	MAX_VERSION
static int	MIN_VERSION
int	size The width and height of this QR Code symbol, measured in modules.
int	version This QR Code symbol's version number, which is always between 1 and 40 (inclusive).

Constructor Summary

Constructors

Constructor and Description
QrCode(int ver, QrCode.Ecc ecl, byte[] dataCodewords, int mask) Creates a new QR Code symbol with the specified version number, error correction level, binary data array, and mask number.

Method Summary

Modifier and Type	Method and Description
static QrCode	encodeBinary(byte[] data, QrCode.Ecc ecl) Returns a QR Code symbol representing the specified binary data string at the specified error correction level.
static QrCode	encodeSegments(List<QrSegment> segs, QrCode.Ecc ecl) Returns a QR Code symbol representing the specified data segments at the specified error correction level or higher.
static QrCode	encodeSegments(List<QrSegment> segs, QrCode.Ecc ecl, int minVersion, int maxVersion, int mask, boolean boostEcl) Returns a QR Code symbol representing the specified data segments with the specified encoding parameters.
static QrCode	encodeText(String text, QrCode.Ecc ecl) Returns a QR Code symbol representing the specified Unicode text string at the specified error correction level.
boolean	getModule(int x, int y) Returns the color of the module (pixel) at the specified coordinates, which is either false for white or true for black.
BufferedImage	toImage(int scale, int border) Returns a new image object representing this QR Code, with the specified module scale and number of border modules.
String	toSvgString(int border) Based on the specified number of border modules to add as padding, this returns a string whose contents represents an SVG XML file that depicts this QR Code symbol.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MIN_VERSION

public static final int MIN_VERSION

See Also:

Constant Field Values

MAX_VERSION

public static final int MAX_VERSION

See Also:

Constant Field Values

version

public final int version

This QR Code symbol's version number, which is always between 1 and 40 (inclusive).

size

public final int size

The width and height of this QR Code symbol, measured in modules. Always equal to version × 4 + 17, in the range 21 to 177.

errorCorrectionLevel

public final QrCode.Ecc errorCorrectionLevel

The error correction level used in this QR Code symbol. Never null.

mask

public final int mask

The mask pattern used in this QR Code symbol, in the range 0 to 7 (i.e. unsigned 3-bit integer). Note that even if a constructor was called with automatic masking requested (mask = -1), the resulting object will still have a mask value between 0 and 7.

Constructor Detail

QrCode

public QrCode(int ver,
              QrCode.Ecc ecl,
              byte[] dataCodewords,
              int mask)

Creates a new QR Code symbol with the specified version number, error correction level, binary data array, and mask number.

This is a cumbersome low-level constructor that should not be invoked directly by the user. To go one level up, see the encodeSegments(List,Ecc) function.

Parameters:

ver - the version number to use, which must be in the range 1 to 40, inclusive

ecl - the error correction level to use

dataCodewords - the raw binary user data to encode

mask - the mask pattern to use, which is either -1 for automatic choice or from 0 to 7 for fixed choice

Throws:

NullPointerException - if the byte array or error correction level is null

IllegalArgumentException - if the version or mask value is out of range

Method Detail

encodeText

public static QrCode encodeText(String text,
                                QrCode.Ecc ecl)

Returns a QR Code symbol representing the specified Unicode text string at the specified error correction level. As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.

Parameters:

text - the text to be encoded, which can be any Unicode string

ecl - the error correction level to use (will be boosted)

Returns:

a QR Code representing the text

Throws:

NullPointerException - if the text or error correction level is null

IllegalArgumentException - if the text fails to fit in the largest version QR Code, which means it is too long

encodeBinary

public static QrCode encodeBinary(byte[] data,
                                  QrCode.Ecc ecl)

Returns a QR Code symbol representing the specified binary data string at the specified error correction level. This function always encodes using the binary segment mode, not any text mode. The maximum number of bytes allowed is 2953. The smallest possible QR Code version is automatically chosen for the output. The ECC level of the result may be higher than the ecl argument if it can be done without increasing the version.

Parameters:

data - the binary data to encode

ecl - the error correction level to use (will be boosted)

Returns:

a QR Code representing the binary data

Throws:

NullPointerException - if the data or error correction level is null

IllegalArgumentException - if the data fails to fit in the largest version QR Code, which means it is too long

encodeSegments

public static QrCode encodeSegments(List<QrSegment> segs,
                                    QrCode.Ecc ecl)

Returns a QR Code symbol representing the specified data segments at the specified error correction level or higher. The smallest possible QR Code version is automatically chosen for the output.

This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and binary) to encode text more efficiently. This function is considered to be lower level than simply encoding text or binary data.

Parameters:

segs - the segments to encode

ecl - the error correction level to use (will be boosted)

Returns:

a QR Code representing the segments

Throws:

NullPointerException - if the list of segments, a segment, or the error correction level is null

IllegalArgumentException - if the data is too long to fit in the largest version QR Code at the ECL

encodeSegments

public static QrCode encodeSegments(List<QrSegment> segs,
                                    QrCode.Ecc ecl,
                                    int minVersion,
                                    int maxVersion,
                                    int mask,
                                    boolean boostEcl)

Returns a QR Code symbol representing the specified data segments with the specified encoding parameters. The smallest possible QR Code version within the specified range is automatically chosen for the output.

This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and binary) to encode text more efficiently. This function is considered to be lower level than simply encoding text or binary data.

Parameters:

segs - the segments to encode

ecl - the error correction level to use (may be boosted)

minVersion - the minimum allowed version of the QR symbol (at least 1)

maxVersion - the maximum allowed version of the QR symbol (at most 40)

mask - the mask pattern to use, which is either -1 for automatic choice or from 0 to 7 for fixed choice

boostEcl - increases the error correction level if it can be done without increasing the version number

Returns:

a QR Code representing the segments

Throws:

NullPointerException - if the list of segments, a segment, or the error correction level is null

IllegalArgumentException - if 1 ≤ minVersion ≤ maxVersion ≤ 40 is violated, or if mask < −1 or mask > 7, or if the data is too long to fit in a QR Code at maxVersion at the ECL

getModule

public boolean getModule(int x,
                         int y)

Returns the color of the module (pixel) at the specified coordinates, which is either false for white or true for black. The top left corner has the coordinates (x=0, y=0). If the specified coordinates are out of bounds, then false (white) is returned.

Parameters:

x - the x coordinate, where 0 is the left edge and size−1 is the right edge

y - the y coordinate, where 0 is the top edge and size−1 is the bottom edge

Returns:

the module's color, which is either false (white) or true (black)

toImage

public BufferedImage toImage(int scale,
                             int border)

Returns a new image object representing this QR Code, with the specified module scale and number of border modules. For example, the arguments scale=10, border=4 means to pad the QR Code symbol with 4 white border modules on all four edges, then use 10*10 pixels to represent each module. The resulting image only contains the hex colors 000000 and FFFFFF.

Parameters:

scale - the module scale factor, which must be positive

border - the number of border modules to add, which must be non-negative

Returns:

an image representing this QR Code, with padding and scaling

Throws:

IllegalArgumentException - if the scale or border is out of range

toSvgString

public String toSvgString(int border)

Based on the specified number of border modules to add as padding, this returns a string whose contents represents an SVG XML file that depicts this QR Code symbol. Note that Unix newlines (\n) are always used, regardless of the platform.

Parameters:

border - the number of border modules to add, which must be non-negative

Returns:

a string representing this QR Code as an SVG document