Spaces:
Sleeping
Sleeping
|
Download README.md from devmandan/qr-scan-difficulty-check: direct link, hf CLI and curl.
- Browser
- Download file 46.3 kB
-
https://huggingface.co/spaces/devmandan/qr-scan-difficulty-check/resolve/main/README.md
- Command line
-
hf download hf://spaces/devmandan/qr-scan-difficulty-check/README.md
-
curl -L -o README.md https://huggingface.co/spaces/devmandan/qr-scan-difficulty-check/resolve/main/README.md
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. | |