QR code generator

Four decisions hide inside every QR code

Paste some text into a QR generator and a black-and-white square comes out. What you are not shown is that the encoder just made four separate choices on your behalf, each of which changes the result, and any of which it could have made differently.

This tool shows all four, because they are the interesting part. Once you can see them, the behaviour that seems arbitrary — the code jumping a size when you add one character, a logo working on one code and not the next — stops being arbitrary.

• The mode split: the standard defines four ways of packing characters, and your text is divided between them.
• The version: a number from 1 to 40 that fixes the grid at 21×21 up to 177×177 modules.
• The error-correction level: L, M, Q or H, which decides how much of the symbol can be destroyed and still read.
• The mask: one of eight patterns XORed over the data to break up shapes that confuse a scanner.

None of the four is a preference. Each has a right answer given the others, which is exactly why they are worth watching: they interact.

Splitting the text is a shortest-path problem

Numeric mode spends 10 bits on every three digits. Alphanumeric mode spends 11 bits on every two characters, from a set of 45: the digits, the capital letters, the space, and nine punctuation marks. Byte mode spends 8 bits per UTF-8 byte. Kanji mode spends 13 bits on a character that byte mode would spend 24 on.

So the cheapest encoding is rarely one mode for the whole string — but switching is not free either, since every segment pays for a 4-bit mode indicator and a character-count field. Whether a run of digits is worth breaking out depends on how long it is. That makes the split a shortest-path problem, and this encoder solves it exactly rather than guessing with a rule of thumb.

HELLO12345678901234567890

as one alphanumeric segment
  4 + 9 + (11 x 12) + 6 = 151 bits

split at the digits
  4 + 9  + (11 x 2) + 6 =  41 bits
  4 + 10 + (10 x 6) + 7 =  81 bits
  total                 = 122 bits

Twenty-nine bits, which at version 1 is the difference between fitting and not. The segments table on the page shows the split the encoder actually chose and what each segment cost, so you can see which characters are expensive.

The version and the split chase each other

Here is the wrinkle that makes a naive encoder wrong. The character-count field is not a fixed width. It is 8 bits for byte mode in versions 1 to 9, and 16 bits from version 10 up; numeric goes 10, 12, 14 across the same boundaries.

That means the cost of a split depends on the version, and the version depends on the cost of the split. The way out is to notice there are only three groups of versions, so the split is computed once for each group and the smallest version that fits any of them wins.

• Versions 1–9: numeric 10 bits, alphanumeric 9, byte 8, kanji 8.
• Versions 10–26: numeric 12, alphanumeric 11, byte 16, kanji 10.
• Versions 27–40: numeric 14, alphanumeric 13, byte 16, kanji 12.

The mask is chosen by four penalty rules

Data in a QR code is close to random, and random black and white produces shapes that a scanner can mistake for the structural patterns it is looking for. The remedy is to XOR the data area with a regular pattern chosen to break those shapes up. There are eight, and the encoder tries all of them.

Each masked symbol is scored by four rules from the standard, and the lowest total wins. The table on the page shows all eight scores broken down by rule, and clicking a row forces that mask so you can see the effect.

• Runs: three points for five adjacent modules of one colour in a row or column, plus one for every module beyond.
• Blocks: three points for every 2×2 area of a single colour.
• Finder-like: forty points for the 1:1:3:1:1 dark-light-dark-light-dark sequence next to four light modules — the pattern that looks like the corner squares.
• Balance: ten points for every whole 5% the share of dark modules sits away from a half.

Implementations disagree slightly here — on whether the 1:1:3:1:1 pattern counts at larger scales, and on whether the format information is included in the score. This encoder follows the reading used by ZXing, which is what most phone cameras run, and it is pinned against two independent implementations. The disagreement never produces an invalid code; it only decides which of several perfectly readable masks is picked.

What a logo in the middle really costs

Everyone repeats the same rule: level H recovers 30%, so you can cover up to 30% of the code. It is the wrong shape of answer, and following it will eventually hand you a code that does not scan.

Error correction in a QR code is not one pool. The data is split into Reed–Solomon blocks, each with its own correction codewords, and the blocks are interleaved across the whole grid so that a scratch damages several a little rather than one a lot. Each block can lose roughly half its correction codewords and still be rebuilt. A logo in the middle is a solid square, which is precisely the shape interleaving was designed to spread — but it never spreads evenly.

So the question is not what share of the symbol is covered. It is how much the worst-hit block lost. This page knows which codeword every module belongs to and which block every codeword came from, so it can answer that directly: upload a logo and it reports the damage per block and the room the worst one has left.

• Covering a finder pattern, a timing pattern or the format information is not a matter of budget — those carry no error correction, and a scanner that cannot find them never gets as far as correcting anything.
• The half-the-codewords figure is an upper bound. Printing, glare, curved surfaces and wear spend some of the same budget, so a code that is exactly at the limit on screen is not at the limit on a mug.
• Raising the level to H to fit a bigger logo makes the symbol larger, which makes each module smaller at the same printed size — sometimes a loss rather than a gain.

The payload formats, and where they bite

A Wi-Fi QR code or a contact card is just text in a shape scanners recognise. The shapes are simple; the escaping rules are where real codes break, and they are silent failures — the code scans perfectly and gives the wrong answer.

WIFI:T:WPA;S:Cafe\; Bar;P:p\:ssw\,rd;;

BEGIN:VCARD
VERSION:3.0
N:Lovelace;Ada;;;
FN:Ada Lovelace
ORG:Analytical Engines\, Ltd
END:VCARD

In the Wi-Fi format a semicolon ends a field, so a password containing one truncates the credential unless it is escaped — as do a comma, a colon, a quote and a backslash. A network name made only of hexadecimal digits has to be wrapped in quotes, or it is read as hex rather than as text. In vCard the separators are the semicolon and the comma, a line over 75 octets has to be folded onto a continuation line beginning with a space, and the line ending is CRLF.

The builders here apply all of that and say what they did, rather than rewriting your input quietly. If a finding appears under the fields, something in your text needed handling — which is usually worth knowing before you print a thousand stickers.