devmandan's picture
Slants and cans, what a phone sees, a test sheet, SVG files and more
378f397 verified
|
Raw History Blame Contribute Delete
46.3 kB
---
title: QR Scan Difficulty Check
emoji: 📷
colorFrom: gray
colorTo: red
sdk: docker
app_port: 7860
pinned: false
disable_embedding: true
license: other
short_description: Where your QR code falls among thousands of measured codes
---
# How hard is your QR code to scan?
Add a picture of your QR code, the file or a photo of it. The page leads with its answer: how wide to print it to scan
from a table, for every picture whose code's version a scanner reported or the checks estimate, then a level (Easy,
Everyday, Tough or Advanced), how confident that level is, and checks on the picture that explain it. Below, as the
evidence, all 6,499 codes [QR Scan Difficulty](https://huggingface.co/spaces/devmandan/qr-scan-difficulty) measured at
seven sizes sit on one scale from easy to hard, shaded by how many of eight scanners read each one at 1280 pixels. Each
picture appears there as a numbered line, and the slider shows a measured code from any spot, with what the eight
scanners did on codes there.
## How a picture is placed
Each picture is read the way every measured code was: turned grey and shrunk, never enlarged, to seven sizes
from 1920 down to 224 pixels on its long side, and read at each size by the five of the eight scanners that run
on a Linux server, with the measurement's versions and settings:
| Scanner | What runs here |
|---|---|
| Android Settings' scanner | [ZXing](https://github.com/zxing/zxing/releases/tag/zxing-3.5.2) 3.5.2, called as Android's Settings app calls it (QR only, inverted retry) |
| WeChat's scanner | [WeChatQRCode](https://docs.opencv.org/4.12.0/d5/d04/classcv_1_1wechat__qrcode_1_1WeChatQRCode.html), OpenCV contrib 4.12.0.88, with its detector and super-resolution models (the app's own build may differ) |
| zxing-cpp | [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp/releases/tag/v3.1.1) 3.1.1, library defaults, QR only |
| OpenCV, newer | [QRCodeDetectorAruco](https://docs.opencv.org/4.12.0/d3/db0/classcv_1_1QRCodeDetectorAruco.html), OpenCV 4.12, single-code `detectAndDecode` |
| OpenCV, original | [QRCodeDetector](https://docs.opencv.org/4.12.0/de/dc3/classcv_1_1QRCodeDetector.html), OpenCV 4.12, single-code `detectAndDecode` |
OpenCV's Python binding can't return a decode whose bytes aren't UTF-8 text (QR's kanji mode, or binary content): it
raises an error instead, whose bytes stop at the first zero byte. So here OpenCV's two detectors then read the frame
with their bytes call, `detectAndDecodeBytes`, which returns them all, and that counts as the read; WeChat's scanner
has no such call, so its bytes are taken from the error. None of the 6,499 measured codes is affected: 2 have contents
that aren't UTF-8, and OpenCV's binding raised on neither. That doesn't make every such code easy: a plain test code
in kanji mode still lands just inside Everyday (at 30.8, just past the cut at 30, with low confidence), since Android
Settings' scanner and OpenCV's original detector each read it at only 2 of the 7 sizes, for reasons not yet known.
Transparent parts count as white, as on a printed page. A scanner reads a picture when it returns the content that
more of the five return than any other, even if only one returns any (the measurement scored each code against its
true content instead); a picture with several codes is placed by that one. A decode that runs past 20 seconds counts
as a miss, as in the measurement, and a picture's reading stops after 40 seconds, so that each request ends within a
minute; reads not done by then count as misses, and the page says so. On a picture where zxing-cpp reads 100 codes or
more at one size, OpenCV's newer detector isn't run at that size or any smaller one, and those reads count as misses
too, as the page says: a single-code detector, it slows sharply as the codes multiply. Over all sizes it took about 2
seconds with 100 codes on a Mac, which would be about 5 on this Space's server (2.44 times the Mac's time), an eighth
of the 40-second limit, but 18 to 34 seconds on the Mac with 225 to 255 codes, past the limit here. No test picture
held 25 to 224 codes, apart from crops made for these timings, so any cut in that range gives the same readings on
them. Every measured picture held one code. Read again on this Space's Linux server, 416 of the measured codes gave
the measured result in all but 7 of their 14,560 reads: on this processor WeChat's scanner and OpenCV's newer detector
come out differently on a few borderline pictures.
The other three scanners, Apple's, Google's and Huawei's (Scan Kit), can't run here: Apple's runs only on Apple
devices, and Google's and Huawei's, as measured, need Android. So a picture is placed from its 35 reads (five
scanners at seven sizes) on the scale all eight set, which stays as measured: the five scanners' reader curves from
the measurement's two-parameter item-response fit are held fixed, and the picture's difficulty is the most likely
one given its reads. On the measured codes, codes that at least two of the five read at 1280 pixels land within
about 4 points of where all eight put them, 9 times in 10, on a 0 to 100 scale where clean prints sit near 19 and
tough prints near 56. Where only one reads it at 1280 pixels, or none does but some do at another size, only about
half land that close. A dashed line means low confidence; a reading cut short by the time limit is always low. A
picture none of the five read at any size goes to the pile on the right, where its place is least sure. Of the
measured codes like that, most are distorted research images; the phones' own scanners still read about 1 in 6 of
them (280 of 1,754, at some size), and 33 of the 59 photos and prints among them (BoofCV's photos, Broken QR 104's
codes from the web, and the simulated everyday and tough prints). In Chrome on a Mac or an Android phone, a design
test can add Apple's or Google's in your own browser (see Testing a design).
The page shows how many of the five read a picture at 1280 pixels, its level and how confident that is, checks on
the picture with advice, and, for its place on the scale, how much of the curve there is codes all eight read at
1280 pixels. The curve is an illustrative mix of the sets, not a count of them: half everyday prints, a fifth each
clean and tough prints, a tenth the research sets. The page never claims what a phone would do with your picture.
## Levels, confidence and checks
Each picture also gets a level from its difficulty d, with the cut points in `web/data/levels.json`, which the
server and the page both read: Easy below 30 (the left pile included), Everyday from 30, Tough from 50 and Advanced
from 60 (the right pile included); a d on a cut goes to the level above. On the curve, the levels line up with the
simulated prints: most clean prints are Easy (184 of 200), most everyday prints Everyday (443 of 600) and most
tough prints Tough (433 of 600).
What a level means depends on the picture's size, because the measured codes come in two kinds: 1,553 pictures over
1280 pixels on the long side, mostly simulated prints with some real photos, and 4,946 smaller ones, mostly
512-pixel research images, which are read 'at 1280 pixels' as they are, never enlarged. So beside your picture the
page describes its level by the measured codes in pictures of the same size class that the five scanners here place
at that level (`meaning` in levels.json), except in the right pile, where it describes the level by the pile's own
codes, both size classes together (`meaning.pile_hi`; only 38 of its 1,754 are over 1280 pixels), since the codes
the five place at Advanced were read far more often by the phones' own scanners than the pile's own: at 1280 pixels
each phone's own scanner read 2 to 8% of the pile's codes, and at least one of them 12%. For pictures over 1280
pixels, at 1280 pixels: at Easy (309 codes) all three phones' own scanners read 98% and Android Settings' 92%; at
Everyday (687) all three 98%, Android Settings' 88%; at Tough (429) each phone's own 94 to 96%, all three together
88%, Android Settings' 44%; at Advanced (128) each phone's own 43 to 69%, at least one of them 78%, Android
Settings' 2%. For smaller pictures: at Easy (1,383) all three over 99%, Android Settings' over 99%; at Everyday
(542) all three 97%, Android Settings' 42%; at Tough (302) each 80 to 92%, all three 65%, Android Settings' 12%; at
Advanced (2,719) each 13 to 31%, at least one 38%, Android Settings' under 1%. The levels list under the curve
describes all measured codes at each level, by all eight scanners' level, counted as they are (not in the curve's
illustrative mix) and named by what they mostly are.
A level's confidence (high, medium or low) measures one thing: how well the five scanners here stand in for all
eight. On the 6,499 measured codes, the level from the five scanners' place matched the level from all eight for
5,832 (90%). A picture takes the share that matched among measured codes with the same evidence: on a pile, the
codes in that pile; otherwise how many of the five read it at 1280 pixels (fewer than two, or more) and how far d
is from the nearest cut (under 2 points, 2 to 4, or more), and, with two or more reads, also the picture's size
class (over 1280 pixels on the long side, or not) and, within 4 points of a cut, the side of the cut d is on. It is
high where at least 90% matched, medium from 70%, and low below. The size class and the side matter because the
eight scanners' d is offset from the five's. For pictures over 1280 pixels with two or more reads, near cuts 30 and
50 it sits about 2 to 3 points higher, so just below those cuts such a picture is often a level harder for all
eight (55% and 20% matched), and just above them 99% matched. Near 60 it is pulled towards the cut from both sides
(1.9 points higher just below it, 1.6 lower just above it, where 5 of 21 matched), so a picture over 1280 pixels
within 4 points of 60 counts as below the cut on either side. For smaller pictures the offset is smaller, and just
above a cut a picture is more often a level easier for all eight (66% matched just above 50, 91% just below). A
reading cut short by the time limit is always low, and one where OpenCV's newer detector wasn't run at some sizes (a
picture with many codes, above) is at most medium, since those decodes count as misses. The right pile is high only
on the condition that the picture holds a code: all 1,754 measured codes there do, and 1,742 of them were Advanced
for all eight too; a picture with no QR code at all lands there as well, so the page always says 'if it holds a
code'. Confidence doesn't cover the photo itself: another photo of the same code can land at another level.
The checks are image measurements made in the decoder worker with NumPy and OpenCV only, on the largest frame read
(at most 1920 pixels on the long side), at the corners of the code that the scanners agreeing on its content found:
camera pixels per square at 1280 pixels (before any tilt, which the angle check covers); size (version, squares
across, pixel width, share of the picture); margin; sharpness; contrast; lighting (shadows and washed-out patches);
and angle. The same picture always gives the same results. Each check is Fine, Borderline or a Problem (`ok`,
`watch` or `problem` in `/api/measure`) by [QR Scan
Difficulty](https://huggingface.co/spaces/devmandan/qr-scan-difficulty)'s factor tests (the `ladders` in its
`site.json`: one code all eight scanners read, changed one thing at a time, 80 synthetic codes a step, read at 1280
pixels), counting a scanner as reading a step when it reads at least 9 in 10 of its codes, as that Space does: Fine
where all eight read the step, Borderline where the phones' own scanners did but another didn't, and a Problem
where one of the phones' own didn't. Each limit sits halfway between the check's median values on the last step
with one status and the first step with the next, measured as the Space measures a visitor's picture; where two
tests set one limit (focus and shake for sharpness), it sits in the middle of the range both allow. Pixels per square
takes its limits from the grid behind the print widths instead (below), in its good-light scene, where the factor tests
start (tilt 5°, focus blur 0.3 pixels, 73% contrast), by the same rule, versions that change status between the same two
steps sharing one limit: Fine from 4.45 camera pixels per square, since all eight read 9 in 10 from 5 at versions 2 to
10, and a Problem below 1.90 at versions 1 to 4, 2.14 at 5 to 8, 2.43 at 9 to 13, 2.77 at 14 and 15, and 3.20 from 16
(`pixel_check` in `web/data/sizes.json`). A version between two measured ones takes the next one up, as the widths do.
Above version 10, OpenCV's original detector or Android Settings' scanner read fewer than 72 of 80 even at 6 pixels per
square, the most measured: the version holds them back, not the pixels, so Fine stays at 4.45 there, and from version 14
the size check says so. The grid's pictures weren't kept, so the check's values on them are worked out from each test
code's true corners, which give the Space's own medians on the factor tests to within 0.01. The margin is Fine from the
4 squares the QR standard asks for, Borderline below that, and a Problem with next to none (under a quarter square),
though all eight still read the margin test's codes with half a square; for small or blurred codes the margin may only
be known to be under a bound, and the page says so. A mark at the code's edge that doesn't reach a quarter square past
it, with no clear line between them, such as a design's art crossing it, counts as the code's edge, not its margin; a
mark beyond a clear line, however thin, ends the margin. Under 4 pixels per square, where the check places the code's
edge only to within about a pixel, a margin the picture's edge ends from 3.5 squares out counts as 4 (`capped` in the
margin's check), so a real 3.5-square margin there reads as a Fine 4. A code filling 30% or more of the picture's long
side, more than any simulated print, gets a framing note, not a status: a close view or a tight crop gives each square
more camera pixels than a photo from where people stand. A picture up to 1280 pixels is read at its own size, never
enlarged, so, unless it is Easy, it gets a note that a full-size original can land at an easier level. The checks are
diagnostics only: they never change d, the level or the confidence, and the five scanners' reads are unchanged.
The page lets you say what each picture shows: not sure (the default), the original graphic, a printed code or a
code on a screen. The choice stays in your browser, except that marking a picture as the original graphic can start a
design test, which sends the picture again (see Privacy). A new picture takes the last one only when it was a printed
code or a code on a screen, except an SVG, which starts at not sure. The choice picks what is shown first, and the
advice: for the original graphic, how wide to print the picture itself, with the file's reading as a picture behind "+".
It never changes the level, its confidence or the checks. A file whose own details check out is marked as the original
graphic by itself, unless you have already chosen what it shows.
For the original graphic, the page also gives the code's facts as made: its version as a scanner reported it, its
error correction from zxing-cpp's read, and its margin from the margin check ("As made: version 8 at error correction
L, with at least a 4-square margin."). The margin is stated only where that check measured the code at 4 pixels per
square or more (`margin_min_ppm` in `web/data/sizes.json`, which must stay at or above `QZ_EDGE_PPM` in
`server/quality_fit.py`, the 4 pixels per square below which a margin can be capped), and never a capped one: on plain
files with margins of 0, 1 and 4 squares, ending at the file's edge, it read every margin exactly at 4 and 8 pixels
per square, and all but 4 of 4,968 from 2 to 3.5, where a 1-square margin can read 0.75; but on files enlarged without
smoothing (nearest-neighbour) to under 4 pixels per square, margins of 2 to 3.5 squares often read a quarter square
short (254 of 576 tested). Then comes how much of its error correction the code already uses, from zxing-cpp: none, a
share of it, all of it, or that it can't be judged; a file wider than the largest frame read (at most 1920 pixels on
the long side), whose code was read shrunk too small to judge though its own pixels would do, is told that a crop of
it holding the code and its margin can be judged. When the page holds the whole content, it also says when that
content fits a smaller version at the same error correction, and how wide that version needs printing at least; not
once a printed width is typed, since that answer is a distance, nor for a code that uses some of its error correction,
since its styling on a smaller version would be another design, which nothing has tested. The smaller version comes
from the QR standard's capacity tables (ISO/IEC 18004, in `web/data/capacity.json`), counting the whole content in one
mode, with room for GS1's FNC1 marker, and for each % twice in alphanumeric mode, as FNC1 mode writes it, so it is
never smaller than the smallest version that holds the content. One gap: a code whose bytes are in a character set
other than UTF-8, named in an ECI header, but happen to be valid UTF-8 too, is counted as the text they make in UTF-8,
so the page can name too small a version; that is rare, and nothing in the reading tells the two apart. Behind "+",
shown only when zxing-cpp gave the mask or the share of error correction left unused, are the squares across, the
mask, that share with the frame zxing-cpp read it on and when it is judged, and where a smaller version comes from.
A PNG file can also say how it was made, in a text chunk keyed `qr-made` that a code generator writes: the squares it
meant, the error correction it used, the kind of art it drew and a hash of its picture data. Your browser reads it and
checks its hash against the file's own picture data, then every claim it can against the reading: the version, error
correction, mask, content, pixels per square, position, margin and squares. One mismatch, and the whole record is
ignored, with one line saying why. A record that checks out can mark the file as the original graphic, so the page gives
the picture's own width, explains its art in words and compares the squares meant with the squares zxing-cpp read; every
number still comes from the reading. It is removed before the picture is sent, so the server's answer is the same with
or without it.
## How wide to print it
Every picture whose version a scanner reported, or the checks estimate, also gets the smallest width to print its
code to scan from a table, 40 cm away; in hand (20 cm), a wall (1 m), across a room (3 m) or a distance you type are
one step away. Marked as the original graphic, a code file or a design gets the width to print the picture itself,
from its code's share of the picture's width, and given the width it will print at, the answer becomes how far its
code scans from. Where a picture repeats one code, each width is for one copy, and the page says how many copies
zxing-cpp read. It is arithmetic in your browser: code width = squares across × need × distance ÷ 960.
- Squares across: 17 + 4 × the version a scanner reported, or, where no scanner reported one, the version the checks
estimate from the code's own patterns, which the answer says. Without either, or where the checks' estimate
overrides the version zxing-cpp decoded, the page says the width can't be planned.
- Need: the camera pixels per square from which Apple's, Google's and Huawei's scanners each read at least 72 of 80
codes at every larger step, in a quick everyday scan (tilt 15°, focus blur 0.7 pixels, a 2-pixel shake, 61%
contrast, uneven light, JPEG quality 82), measured on 30 October 2026 on a grid of versions 2 to 21 at 1.6 to 6
pixels per square, read at 1280 pixels: 2.6 at versions 2 and 4, 3.0 at 6 and 8, 3.5 at 10, 4.0 at 13 and 15, and
5.0 at 18 and 21. At 18 and 21 it is Apple's and Google's alone, because Huawei's doesn't hold 72 of 80 at every
larger step there (at version 18 it read 72, 76 and 69 of 80 at 4, 5 and 6 pixels per square; at 21, 56, 70 and
63), and the page says how often it missed. A version between measured ones takes the next one up,
version 1 takes version 2's, and versions 22 to 40, not measured, take version 21's as a floor.
- 960: an assumption, untested on real phones. A phone's main camera (24–26 mm equivalent) sees a patch about as
wide as its distance, in portrait, and its scanner gets it as a 1280 × 960 picture.
Code widths are rounded half up, to the millimetre under 20 cm and to the centimetre from 20 cm; a picture's width is
rounded up, so printing at it never makes the code smaller than its need; distances worked out are rounded down (the
nearest distance behind "+" is rounded up, as a least distance), and a distance you type is shown as typed, in cm. A
printed width whose code would scan only from closer than 10 cm is called too small instead. A width is an estimate
for a plain code: never a level, and never a promise that a phone will scan it. The needs, the camera and the
distances are in `web/data/sizes.json`.
At a slant, or on a can or bottle (one step away in "Your picture"), the width grows so that the squares the phone sees
narrowest keep the need, by perspective with the same camera, facing the code's middle. Turned more than 15°, the quick
everyday scan's own tilt, the code's far side keeps the camera pixels per square it gets turned 15°: at 45°, that asks
about 1.05 times what the cosine of the angle alone would at version 2, 1.3 times at version 13 and 2 times at
version 21. On a can or bottle of a given diameter, the code's edge squares keep the need. No width is given turned past
55°, for a code wider than the diameter over 1.2 (a radius under 0.6 code widths), or where the code and its margin,
turned, would no longer fit the camera's view. Those are the limits of the factor tests (version 3 codes at 8 camera
pixels per square): Apple's, Google's and Huawei's scanners each read at least 72 of 80 test codes turned up to 55° and
wrapped down to 0.6 code widths, while Apple's read 49 at 60° and 69 at 0.55. The test codes were wrapped as seen from
afar and straight on, so a can or bottle held close, or seen from above or below, may be harder.
Behind "+", What a phone sees draws your picture as a phone's scanner would get it, printed at the width worked out and
seen from its distance. Your browser resamples it so each square gets the camera pixels that width gives it (code width
× 960 ÷ distance ÷ squares across), each camera pixel the mean of the picture it covers, in grey and enlarged. At its
need a code looks the same from any distance, since its width grows with the distance. It is an illustration, not a
scan: it leaves out the tilt, blur, shake, contrast and light of a quick everyday scan that the needs were measured
with, its camera is the assumption above, and no scanner reads it. It isn't drawn for a code turned more than 15° or on
a can or bottle, which it can't show.
A test sheet, `web/sheet.html`, opens in a tab of its own from the end of "How this is worked out". It holds five plain
version 4 codes at error correction M, 7.2, 5.1, 3.6, 2.5 and 1.8 cm wide: the width planned for a table and steps of
the square root of 2 to twice and half of it, half being the width planned in hand. Printed at 100% and scanned from 40
cm, it can show that your own phone needs more than the 960-pixel camera the widths assume: if it needs a bigger code
than the one planned for a table, print your codes at least that much wider, since a quick everyday scan asks for more
than this careful one. A bar on it, 10 cm along one edge and 4 inches along the other, shows whether it printed true.
Each code holds a line of plain text naming its width, not a web address, so scanning one sends nothing to this Space.
The page draws the codes in your browser from `web/data/sheet.json`, written with zxing-cpp's encoder from the needs in
`web/data/sizes.json`.
Every width and distance worked out is also given in inches, beside its metric figure, from the same length and
rounded the same way: widths to the eighth of an inch under 10 inches and to the whole inch from 10, distances in
whole inches under 1 m and in feet and inches from 1 m, rounded down like the four distances themselves (a table, 40
cm, is 15 in), and up for a least distance (the 10 cm a code too small falls short of is 4 in); a margin's inch figure
is rounded up, as a least clear space, while its metric figure rounds half up, as a code's width does, so it can be a
little under; and where the answer gives the picture's width, its code's inch figure comes from that width in inches.
The exact distance you type stays in cm. A printed width can be typed in inches, as a decimal or a fraction ("1 1/4",
"1-1/4", "5/4" or "9/16"), with or without "in" or an inch mark after it.
`/api/measure` keeps every earlier field and adds `rating` (`level`, `confidence`, `agree` and `n` for the measured
codes behind it, `why` naming its main reason, and `big` for the size class) and `checks` (null when nothing could be
measured, and for a reading cut short, which the checks never measure). It also adds zxing-cpp's unused error
correction, `uec` (1.0 when none was needed, down to 0.0), and its other facts about the code, all from one frame: the
largest in which it read the content with that figure (`uec_frame`, that frame's largest size). There, each of its
reads of the content has a figure; when a read whose code has under 3 pixels per square there reads under 1.0,
zxing-cpp reads that frame again, once, if the time limit hasn't passed, with its GlobalHistogram binarizer, and its
read in the same place stands for that read when its figure is higher, since a small, lossy JPEG of a plain code can
read under 1.0 with its default binarizer alone. From 3 pixels per square up the default binarizer's figure stands,
art and all: plain code files enlarged without smoothing (nearest-neighbour or area resampling), and JPEG and WebP
copies of them, read with all of it unused from about 2.5 pixels per square, while a plain code resampled with
smoothing, or photographed, can read some as used at any size. `uec` is the lowest figure over its reads of the
content there, another code of the same content included: where a picture repeats a code, the copy that uses the most
error correction sets it. The other facts come from one read, zxing-cpp's last read of the content with a figure
there, or that read's second look when it stands; where a picture repeats a code, that read is of the copy the checks
measure. They are `ec_level` (L, M, Q or H) and `mask` (0 to 7), from the code's format bits; `squares`, the squares
as zxing-cpp sampled them before error correction (1 for dark, row by row, 8 to a byte from the high bit, the last
byte filled with zeros, in base64; a turned or light-on-dark code's squares come back upright and as meant, a mirrored
code's transposed); `raw_sha256` and `raw_bytes`, the SHA-256 and the count of the bytes zxing-cpp read; and `copies`,
how many copies of that code it read there: its reads of the content with the same error correction and mask and,
where both have corners, the same squares across and a size within 10% (zxing-cpp returned at most 255 codes from one
picture in tests). Where zxing-cpp read the content two or more times in the first frame it read it in, none of these
facts from that frame, nor the checks, use a read it made in its own smaller copies of the frame (a third the size, and
a third of that while that copy is over 500 pixels on its longer side, which it reads only while it has fewer than 255
codes), whose corners are coarse and whose squares were sampled at a third of the frame's resolution or less: it reads
the frame again at its own size alone (unless the reading has run out of time, or that look fails), and only the reads
that look repeats count, unless it repeats none. All of these are
null when zxing-cpp never read the content with that figure, and for a reading cut short. `not_run` lists the decodes
the many-codes rule left out, as {scanner: [frame sizes]}, empty when none. And it adds `content.sha256`, the content's
digest, taken from its raw bytes so that pictures of one code match whichever scanners read them, and `content.sha256s`,
the digests of every set of raw bytes the content can stand for: one, or two for a non-ASCII text whose characters fit
both ISO-8859-1 and Shift JIS (such as "25°C"), which either can encode.
The page pairs your pictures by those digests (two pictures are of one content when they share one), in your
browser: a later picture names the earliest one with the same content, and a photo compares with the original
graphic of its code, by margin, contrast and camera pixels per square; two files also compare the error correction
they use.
A file whose code already uses some of its error correction, as a logo or art over its squares does, is flagged as
maybe needing printing wider, and one that uses all of it as likely needing printing wider than a plain code. That is
judged only where its code had at least 2 pixels per square in the frame read (3 for version 1, whose plain codes
read some as used at about 2.4), since plain code files enlarged without smoothing read with all of it unused from
about there. The flag never changes the width.
## Testing a design
For a picture marked as the original graphic, the page also tests the design, by itself and with nothing to press.
Once the choice has stood for a second, so that arrowing past it with the keyboard starts nothing, the page sends the
picture again, and this server scans it beside a plain code with the same content, version, error correction and mask.
The answer, under the code's facts as made, says whether the scanners it names read the design as well as that plain
code or worse, or that the test couldn't tell, with a next step. A page tests its pictures one at a time, in the order
they were marked, and this server runs one test at a time for all its visitors, in a low-priority worker of its own
that never takes a reading's place; a page told to wait keeps its turn. The test is a comparison in simulation, at the
need the width is worked out from: it isn't a phone's camera, and it never replaces scanning a test print with a few
phones. Its settings, the figures it shows and the source of each are in `web/data/test.json`, which the page and the
server both read.
A test runs only where the page plans the width from the version a scanner reported, not from the checks' estimate.
Then, where it can't run, one line says why, with a next step: for a code whose error correction and mask zxing-cpp
didn't read; over version 21, the last version the needs were measured at (`max_version`); under 2 pixels per square
in the file, or 3 for version 1 (`min_ppm` and `min_ppm_v1`, the same floor as the error correction flag above); over
16 megapixels, the page's own conversion cap (`max_pixels`); for a light-on-dark code, since the test compares a
design with a dark-on-light plain code; for a mirrored code; for a picture that holds more than one code (copies of
one code are fine: the test takes the copy nearest the picture's centre); and where the plain code can't be made. The
server checks all of these itself. The page then checks that the server read the code as the first reading did, with
the same version, error correction, mask and raw bytes; if not, one line says the test read it differently.
The design and its plain code are printed and photographed in the same 20 simulated everyday scenes: the quick
everyday scan the widths are worked out for, with each square at the need for the code's version, and at that width
only (a version between measured ones takes the next one up, and version 1 takes version 2's). The scenes are fixed,
seeds 0 to 19 of the scene streams the needs were measured with, so the same picture always gets the same scenes, and
the same answer from this server. The design prints with up to 6 squares of it round its code, each file pixel a solid
square, and beyond its own edge comes the scene, so a small margin counts against it; the plain code has a 4-square
margin. Each capture is a 1920 × 1440 grey JPEG at quality 82, shrunk to the 1280 × 960 grey frame every scanner reads
by a whole-number rule equal to OpenCV's INTER_AREA at that size, so the same decoded JPEG gives the same frame on any
processor. zxing-cpp and WeChat's scanner read every frame on this server, with the reading's own decoders, and a read
counts only when it gives the code's content.
Each scanner is judged on its own, scene by scene, over the 20 paired scenes. It read the design worse when it missed
the design where it read the plain code too often to put down to chance: a one-sided exact sign test under 0.05 (a
definition), which takes at least 5 such scenes with none the other way round, or more when there are some. It read it
as well as a plain code when that happened at most 2 more times than the other way round (the study below flagged a
difference of 3 or more), and it read the plain code, or the design, in at least 16 scenes (a named choice, for the
test's power). Otherwise the test can't tell: the loss is too small to be sure of, or too few scenes were read. The
answer is worse when any scanner read the design worse, naming those that did; as well as a plain code only when every
scanner did, naming them all; and otherwise that the test couldn't tell, naming those that couldn't. The page judges
its own scanner by the same rule (`rule`).
In Google Chrome on a Mac, or on an Android phone with Google Play, Apple's or Google's scanner can join the test in
your own browser: Chrome takes its scanner from macOS on a Mac and from Google Play on Android. Other browsers, and
Chrome elsewhere, get zxing-cpp's and WeChat's answer: their detectors are missing or unmeasured. The page finds out
once, sending nothing, when a picture is first marked as the original graphic: whether the browser is Google Chrome on
macOS or Android, and whether its detector lists QR codes; then, with two small pictures in test.json (the working
check), whether its canvas gives a plain code's exact pixels and its detector reads that code, and whether it decodes
a grey JPEG exactly as this server does. If its detector fails that check, the page runs the check again when the
next test starts.
The browser's scanner joins a page's tests by itself until it has done so in 3 tests (`join`), usually about 24 MB in
all; later tests offer it with one tap, and Try again keeps it in a test it was to join. While its part runs, "Leave
it out" ends it at once. A browser that asks to save data leaves it out, and Chrome on Android leaves it out of a code
whose raw bytes aren't its text in UTF-8 (the text zxing-cpp reads), such as text in Latin-1 or Shift JIS, since
Chrome 113 on the Android emulator failed on every such code in tests. After "as well as" or "can't tell", a second
line names the phone's scanner that wasn't in the test and where to get its answer, or says why your browser's own
didn't take part.
For each scene, the page fetches its facts (the box where the plain code's frame differs from the design's, and both
frames' SHA-256), then the design's capture JPEG and the plain code's patch, its frame inside that box as a grey PNG.
It decodes the JPEG with your browser's own decoder, shrinks it by the same whole-number rule, pastes the patch over a
copy for the plain code's frame, and reads a frame only once its SHA-256 equals the server's: so it reads exactly the
frames this server's scanners read, byte for byte. A frame that fails its check comes again as a whole PNG frame, and
from then on the design's frames come as PNG, the plain code's still as patches; a browser whose working check decodes
the JPEG differently takes them that way from the start. A test usually downloads about 8 MB. While a test with your
browser's scanner waits and runs, the page says about how much it downloads: 9 MB up to version 10 and 16 MB above
with JPEG frames, or 16 and 23 MB with PNG frames, the most measured for each range, rounded up, with room in the PNG
figures for two scenes' JPEGs fetched before a switch (`mb`).
Your browser's part stops fetching once no reads of the scenes left could change its answer. It also has 45 seconds of
fetching the scenes' pictures, from the test's start: after 2 scenes, and after each one from then on, it projects how
long all 20 would take at the link's own pace, and stops when that comes to more than 45 seconds (`budget`). That
holds down to about 2 Mbit/s up to version 10, and 3 Mbit/s at version 21. Time spent waiting for the server, or
frozen in the background, doesn't count. When your browser's part stops before its answer, by the budget, a failure or
Leave it out, the test still finishes with zxing-cpp's and WeChat's answers, and after "as well as" or "can't tell"
the second line says why.
Besides the picture, the server learns only what the test's own requests show: that the picture was marked as the
original graphic; whether your browser's scanner joins, with JPEG or PNG frames, which says whether your browser
decodes JPEG as the server does; which scenes and frames it fetches; and where its part ended, which the page's polls
then say: an early end can hint at its answer. What its scanner read is never sent: it stays in the page, and the
scans are never shown. Nothing about a test is logged or stored: the picture goes to a temporary file that is deleted
once the test is set up, and its scenes stay in memory only until the page needs no more, or a minute after its last
request. Of the server's two scanners, the test's routes under `/api/design` give only their answers, never their
reads or read counts.
Behind "How this was tested +", each answer gives its method, its rule, each scanner's own answer (never its reads)
and the figures' scope, and, where they apply, the Chrome build measured, what a study found for its path, what 20
scenes can't show, and that your browser's reads stayed in the page. The study tested 163 files from one code
generator, each beside a plain code with the same content, in the same 20 scenes at two widths: 13,040 simulated
captures. Its figures here are for the 125 distinct styled designs among them that are dark on light, in four styles
at versions 3 to 8, at the width the test uses (`figures`). zxing-cpp and WeChat's scanner can warn, but can't clear
a design for phones: of the 53 designs they read as well as a plain code, Apple's or Google's scanner read 14 worse
and couldn't tell for 11 more, and of the 69 they read worse, Apple's or Google's read 64 worse too. With Apple's
scanner in the test, Google's read 1 of the 32 that passed worse and couldn't tell for 3 more; with Google's, Apple's
read 2 of the 38 worse and couldn't tell for 8. No test has both phones' scanners, so no answer speaks for phones in
general.
Chrome's scanner is the platform's own on the builds measured: Chrome 157 on macOS 14.3.1 read all 13,040 captures
exactly as Apple's scanner did on its own, and Chrome 113 on Google's Android 14 emulator with Google Play read all
3,200 captures of a 40-design sample exactly as Google's did. Other versions may read differently, but the same
scanner reads the plain code in every scene, so the two still compare.
The 20 scenes show big differences, not small ones. Losing none of them rules out only a loss above 13.9% of scans
(one-sided, at 95%), and if the plain code read every scene, a design that misses 3 in 10 of the scans a plain code
reads still gets "as well as a plain code" about 1 time in 30, and one that misses 1 in 10, about 2 times in 3 (the
binomial chance: 3.5% and 67.7%). The study's figures come from one generator's designs in one kind of scene, and in
that set each style came at its own versions and error correction, so their effects can't be told apart. And the scans
are simulated stills of a print, read without a phone's camera or app. The study's captures were made on a Mac, and this
server makes the same scenes on its own processor: for 38 of the study's designs, 1,211 of their 1,520 frames came out
different in some pixels. zxing-cpp, WeChat's scanner and Apple's still gave the study's answer for all 38, and Google's
for 35; for the other 3 it moved to can't tell.
## Privacy
A picture is written to a temporary file, read, and deleted as soon as the reading ends. Nothing is stored, and
this server keeps no access log. The decoded content is sent back to your browser only, so you can see which code
was read. If a file says how it was made, your browser reads that and removes it before the picture is sent. Your
browser also removes the other details a file carries before it is sent: where and when a photo was taken, the phone or
camera and its settings, comments, thumbnails, and any other pictures or data stored with it. It keeps only what the
reading needs: the picture itself, how its colours and transparency are stored, and which way up a JPEG or PNG photo
goes, since the server turns the picture that way before reading it. A file your browser can't take apart this way is
converted first, as other formats are (see Limits). Hugging Face, which hosts the Space, has its own [privacy
policy](https://huggingface.co/privacy). What you say a picture shows stays in your browser, with one exception: marking
a picture as the original graphic can start a design test, which sends the picture again (see below). An SVG is drawn in
your browser and only the drawing is sent, as PNG: its text, links and other details stay in your browser. The distance,
width, slant and diameter you give stay in the page: they are never saved or sent. What a phone sees is drawn in your
browser from the picture you added: nothing more is sent. The test sheet is drawn in your browser from the same files
for everyone, and its codes hold plain text, not a web address: scanning one sends nothing to this Space.
Marking a picture as the original graphic, which the page can also do by itself for a file whose details check out, can
start a design test: it sends the picture again, so the server can tell it was marked. When your browser has a scanner
the test can use and it joins in, the page also fetches the test's simulated scans from this server, usually about 8 MB
and at most about 23 MB each time a test runs, and rebuilds and reads them in your browser. The server sees which scans
your browser fetches and when it stops, never what its scanner read, and the scans are never shown. Nothing is stored.
## Limits
Up to 25 MB and 50 megapixels a picture, and 40 at a time; the page sends them one by one, and each must arrive
within a minute. JPEG, PNG and WebP are read as sent, without their details (see Privacy). Other formats your browser
can open (such as GIF, AVIF, or HEIC in Safari) are converted by your browser first, as it shows them: transparent parts
on white, at most 16 megapixels, as PNG, or as a high-quality JPEG when the PNG would be over 25 MB. So is a JPEG, PNG
or WebP file whose structure your browser can't follow, which is rare. An SVG is drawn by your browser at 1920 pixels on
its long side, the largest size pictures are read at, with transparent parts on white, and sent as PNG; one that uses
other files, holds web content or has no size isn't drawn, nor is one with its own dark-mode colours while your browser
is in dark mode: export a PNG instead. The server reads two pictures at once and keeps up to 16 more waiting; one that
would wait longer than 10 seconds is turned away with a request to try again in a minute. A design test never takes a
reading's place, but it shares the processor: in a load test on this Space, readings took about 1.5 times as long at the
median while a test ran with both reading slots busy, and their usual time with one reading at a time. On Hugging Face's
free hardware the Space sleeps when nobody has used it for a while, and the first visit after that wakes it up.
## Credits
- Scanners: ZXing (Apache-2.0), zxing-cpp (Apache-2.0), OpenCV and opencv_contrib (Apache-2.0), WeChat's QR
models (© THL A29 Limited, a Tencent company; Apache-2.0) from WeChatCV's
[opencv_3rdparty](https://github.com/WeChatCV/opencv_3rdparty/tree/3487ef7cde71d93c6a01bb0b84aa0f22c6128f6b),
fetched at build time with their licence and checked against pinned SHA-256 sums.
- Server: Starlette and Uvicorn (BSD-3-Clause), NumPy (BSD-3-Clause); Java: OpenJDK 17 (GPL-2.0 with the
Classpath Exception). Libraries bundled in these packages keep their own licences.
- Codes on the curve: made for the measurement
([QR Scan Difficulty: synthetic codes](https://huggingface.co/datasets/devmandan/qr-scan-difficulty), CC BY 4.0), and
from research datasets, each under its own terms:
[BoofCV QR singles](https://huggingface.co/datasets/devmandan/boofcv-qr-singles) (Peter Abeles' BoofCV QR
Code Performance Benchmark photos, published openly without an explicit licence grant),
[QR-DN1.0](https://huggingface.co/datasets/devmandan/qr-dn1.0) (CC BY 4.0, Mendeley Data,
doi:10.17632/t2bdr663ms.2),
[syn10k](https://huggingface.co/datasets/devmandan/syn10k-huawei-barcodes) (Bodnár, Grósz and Tóth; CC BY 4.0)
and [Broken QR 104](https://huggingface.co/datasets/devmandan/broken-qr-codes-104) (annotations CC BY 4.0).
Pictures are cropped and resized from their datasets; to have one removed, open a discussion on its dataset page.
## Disclosures
Independent work, not affiliated with or endorsed by Apple, Google, Huawei, Tencent or DENSO WAVE, nor by the
open-source projects and dataset authors credited above. QR Code is a registered trademark of DENSO WAVE
INCORPORATED. Apple and iPhone are trademarks of Apple Inc.; Android and Google Play of Google LLC;
Huawei of Huawei Technologies Co., Ltd.; WeChat of Tencent. Other names are trademarks of their owners.