Class QrCode

Namespace

Net.Codecrete.QrCodeGenerator

Assembly

QrCodeGenerator.dll

Represents a QR code containing text or binary data.

Instances of this class represent an immutable square grid of dark and light pixels (called modules by the QR code specification). Static factory methods are provided to create QR codes from text or binary data. Some of the methods provide detailed control about the encoding parameters such a QR code size (called version by the standard), error correction level and mask.

QR codes are a type of two-dimensional barcodes, invented by Denso Wave and described in the ISO/IEC 18004 standard.

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

public class QrCode

Inheritance

object

QrCode

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

To create a QR code instance:

• High level: Take the payload data and call EncodeText(string, Ecc) or EncodeBinary(byte[], Ecc).
• Mid level: Custom-make a list of QrSegment instances and call EncodeSegments(List<QrSegment>, Ecc, int, int, int, bool)
• Low level: Custom-make an array of data codeword bytes (including segment headers and final padding, excluding error correction codewords), supply the appropriate version number, and call the QrCode(int, Ecc, byte[], int).

Constructors

QrCode(int, Ecc, byte[], int)

Constructs a QR code with the specified version number, error correction level, data codeword bytes, and mask number.

public QrCode(int version, QrCode.Ecc ecl, byte[] dataCodewords, int mask = -1)

Parameters

version int

The version (size) to use (between 1 to 40).

ecl QrCode.Ecc

The error correction level to use.

dataCodewords byte[]

The bytes representing segments to encode (without ECC).

mask int

The mask pattern to use (either -1 for automatic selection, or a value from 0 to 7 for fixed choice).

Remarks

This is a low-level API that most users should not use directly. A mid-level API is the EncodeSegments(List<QrSegment>, Ecc, int, int, int, bool) function.

Exceptions

ArgumentNullException

ecl or dataCodewords is null.

ArgumentOutOfRangeException

The version or mask value is out of range, or the data has an invalid length for the specified version and error correction level.

Fields

MaxVersion

The maximum version (size) supported in the QR Code Model 2 standard – namely 40.

public const int MaxVersion = 40

Field Value

int

The maximum version.

MinVersion

The minimum version (size) supported in the QR Code Model 2 standard – namely 1.

public const int MinVersion = 1

Field Value

int

The minimum version.

Properties

ErrorCorrectionLevel

The error correction level used for this QR code.

public QrCode.Ecc ErrorCorrectionLevel { get; }

Property Value

QrCode.Ecc

The error correction level.

Mask

The index of the mask pattern used fort this QR code (between 0 and 7).

Even if a QR code is created with automatic mask selection (mask = 1), this property returns the effective mask used.

public int Mask { get; }

Property Value

int

The mask pattern index.

Size

The width and height of this QR code, in modules (pixels). The size is a value between 21 and 177. This is equal to version × 4 + 17.

public int Size { get; }

Property Value

int

The QR code size.

Version

The version (size) of this QR code (between 1 for the smallest and 40 for the biggest).

public int Version { get; }

Property Value

int

The QR code version (size).

Methods

EncodeBinary(byte[], Ecc)

Creates a QR code representing the specified binary data using the specified error correction level.

This function encodes the data in the binary segment mode. The maximum number of bytes allowed is 2953. The smallest possible QR code version is automatically chosen. The resulting ECC level will be higher than the one specified if it can be achieved without increasing the size (version).

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

Parameters

data byte[]

The binary data to encode.

ecl QrCode.Ecc

The minimum error correction level to use.

Returns

QrCode

The created QR code representing the specified data.

Exceptions

ArgumentNullException

data or ecl is null.

DataTooLongException

The specified data is too long to fit in the largest QR code size (version) at the specified error correction level.

EncodeSegments(List<QrSegment>, Ecc, int, int, int, bool)

Creates a QR code representing the specified segments with the specified encoding parameters.

The smallest possible QR code version (size) is used. The range of versions can be restricted by the minVersion and maxVersion parameters.

If boostEcl is true, the resulting ECC level will be higher than the one specified if it can be achieved without increasing the size (version).

The QR code mask is usually automatically chosen. It can be explicitly set with the mask parameter by using a value between 0 to 7 (inclusive). -1 is for automatic mode (which may be slow).

This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and byte) to encode text in less space and gives full control over all encoding parameters.

public static QrCode EncodeSegments(List<QrSegment> segments, QrCode.Ecc ecl, int minVersion = 1, int maxVersion = 40, int mask = -1, bool boostEcl = true)

Parameters

segments List<QrSegment>

The segments to encode.

ecl QrCode.Ecc

The minimal or fixed error correction level to use .

minVersion int

The minimum version (size) of the QR code (between 1 and 40).

maxVersion int

The maximum version (size) of the QR code (between 1 and 40).

mask int

The mask number to use (between 0 and 7), or -1 for automatic mask selection.

boostEcl bool

If true the ECC level wil be increased if it can be achieved without increasing the size (version).

Returns

QrCode

The created QR code representing the segments.

Remarks

This is a mid-level API; the high-level APIs are EncodeText(string, Ecc) and EncodeBinary(byte[], Ecc).

Exceptions

ArgumentNullException

segments, any list element, or ecl is null.

ArgumentOutOfRangeException

1 ≤ minVersion ≤ maxVersion ≤ 40 or -1 ≤ mask ≤ 7 is violated.

DataTooLongException

The segments are too long to fit in the largest QR code size (version) at the specified error correction level.

EncodeText(string, Ecc)

Creates a QR code representing the specified text using the specified error correction level.

As a conservative upper bound, this function is guaranteed to succeed for strings with up to 738 Unicode code points (not UTF-16 code units) if the low error correction level is used. The smallest possible QR code version (size) is automatically chosen. The resulting ECC level will be higher than the one specified if it can be achieved without increasing the size (version).

public static QrCode EncodeText(string text, QrCode.Ecc ecl)

Parameters

text string

The text to be encoded. The full range of Unicode characters may be used.

ecl QrCode.Ecc

The minimum error correction level to use.

Returns

QrCode

The created QR code instance representing the specified text.

Exceptions

ArgumentNullException

text or ecl is null.

DataTooLongException

The text is too long to fit in the largest QR code size (version) at the specified error correction level.

EncodeTextInMultipleCodes(string, Ecc, int, bool)

Creates a series of QR codes representing the specified text.

The result will consist of the minimal number of QR codes needed to encode the text with the given error correction level and version (size of QR code). If multiple QR codes are required, Structured Append data is included to link the QR codes.

Each QR code might use multiple segments with different encoding modes to maximize the amount of text that can be stored in each QR code.

Each QR code will contain a valid string as it is ensured that splitting only occurs at character boundaries and not in the middle of a multi-byte encoding of a character. This increases compatibility with QR code scanners that incorrectly assume that each individual QR code in the series contains a valid UTF-8 string.

public static List<QrCode> EncodeTextInMultipleCodes(string text, QrCode.Ecc ecl, int version = 29, bool boostEcl = true)

Parameters

text string

The text to be encoded. The full range of Unicode characters may be used.

ecl QrCode.Ecc

The minimum error correction level to use.

version int

The version (size of QR code) to use. Default is 29.

boostEcl bool

Whether error correction level should be upgraded if possible. Default is false.

Returns

List<QrCode>

A list of QR codes representing the specified text.

Exceptions

ArgumentNullException

text or ecl is null.

DataTooLongException

The text is too long to fit the maximum of 16 QR codes with the given parameters.

GetModule(int, int)

Gets the color of the module (pixel) at the specified coordinates.

The top left corner has the coordinates (x=0, y=0). x-coordinates extend from left to right, y-coordinates extend from top to bottom.

If coordinates outside the bounds of this QR code are specified, light (false) is returned.

public bool GetModule(int x, int y)

Parameters

x int

The x coordinate.

y int

The y coordinate.

Returns

bool

The color of the specified module: true for dark modules and false for light modules (or if the coordinates are outside the bounds).

GetNumDataCodewords(int, Ecc)

Returns the number of 8-bit data codewords contained in a QR code of the given version number and error correction level.

The result is the net data capacity, without error correction data, and after discarding remainder bits.

public static int GetNumDataCodewords(int ver, QrCode.Ecc ecl)

Parameters

ver int

The version number.

ecl QrCode.Ecc

The error correction level.

Returns

int

The number of codewords.

RgbColor(byte, byte, byte)

Creates an RGB color value in little endian format.

public int RgbColor(byte red, byte green, byte blue)

Parameters

red byte

Red component.

green byte

Green component.

blue byte

Blue component.

Returns

int

RGB color value

ToBmpBitmap(int, int)

Creates bitmap in the BMP format data using black for dark modules and white for light modules.

The bitmap uses 1 bit per pixel and a color table with 2 entries.

public byte[] ToBmpBitmap(int border = 0, int scale = 1)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size.

scale int

The width and height, in pixels, of each module.

Returns

byte[]

Bitmap data

Exceptions

ArgumentOutOfRangeException

Thrown if border is negative, scale is less than 1 or the resulting image is wider than 32,768 pixels.

ToBmpBitmap(int, int, int, int)

Creates a bitmap in the BMP format.

The bitmap uses 1 bit per pixel and a color table with 2 entries.

Color values can be created with RgbColor(byte, byte, byte).

public byte[] ToBmpBitmap(int border, int scale, int foreground, int background)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size.

scale int

The width and height, in pixels, of each module.

foreground int

The foreground color (dark modules), in RGB value (little endian).

background int

The background color (light modules), in RGB value (little endian).

Returns

byte[]

Bitmap data

Exceptions

ArgumentOutOfRangeException

Thrown if border is negative, scale is less than 1 or the resulting image is wider than 32,768 pixels.

ToGraphicsPath(int)

Creates a graphics path of this QR code valid in SVG or XAML.

The graphics path uses a coordinate system where each module is 1 unit wide and tall, and the top left module is offset vertically and horizontally by border units.

Note that a border width other than 0 only make sense if the bounding box of the QR code is explicitly set by the graphics using this path. If the bounding box of this path is automatically derived, at least the right and bottom border will be missing.

The path will look like this: M3,3h7v1h-7z M12,3h1v4h-1z ... M70,71h1v1h-1z. It is valid for SVG (<path d="M3,3h..." />) and for XAML (<Path Data="M3,3h..." />). For programmatic geometry creation in WPF see Geometry.Parse(String).

public string ToGraphicsPath(int border = 0)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size

Returns

string

The graphics path

Exceptions

ArgumentOutOfRangeException

Thrown if border is negative

ToPngBitmap(int, int)

Creates bitmap in the PNG format data using black for dark modules and white for light modules.

public byte[] ToPngBitmap(int border = 0, int scale = 1)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size.

scale int

The width and height, in pixels, of each module.

Returns

byte[]

Bitmap data

ToPngBitmap(int, int, int, int)

Creates bitmap in the PNG format data using specified foreground and background colors for dark and light modules.

public byte[] ToPngBitmap(int border, int scale, int foreground, int background)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size.

scale int

The width and height, in pixels, of each module.

foreground int

The foreground color (dark modules), in RGB value (little endian).

background int

The background color (light modules), in RGB value (little endian).

Returns

byte[]

Bitmap data

ToSvgString(int)

Creates an SVG image of this QR code.

The images uses Unix newlines (\n), regardless of the platform.

public string ToSvgString(int border)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size

Returns

string

The SVG image as a string.

ToSvgString(int, string, string)

Creates an SVG image of this QR code.

The images uses Unix newlines (\n), regardless of the platform.

Colors are specified using CSS color data type. Examples of valid values are "#339966", "fuchsia", "rgba(137, 23, 89, 0.3)".

public string ToSvgString(int border, string foreground, string background)

Parameters

border int

The border width, as a factor of the module (QR code pixel) size

foreground string

The foreground color.

background string

The background color.

Returns

string

See Also

QrSegment