readme

Author: paulmillr

README.md

@@ -3,11 +3,11 @@
 Minimal 0-dependency QR code generator & reader.
 
 - 🔒 Auditable, 0-dependency
-- 🏎 [Fast](#speed): aims to be faster than all JS implementations
-- 🔍 Reliable: 100MB+ of extensive test vectors ensure correctness
+- 🏎 [Fast](#speed): faster than all JS implementations, faster than native zxing-cpp
+- 🔍 Reliable: decodes 63-69% of BoofCV photo vectors; compared to zxing-cpp 50-75% (for fast-slow modes)
 - 🏞️ Encoding (generating) supports ASCII, term, gif, svg and png codes
 - 📷 Decoding (reading) supports camera feed input, files and non-browser environments
-- 🪶 18KB (gzipped) for encoding + decoding, 9KB for encoding
+- 🪶 26KB (gzipped) for encoding + decoding, 10KB for encoding
 
 Check out:
 
@@ -163,8 +163,10 @@ type DecodeGrid = {
 type DecodeOpts = {
   cropToSquare?: boolean;
   grid?: DecodeGrid; // trusted centered, axis-aligned grid geometry
-  moreEffort?: boolean;
-  textDecoder?: (bytes: Uint8Array) => string;
+  // default true: invert / downscale retries, downscale-first detection.
+  // 'max' adds slow rotation / crop / upscale fallbacks; false = single pass
+  multiPass?: boolean | 'max';
+  textDecoder?: (bytes: Uint8Array, eci?: number) => string;
   pointsOnDetect?: (points: FinderPoints) => void;
   imageOnBitmap?: (img: Image) => void;
   imageOnDetect?: (img: Image) => void;
@@ -175,6 +177,22 @@ declare function decodeQR(img: Image | Bitmap, opts?: DecodeOpts): string;
 
 A `Bitmap` input must contain the exact borderless QR module matrix. For a rendered image whose integer module geometry is already known, `grid` skips photographic binarization and finder detection. Centered generated grids are also recognized automatically when their quiet zone and finder patterns validate.
 
+`multiPass` controls how much work the decoder may spend on one image:
+
+- `true` (default) — adaptive multi-pass detection. Large frames are detected
+  on a box-downscaled raster first (full resolution stays as the fallback);
+  failed decodes are retried with inverted colors (light-on-dark codes,
+  screens) and on 2x..32x downscaled rasters (codes overflowing the frame,
+  screen moire). Extra passes only run after the primary pass fails, so
+  images that already decode pay nothing.
+- `'max'` — additionally tries rotated, cropped, and upscaled fallback
+  candidates. Decodes noticeably more hard photos, but can be several times
+  slower on images that still fail. Good for one-shot file decoding; avoid it
+  for per-frame camera scanning, where the next frame is usually a better
+  candidate than a slow retry.
+- `false` — strict single-pass decode: one binarization, one detection, no
+  retries. Deterministic latency for tests and trusted inputs.
+
 ### Decoding algorithm
 
 QR code decoding is challenging; it is essentially a computer vision problem. There are two main scenarios:
@@ -186,18 +204,19 @@ The state-of-the-art approach for this, as with other computer vision problems,
 
 The implemented reader algorithm is inspired by [ZXing](https://github.com/zxing/zxing):
 
-1. `toBitmap`: Convert the image to a bitmap of black and white segments. This is the slowest part and the most important.
-2. `detect`: Find three finder patterns and one alignment pattern (for versions > 1). This is tricky—they can be rotated and distorted by perspective. A square might appear as a quadrilateral with unknown size. The best we can do is count runs of the same color and select patterns with almost the same ratio of runs.
-3. `transform`: Once patterns have been found, correct the perspective and transform the quadrilateral into a square.
-4. `decodeBitmap`: Execute the encoding in reverse: read information via a zig-zag pattern, de-interleave bytes, correct errors, convert to bits, and finally, read segments from bits to create the string.
-5. **Finished!**
+1. Fast paths: exact module grids (`Bitmap` input, `grid` geometry) and clean generated / screenshot rasters are sampled directly, skipping the photographic pipeline below. Frames larger than 4MP run detection on a box-downscaled raster first, with full resolution kept as the fallback.
+2. `toBitmap`: Convert the image to a bitmap of black and white segments using per-block adaptive thresholds. This is the slowest part and the most important.
+3. `detect`: Find three finder patterns by scanning for 1:1:3:1:1 runs of the same color, cross-checking each candidate in four directions, and ranking candidate triples — several QR codes may share one frame. The BCH-protected version words are read straight from the image, since the size estimated from finder distances drifts on dense codes.
+4. `transform`: Correct perspective and sample the quadrilateral into a square grid — through one homography, or, for dense v7+ codes, cell-by-cell against the full alignment-pattern grid so distortion cannot accumulate.
+5. `decodeBitmap`: Execute the encoding in reverse: read information via a zig-zag pattern, de-interleave bytes, correct errors, convert to bits, and finally, read segments from bits to create the string.
+6. If every candidate fails and `multiPass` allows it, the pipeline reruns with inverted colors, on progressively downscaled rasters, and with perturbed sampling grids; `multiPass: 'max'` adds rotated, cropped, and upscaled candidates.
 
 ### Decoding test vectors
 
 To test our QR code decoding, we use an excellent dataset
 from [BoofCV](http://boofcv.org/index.php?title=Performance:QrCode). BoofCV decodes 73% of the test cases,
-while ZXing decodes 49%. Our implementation is nearly at parity with ZXing, primarily because ECI (Extended
-Channel Interpretation) support is not yet included. The test vectors are preserved in a Git repository at
+while ZXing decodes 49%. Our implementation decodes 63% with default options and 69% with
+`multiPass: 'max'`, surpassing ZXing. The test vectors are preserved in a Git repository at
 [github.com/paulmillr/qr-code-vectors](https://github.com/paulmillr/qr-code-vectors).
 
 **Note for Testing on iOS Safari:** Accessing the camera on iOS Safari requires HTTPS. This means that the file: protocol or non-encrypted http cannot be used. Ensure your testing environment uses https:.
@@ -274,6 +293,19 @@ nuintun x 51 ops/sec @ 19ms/op
 instascan x 133 ops/sec @ 7ms/op ± 31.77% (3ms..164ms)
 ```
 
+Versus native [zxing-cpp](https://github.com/zxing-cpp/zxing-cpp) 3.1 (gcc -O2, default reader
+options — the configuration phone scanning stacks approximate), measured on one Ryzen 9900X core:
+
+```
+# decode vs native zxing-cpp
+clean v1, 116x116     qr 5.6μs    zxing-cpp 23μs   (4.1x faster)
+clean 768-char code   qr 50μs     zxing-cpp 113μs  (2.3x faster)
+12MP photo            qr 12.8ms   zxing-cpp 17.3ms (1.4x faster)
+
+# BoofCV detection dataset accuracy (508 photos)
+qr 63%, qr multiPass max 69%, zxing-cpp fast mode 50%, zxing-cpp default 75%
+```
+
 ## License
 
 Copyright (c) 2023 Paul Miller (paulmillr.com)