Project Nayuki


QR Code generator library

Introduction

This project aims to be the best, clearest library for generating QR Codes. My primary goals are flexible options and absolute correctness. Secondary goals are compact implementation size and good documentation comments.

This work is an independent implementation based on reading the official ISO specification documents. I believe that my library has a more intuitive API and shorter code length than competing libraries out there. The library is designed first in Java and then ported to JavaScript, Python, C++, C, and Rust. It is open source under the MIT License. For each language, the codebase is roughly 1000 lines of code and has no dependencies other than the respective language’s standard library.

Live demo (JavaScript)

You can generate QR Code symbols conveniently on this web page, powered by the JavaScript version of this library.

Text string:
QR Code:
Error correction:
Output format:
Border: modules
Scale: pixels per module
Version range: Minimum = , maximum =
Mask pattern: (−1 for automatic, 0 to 7 for manual)
Boost ECC:
Statistics:

Features

Core features:

Manual parameters:

Optional advanced features (Java only):

Source code

This library is designed with essentially the same API structure and naming in multiple languages for your convenience: Java, JavaScript, Python, C++, Rust – but a different API in C to avoid dynamic allocation. Regardless of the language used, the generated results are guaranteed to be identical because the algorithms are translated faithfully.

For my own convenience when designing and testing the code, the Java language version of the QR Code generator library is considered to be the master reference version. The JavaScript, Python, C++, and Rust versions are ported from the Java version, with a balance between writing idiomatic code in the target language but also not deviating too much from the Java version’s design. When in doubt, please consult the Java version to read the more extensive documentation comments and to check what types and values are considered legal.

The full project repository is available at GitHub:
https://github.com/nayuki/QR-Code-generator

Java

The library: QrCode.java, QrSegment.java, BitBuffer.java
Optional advanced logic: QrSegmentAdvanced.java
Runnable demo program: QrCodeGeneratorDemo.java

Usage examples:

import java.awt.image.BufferedImage;
import java.io.File;
import javax.imageio.ImageIO;
import io.nayuki.qrcodegen.*;

// Simple operation
QrCode qr0 = QrCode.encodeText("Hello, world!", QrCode.Ecc.MEDIUM);
BufferedImage img = qr0.toImage(4, 10);
ImageIO.write(img, "png", new File("qr-code.png"));

// Manual operation
List<QrSegment> segs = QrSegment.makeSegments("3141592653589793238462643383");
QrCode qr1 = QrCode.encodeSegments(segs, QrCode.Ecc.HIGH, 5, 5, 2, false);
for (int y = 0; y < qr1.size; y++) {
    for (int x = 0; x < qr1.size; x++) {
        (... paint qr1.getModule(x, y) ...)
    }
}

This compact, no-dependency library is your one-stop shop for all your QR Code generation needs. To learn how to use the API, please read the demo program’s source code, and maybe skim the library code’s inline Javadoc comments.

For the following practical reasons, Java is my best choice for the reference version because it ensures a high degree of correctness and allows writing detailed documentation comments:

  • Static type checking prevents dumb typos in names and subtly incorrect arguments being passed (such as byte[] vs. BitBuffer). (Whereas Python and JavaScript don’t have static type checking.)

  • There is a strong and clear separation between public interfaces and private implementation details. (Whereas privacy is only a naming convention in Python, and feasible but hacky/ugly in JavaScript.)

  • Javadoc is expressive and has a consistent syntax. (Whereas Python, JavaScript, and C++ do not have single dominant syntax for documentation comments.)

  • Java has good standard libraries for file, image, and network handling, and the language is memory-safe. This makes it easier to build a correct application quickly. (Whereas C++ programming easily gets into third-party library frenzy and undefined behavior hell – even though it does have static typing and proper public/private just like Java.)

  • Only the Java version of my library contains the advanced segment encoder logic for kanji mode and optimal segment mode switching.

JavaScript

The library: qrcodegen.js
The demo on this page: qrcodegen-demo.js

Usage examples:

// Name abbreviated for the sake of these examples here
var QRC = qrcodegen.QrCode;

// Simple operation
var qr0 = QRC.encodeText("Hello, world!", QRC.Ecc.MEDIUM);
var svg = qr0.toSvgString(4);

// Manual operation
var segs = qrcodegen.QrSegment.makeSegments("3141592653589793238462643383");
var qr1 = QRC.encodeSegments(segs, QRC.Ecc.HIGH, 5, 5, 2, false);
for (var y = 0; y < qr1.size; y++) {
    for (var x = 0; x < qr1.size; x++) {
        (... paint qr1.getModule(x, y) ...)
    }
}

The public interface (the set of available functions and constants) is summarized in the big block comment near the top of the library source file. Any function/variable not included in that comment is considered private and is subjected to change.

Although the low-level imperative code parts (e.g. loops, arithmetic) are virtually identical to the Java version, the organization of classes and methods looks quite different due to JavaScript’s use of closures to simulate objects. The documentation comments in the JavaScript version of the library is not as good as the Java version, and there is a higher risk of errors with respect to names and values.

Note that all private functions, methods, and fields are hidden as function-local variables so that it is impossible to access them from outside the library. This ensures that no external code depends on internal variables and APIs that might change in the future. On the other hand, all public fields and methods are writable, which means it is possible to (for example) reassign qrcodegen.QrCode to another value (please don’t do this).

Python

The library: qrcodegen.py
Runnable demo program: qrcodegen-demo.py

Also available as a package on PyPI: pip install qrcodegen

Usage examples:

from qrcodegen import *

# Simple operation
qr0 = QrCode.encode_text("Hello, world!", QrCode.Ecc.MEDIUM)
svg = qr0.to_svg_str(4)

# Manual operation
segs = QrSegment.make_segments("3141592653589793238462643383")
qr1 = QrCode.encode_segments(segs, QrCode.Ecc.HIGH, 5, 5, 2, False)
for y in range(qr1.get_size()):
    for x in range(qr1.get_size()):
        (... paint qr1.get_module(x, y) ...)

Python 2.7 and 3.x are supported. Please read the demo program’s source code to get a good idea of how to use this library. For further information, consult the big comment at the top of the library source file that summarizes all the public classes, functions, and methods available in the module.

C++

The library headers: QrCode.hpp, QrSegment.hpp, BitBuffer.hpp
The library definitions: QrCode.cpp, QrSegment.cpp, BitBuffer.cpp
Runnable demo program: QrCodeGeneratorDemo.cpp

Usage examples:

#include <string>
#include <vector>
#include "QrCode.hpp"
using namespace qrcodegen;

// Simple operation
QrCode qr0 = QrCode::encodeText("Hello, world!", QrCode::Ecc::MEDIUM);
std::string svg = qr0.toSvgString(4);

// Manual operation
std::vector<QrSegment> segs =
    QrSegment::makeSegments("3141592653589793238462643383");
QrCode qr1 = QrCode::encodeSegments(
    segs, QrCode::Ecc::HIGH, 5, 5, 2, false);
for (int y = 0; y < qr1.size; y++) {
    for (int x = 0; x < qr1.size; x++) {
        (... paint qr1.getModule(x, y) ...)
    }
}

The code requires C++11 to compile due to numerous convenient features unavailable in C++03, such as better handling of temporary values and const instance fields. The code is unfortunately not suitable for embedded microcontroller environments (e.g. Arduino) due to the use of the heavyweight STL std::vector class and dynamic memory allocation.

C

The library: qrcodegen.h, qrcodegen.c
Runnable demo program: qrcodegen-demo.c

Usage examples:

#include <stdbool.h>
#include <stdint.h>
#include "qrcodegen.h"

// Text data
uint8_t qr0[qrcodegen_BUFFER_LEN_MAX];
uint8_t tempBuffer[qrcodegen_BUFFER_LEN_MAX];
bool ok = qrcodegen_encodeText("Hello, world!",
    tempBuffer, qr0, qrcodegen_Ecc_MEDIUM,
    qrcodegen_VERSION_MIN, qrcodegen_VERSION_MAX,
    qrcodegen_Mask_AUTO, true);
if (!ok)
    return;

int size = qrcodegen_getSize(qr0);
for (int y = 0; y < size; y++) {
    for (int x = 0; x < size; x++) {
        (... paint qrcodegen_getModule(qr0, x, y) ...)
    }
}

// Binary data
uint8_t dataAndTemp[qrcodegen_BUFFER_LEN_FOR_VERSION(7)]
    = {0xE3, 0x81, 0x82};
uint8_t qr1[qrcodegen_BUFFER_LEN_FOR_VERSION(7)];
ok = qrcodegen_encodeBinary(dataAndTemp, 3, qr1,
    qrcodegen_Ecc_HIGH, 2, 7, qrcodegen_Mask_4, false);

Notes about this C version of the library:

  • Many projects choose the C programming language instead of C++, due to simpler semantics and more robust development tools (debuggers, etc.). This version of the library serves this market.

  • The other 4 language versions are facsimiles of each other in terms of code architecture, but this C library was written from scratch to avoid dynamic memory allocation and to fit C’s object-less programming paradigm.

  • The complete lack of heap allocation makes this code suitable for constrained environments such as operating system kernels and small microcontrollers (e.g. having 64 KiB of RAM). The C++ code, with its use of the heavyweight Standard Template Library (STL) and dynamic memory allocation in std::vector, is probably unsuitable for such environments.

  • The code requires a C99-compliant compiler and standard library to compile. It’s unsuitable for C89 compilers like Microsoft Visual C++, but can be adjusted for compilation in C++ mode as a workaround.

  • This code is portable and platform-independent by design. It makes no assumptions on endianness, integer type widths, two’s complement, etc. It only relies on behavior mandated by the C standard, such as the fact that int has at least 16 bits.

  • The C version of this library uses much more low-level indexing and raw buffer passing than the other 4 language versions, so the correctness of the logic is much less obvious at a glance. The safety of this C library was assured in multiple ways: Being mindful of value ranges and choosing suitably sized integer types, designing arithmetic operations to carefully avoid overflow, running the code under Clang’s UndefinedBehaviorSanitizer and AddressSanitizer and MemorySanitizer, and feeding millions of random inputs then testing for identical output against other language versions.

  • Here is a photo and video showing the C version of the QR Code generator library running on a PJRC Teensy 3.1 microcontroller. Remember that in the worst case, rendering a version 40 QR Code requires 8 KB of RAM (including temporary scratch space).

Rust

The library: lib.rs
Runnable demo program: qrcodegen-demo.rs

Usage examples:

extern crate qrcodegen;
use qrcodegen::QrCode;
use qrcodegen::QrCodeEcc;
use qrcodegen::QrSegment;

// Simple operation
let qr0 = QrCode::encode_text("Hello, world!",
    QrCodeEcc::Medium).unwrap();
let svg = qr0.to_svg_string(4);

// Manual operation
let chrs: Vec<char> = "3141592653589793238462643383".chars().collect();
let segs = QrSegment::make_segments(&chrs);
let qr1 = QrCode::encode_segments_advanced(
    &segs, QrCodeEcc::High, 5, 5, Some(2), false).unwrap();
for y in 0 .. qr1.size() {
    for x in 0 .. qr1.size() {
        (... paint qr1.get_module(x, y) ...)
    }
}

Notes about this Rust version of the library:

  • Has no crate dependencies, only relying on the standard library.

  • The source code files are laid out in directories according to the Cargo project format.

  • The higher level text APIs take &str (UTF-8 byte sequence), whereas the lower APIs take &[char] (Unicode code point sequence).

  • Unlike the {Java, JavaScript, Python, C++} language versions which throw exceptions for various conditions, the Rust version panics if an input violates a precondition (e.g. number out of range, character value outside of designated set). However, the encoder functions return None if the data is too long to fit in a QR Code, because this precondition is quite difficult for a library user to check ahead of time.


QR Code technology overview

The QR Code standard defines a method to encode a string of characters or bytes into a grid of black and white pixels. The text could be numbers, names, URLs, et cetera. Because the standard uses a 2D barcode, it can store much more information than a traditional 1D barcode. To illustrate for comparison, a 1D barcode usually stores 10 to 20 digits, while a QR code often stores 50 textual characters. Note that a QR Code barcode simply represents static data – the barcode does not inherently cause an action to be executed.

Terminology

Some of the frequently used official terminology have non-intuitive meanings, as summarized below:

QR Code

A popular international standard (symbology), created by Denso Wave, that specifies how messages are converted to barcodes.

QR Code symbol

A single 2D graphical barcode, which results from the QR Code generation process. Informally this is called a “QR code” (without using the word symbol) or a barcode.

Module

A black or white pixel in a QR Code symbol. Note that a module can be scaled to occupy multiple pixels on a screen or in an image file.

Version

A way of measuring the size of a symbol, from 1 to 40. Version 1 has 21×21 modules, version 2 has 25×25, ..., and version 40 has 177×177. Note that all 40 versions are defined in a single standard, and this term differs from the conventional meaning of the word version.

Model

Indicates the revision of the QR Code standard. (The word model here corresponds with the conventional meaning of the word version.) Model 1 QR codes are outdated and essentially never seen. Model 2 QR codes are widespread and dominant. Model 2 also has an extension called Micro QR codes (not implemented in my library). Note that model 1 defines versions 1 through 14, whereas model 2 QR defines versions versions 1 through 40, allowing much more data capacity.

Generation procedure

The process (and high-level algorithm) for generating a QR Code symbol is as follows:

  1. Choose the text (Unicode string) or binary data (byte string) to encode.

  2. Choose one of the 4 error correction levels (ECL). A higher ECC level will yield a barcode that tolerates more damaged parts while preserving the payload data, but will tend to increase the version number (i.e. more modules in width and height).

  3. Encode the text into a sequence of zero or more segments. A segment in byte mode can encode any data, but using alphanumeric or numeric mode is more compact if the text falls into these subsets.

  4. Based on the segments to be encoded and the ECL, choose a suitable QR Code version to contain the data, preferably the smallest one.

  5. Concatenate the segments (which have headers and payload) and add a terminator. The result is a sequence of bits.

  6. Add padding bits and bytes to fill the remaining data space (based on the version and ECL).

  7. Reinterpret the bitstream as a sequence of bytes, then divide it into blocks. Compute and append error correction bytes to each block. Interleave bytes from each block to form the final sequence of 8-bit codewords to be drawn.

  8. Initialize a blank square grid based on the version number.

  9. Draw the function patterns (finders, alignment, timing, version info, etc.) onto the appropriate modules. This is formatting overhead to support the QR Code standard, and does not encode any user data.

  10. Draw the sequence of (data + error correction) codewords onto the QR Code symbol, starting from the bottom right. Two columns at a time are used, and the scanning process zigzags going upward and downward. Any module that was drawn for a function pattern is skipped over in this step.

  11. Either manually or automatically choose a mask pattern to apply to the data modules. If masking automatically, then all 8 possibilities are tested and the one with the lowest penalty score is accepted. Note that the format information is redrawn to reflect the mask chosen.

  12. We are now finished the algorithmic parts of QR Code generation. The remaining work is to render the newly generated barcode symbol as a picture on screen, or save it as an image file on disk.

Note that my QR Code generator library provides the logic to perform steps 3 through 11. The other steps must be performed by the user of the library.

Compared to competitors

qrcodegen by Project Nayuki (Java, JavaScript, Python, C++, C)
  • Relatively compact implementation – 1220 lines of code for the Java version (without QrSegmentAdvanced), 1000 lines for JavaScript, 830 lines for Python, 1340 lines for C++, 940 lines for C, 1080 lines for Rust. (Each version is independent, so it’s meaningless to add up all the line counts.)

  • Contains as few tables of numerical constants as needed – unlike competitors, this implementation does not have tables of: data capacities per version, alignment pattern positions, error correction block sizes, expanded format and version bits, Reed-Solomon divisor polynomials, or finite field exp/log tables

  • The QR Code and helper objects are all immutable, thus simplifying user operation and reducing errors from accidental misuse of the API

  • Line counts include the generous amount of comments for functions, comments for blocks of statements, and blank lines – but not header comments of author and license info

  • The extra advanced features (kanji mode, optimal segment mode switching) in the Java version cost another 270 lines of code and 110 lines of constants

  • The version reviewed was 88ad854fd34c, dated 2017-04-21

qr.js by Kang Seonghoon (JavaScript)
  • About 800 lines of core code in the library

  • Code is quite concise, minimizing the size of constant tables and avoiding verbose logic

  • Includes generous comments explaining the overview of behavior

  • The organization and behavior of subfunctions (such as computing the number of bits and characters, and painting different sets of QR Code modules) are surprisingly similar to my design, despite the fact that he published one year earlier than me and I had never seen his code until months after I published my library

  • The code is more compact than mine in areas such as the bit buffer and segment encoding, because they are inlined into the QR Code generation workflow instead of being exported as freestanding modules

  • The version reviewed was 52f0409a22c5, dated 2015-04-11

qr.js by Alasdair Mercer (JavaScript)
  • About 1200 lines of core code in the library

  • qr.js: 800 lines for main QR encoding logic, 110 lines for numerical tables, 300 lines for image export

  • Code includes a good number of comments inside and outside functions

  • Only supports 8-bit segment encoding mode; generateFrame() is a 400-line monolithic function

  • The version reviewed was 18decea6ba9a, dated 2015-11-11. The library has since been renamed to QRious

QR Code Generator by Kazuhiko Arase (JavaScript, others)
  • About 1840 lines of core code in the JavaScript library

  • qrcode.js: 860 lines of code for main QR encoding logic, 340 lines for numerical tables, 360 lines for HTML and GIF output, 280 lines for binary encoding utilities

  • Contains no comments at all to describe functions; sparsely contains low-level comments to describe chunks of logic statements

  • The author has ported the library to multiple languages, but with different levels of features. The JavaScript version appears to be the most feature-complete, the Java version has fewer features but more documentation comments, and others have less features and comments.

  • The version reviewed was 94f0023b802a, dated 2016-01-23

QR-Logo by Henrik Kaare Poulsen (JavaScript)
  • About 2900 lines of core code in the library

  • Supports encoding and decoding(!) QR Code symbols

  • qrcodedecode.js: 970 lines of code for an encoder with the typical features, 1100 lines for a decoder that can operate on imperfect images (i.e. not axis-aligned with whole-pixel module size), 410 lines for tables of numbers

  • reedsolomon.js: 420 lines of code for Reed-Solomon encoding, decoding syndrome calculation, error correction, polynomial arithmetic

  • The version reviewed was b3a77e8f0145, dated 2011-10-15

qrcode by Lincoln Loop (Python)
  • About 1300 lines of core code in the library

  • main.py: 420 lines for text accumulation, module drawing, terminal printing

  • util.py: 550 lines for tables of various constants, QR symbol penalty calculation, segment encoding logic, bit buffer class, block error correction and interleaving, bitstream formatting

  • base.py: 360 lines for finite field tables, error correction block sizes, polynomial class

  • Code documentation/comments is neglectfully sparse in most places, but main.py has some good comments for the public methods of the QRCode class

  • The version reviewed was b79ab5b3e598, dated 2016-03-15

PyQRCode by Michael Nooner (Python)
  • About 2800 lines of core code in the library

  • builder.py: 900 lines of code for segment encoding, bitstream formatting, ECC generation, module drawing, symbol penalty calculation; 500 lines for export logic to various image formats

  • __init__.py: 620 lines for mostly character encoding logic, some one-liner wrapper methods for exporting images, and long documentation comments

  • tables.py: 750 lines of almost entirely numeric constants

  • Generally speaking the function-level documentation comments are long (and longer than my typical writing), there are comments every 5 or so lines within functions to describe the algorithmic processes (just like I do), but the implementation seems to use a lot of code just to implement basic behaviors

  • The version reviewed was 467f9a2a3c04, dated 2016-02-26

Zint by Ismael Luceno and Robin Stuart (C)
  • About 2400 lines of code among qr.c/h and reedsol.c/h

  • Can encode many types of 1D and 2D barcodes, and includes GUI application

  • Uses heap memory allocation; mutable global variables to store current Reed-Solomon tables (not thread-safe)

  • Low-density logic in code, not much API documentation comments, 100 lines of QR constants

  • The version reviewed was 3432bc9aff31, dated 2013-07-09

libqrencode by Kentaro Fukuchi (C)
  • About 6800(!) lines of core code in the library

  • The most popular C library for QR Code encoding by far

  • Has third-party wrappers for various high-level languages, and numerous patches over the years

  • Uses dynamic memory allocation, unlike my zero-allocation C library

  • Supports even more advanced features absent from my library, such as Micro QR codes and structured append mode

  • Code seems confusing with over 50 public API functions

  • The version reviewed was 1ef82bd29994, dated 2017-03-15

qrcode by kennytm (Rust)
  • About 2800 of core code in the library, when the embedded pieces of test and benchmark code are removed

  • Includes plenty of documentation comments throughout, and at least 200 lines of tables of numbers in ec.rs

  • Apparently supports encoding Micro QR Codes and kanji mode

  • The version reviewed was ba77f8bc2d9b, dated 2017-07-18

More info