qr 0.5.4 → 0.5.5

package/README.md

@@ -3,11 +3,11 @@
 Minimal 0-dependency QR code generator & reader.
 
 - 🔒 Auditable, 0-dependency
+- 🏎 Fast: [faster](#speed) than all JS implementations
+- 🔍 Reliable: 100MB+ of extensive test vectors ensure correctness
 - 🏞️ Encoding (generating) supports ASCII, term, gif, svg and png codes
 - 📷 Decoding (reading) supports camera feed input, files and non-browser environments
-- 🏎 Fast: faster than all JS implementations
-- 🔍 Extensive tests ensure correctness: 100MB+ of vectors
-- 🪶 16KB (gzipped) for encoding + decoding, 9KB for encoding
+- 🪶 18KB (gzipped) for encoding + decoding, 9KB for encoding
 
 Check out:
 
@@ -248,14 +248,14 @@ qrcode-generator x 2,909 ops/sec @ 343μs/op
 nuintun x 3,470 ops/sec @ 288μs/op
 
 # encode of large qr
-@paulmillr/qr x 318 ops/sec @ 3ms/op
+@paulmillr/qr x 334 ops/sec @ 2ms/op
 qrcode-generator x 174 ops/sec @ 5ms/op
 nuintun x 221 ops/sec @ 4ms/op
 
 # decode
-@paulmillr/qr x 162 ops/sec @ 6ms/op ± 3.78% (5ms..16ms)
-jsqr x 50 ops/sec @ 19ms/op ± 5.44% (18ms..35ms)
-nuintun x 49 ops/sec @ 20ms/op ± 5.08% (18ms..36ms)
+@paulmillr/qr x 662 ops/sec @ 1ms/op
+jsqr x 50 ops/sec @ 19ms/op
+nuintun x 49 ops/sec @ 20ms/op
 instascan x 128 ops/sec @ 7ms/op ± 31.44% (4ms..166ms)
 ```
 

package/decode.d.ts

@@ -27,7 +27,21 @@ import { Bitmap } from './index.ts';
 export type FinderPoints = [Pattern, Pattern, Point, Pattern];
 /**
  * Convert to grayscale. The function is the most expensive part of decoding:
- * it takes up to 90% of time. TODO: check gamma correction / sqr.
+ * it takes up to 90% of time.
+ *
+ * Binarization pipeline:
+ * 1. Convert RGB/RGBA image to one luma byte per pixel.
+ * 2. Split the image into 8x8 blocks and collect per-block mean/min/max.
+ * 3. Build a 5x5 neighborhood mean over those block means.
+ * 4. Turn each 8x8 block into bitmap bits using a local cut derived from:
+ *    - the neighborhood mean,
+ *    - the current block statistics,
+ *    - a cheap whole-image color-spread estimate,
+ *    - and, on risky scenes, a local variance field over block means.
+ *
+ * Instead of producing "best looking" thresholding: we produce a
+ * bitmap where finder patterns survive perspective / blur / highlights while
+ * keeping false dark regions low enough for downstream finder selection.
  */
 declare function toBitmap(img: Image): Bitmap;
 type Pattern = Point & {

package/decode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["src/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AACF;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAiC,KAAK,EAAQ,KAAK,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,MAAM,EAAS,MAAM,YAAY,CAAC;AAiB3C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AA2B9D;;;GAGG;AACH,iBAAS,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAwEpC;AAGD,KAAK,OAAO,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA6I7D,iBAAS,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACb,CA8HA;AAoHD,iBAAS,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;CACtB,CA6DA;AAqLD,iBAAS,YAAY,CACnB,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,MAAsB,GAClE,MAAM,CAuFR;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IAC5C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACtC,CAAC;AAsBF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CA8BlE;AAED,eAAe,QAAQ,CAAC;AAGxB,eAAO,MAAM,MAAM,EAAE;IACnB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CAMvB,CAAC"}
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["src/decode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;EAeE;AACF;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAiC,KAAK,EAAQ,KAAK,EAAE,MAAM,YAAY,CAAC;AACpF,OAAO,EAAE,MAAM,EAAS,MAAM,YAAY,CAAC;AA6B3C,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;AAoC9D;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CA2TpC;AAGD,KAAK,OAAO,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AA8K7D,iBAAS,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;CACb,CA8HA;AAoHD,iBAAS,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;CACtB,CA6DA;AAqLD,iBAAS,YAAY,CACnB,CAAC,EAAE,MAAM,EACT,OAAO,GAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,MAAsB,GAClE,MAAM,CAuFR;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IAC5C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAChD,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IACrC,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACtC,CAAC;AAsBF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,CA2BlE;AAED,eAAe,QAAQ,CAAC;AAGxB,eAAO,MAAM,MAAM,EAAE;IACnB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,MAAM,EAAE,OAAO,MAAM,CAAC;CAMvB,CAAC"}

package/decode.js

@@ -32,6 +32,18 @@ const PATTERN_VARIANCE = 2;
 const PATTERN_VARIANCE_DIAGONAL = 1.333;
 const PATTERN_MIN_CONFIRMATIONS = 2;
 const DETECT_MIN_ROW_SKIP = 3;
+// Pair LUTs for the 8x8 block-stat fast path: each 16-bit lane holds two
+// brightness bytes, so we can accumulate sum/min/max four pixels at a time.
+const SUM16 = new Uint16Array(1 << 16);
+const MIN16 = new Uint8Array(1 << 16);
+const MAX16 = new Uint8Array(1 << 16);
+for (let i = 0; i < SUM16.length; i++) {
+    const lo = i & 0xff;
+    const hi = i >>> 8;
+    SUM16[i] = lo + hi;
+    MIN16[i] = lo < hi ? lo : hi;
+    MAX16[i] = lo > hi ? lo : hi;
+}
 // TODO: move to index, nearby with bitmap and other graph related stuff?
 const int = (n) => n >>> 0;
 // distance ^ 2
@@ -51,37 +63,135 @@ const pointMirror = (p) => ({ x: p.y, y: p.x });
 const pointClone = (p) => ({ x: p.x, y: p.y });
 const pointInt = (p) => ({ x: int(p.x), y: int(p.y) });
 const pointAdd = (a, b) => ({ x: a.x + b.x, y: a.y + b.y });
+// Count trailing zeroes in a packed bitmap word so scanLine can skip whole
+// runs instead of testing one bit at a time.
+const ctz32 = (v) => {
+    v = v >>> 0;
+    if (v === 0)
+        return 32;
+    return 31 - Math.clz32((v & -v) >>> 0);
+};
 function cap(value, min, max) {
     return Math.max(Math.min(value, max || value), min || value);
 }
-const getBytesPerPixel = (img) => {
+function getBytesPerPixel(img) {
     const perPixel = img.data.length / (img.width * img.height);
     if (perPixel === 3 || perPixel === 4)
         return perPixel; // RGB or RGBA
     throw new Error(`Unknown image format, bytes per pixel=${perPixel}`);
-};
+}
+function isBytes(data) {
+    return data instanceof Uint8Array || data instanceof Uint8ClampedArray;
+}
 /**
  * Convert to grayscale. The function is the most expensive part of decoding:
- * it takes up to 90% of time. TODO: check gamma correction / sqr.
+ * it takes up to 90% of time.
+ *
+ * Binarization pipeline:
+ * 1. Convert RGB/RGBA image to one luma byte per pixel.
+ * 2. Split the image into 8x8 blocks and collect per-block mean/min/max.
+ * 3. Build a 5x5 neighborhood mean over those block means.
+ * 4. Turn each 8x8 block into bitmap bits using a local cut derived from:
+ *    - the neighborhood mean,
+ *    - the current block statistics,
+ *    - a cheap whole-image color-spread estimate,
+ *    - and, on risky scenes, a local variance field over block means.
+ *
+ * Instead of producing "best looking" thresholding: we produce a
+ * bitmap where finder patterns survive perspective / blur / highlights while
+ * keeping false dark regions low enough for downstream finder selection.
  */
 function toBitmap(img) {
+    const width = img.width;
+    const height = img.height;
+    const data = img.data;
     const bytesPerPixel = getBytesPerPixel(img);
-    const brightness = new Uint8Array(img.height * img.width);
-    for (let i = 0, j = 0, d = img.data; i < d.length; i += bytesPerPixel) {
-        const r = d[i];
-        const g = d[i + 1];
-        const b = d[i + 2];
-        brightness[j++] = int((r + 2 * g + b) / 4) & 0xff;
+    const pixLen = height * width;
+    const brightness = new Uint8Array(pixLen);
+    if (bytesPerPixel === 4 && isBytes(data) && (data.byteOffset & 3) === 0) {
+        // Little-endian RGBA: compute four grayscale bytes and commit as one u32 store.
+        // Unaligned RGBA subarray views are still valid inputs; they fall back to
+        // the scalar path because Uint32Array would throw on a misaligned offset.
+        const pixels = new Uint32Array(data.buffer, data.byteOffset, pixLen);
+        const bright32 = new Uint32Array(brightness.buffer, brightness.byteOffset, brightness.length >>> 2);
+        const n4 = pixels.length & ~3;
+        for (let i = 0, j = 0; i < n4; i += 4, j++) {
+            const v0 = pixels[i] >>> 0;
+            const v1 = pixels[i + 1] >>> 0;
+            const v2 = pixels[i + 2] >>> 0;
+            const v3 = pixels[i + 3] >>> 0;
+            // RGBA words are little-endian here, so this is `(r + 2*g + b) / 4`
+            // computed from the packed byte lanes for four pixels at once.
+            const b0 = ((v0 & 0xff) + (((v0 >>> 8) & 0xff) << 1) + ((v0 >>> 16) & 0xff)) >>> 2;
+            const b1 = ((v1 & 0xff) + (((v1 >>> 8) & 0xff) << 1) + ((v1 >>> 16) & 0xff)) >>> 2;
+            const b2 = ((v2 & 0xff) + (((v2 >>> 8) & 0xff) << 1) + ((v2 >>> 16) & 0xff)) >>> 2;
+            const b3 = ((v3 & 0xff) + (((v3 >>> 8) & 0xff) << 1) + ((v3 >>> 16) & 0xff)) >>> 2;
+            bright32[j] = b0 | (b1 << 8) | (b2 << 16) | (b3 << 24);
+        }
+        for (let i = n4; i < pixels.length; i++) {
+            const v = pixels[i] >>> 0;
+            brightness[i] = ((v & 0xff) + (((v >>> 8) & 0xff) << 1) + ((v >>> 16) & 0xff)) >>> 2;
+        }
     }
+    else {
+        for (let i = 0, j = 0, d = data; i < d.length; i += bytesPerPixel) {
+            const r = d[i];
+            const g = d[i + 1];
+            const b = d[i + 2];
+            brightness[j++] = int((r + 2 * g + b) / 4) & 0xff;
+        }
+    }
+    // Sampled color spread is a cheap "scene type" signal:
+    // grayscale / flat lighting scenes want conservative cuts, while colorful or
+    // high-spread scenes benefit from a slightly darker threshold.
+    let spreadSum = 0;
+    let spreadCnt = 0;
+    const spreadStep = bytesPerPixel * 16;
+    for (let i = 0; i < data.length; i += spreadStep) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        // hi=max(r,g,b), lo=min(r,g,b): this sampled channel spread is a cheap
+        // scene-level proxy for "how colorful / highlighty is this frame?".
+        const hi = r > g ? (r > b ? r : b) : g > b ? g : b;
+        const lo = r < g ? (r < b ? r : b) : g < b ? g : b;
+        spreadSum += hi - lo;
+        spreadCnt++;
+    }
+    const spreadMean = spreadSum / spreadCnt;
     // Convert to bitmap
     const block = GRAYSCALE_BLOCK_SIZE;
-    if (img.width < block * 5 || img.height < block * 5)
+    if (width < block * 5 || height < block * 5)
         throw new Error('image too small');
-    const bWidth = Math.ceil(img.width / block);
-    const bHeight = Math.ceil(img.height / block);
-    const maxY = img.height - block;
-    const maxX = img.width - block;
-    const blocks = new Uint8Array(bWidth * bHeight);
+    const bWidth = Math.ceil(width / block);
+    const bHeight = Math.ceil(height / block);
+    const maxY = height - block;
+    const maxX = width - block;
+    const blockLen = bWidth * bHeight;
+    const blockState = new Uint32Array(blockLen);
+    // Each 8x8 block stores packed:
+    // - bits 0..7: block baseline brightness used by the threshold field
+    // - bits 8..15: block min
+    // - bits 16..23: block max
+    let hiRangeCnt = 0;
+    let veryLowCnt = 0;
+    const padW = (width + 3) & ~3;
+    let statStride = width;
+    let stat32;
+    if ((width & 3) !== 0) {
+        const padLen = padW * height;
+        const brightPad = new Uint8Array(padLen);
+        for (let y = 0; y < height; y++) {
+            const src = y * width;
+            const dst = y * padW;
+            brightPad.set(brightness.subarray(src, src + width), dst);
+        }
+        // Misaligned widths are padded only for the block-stat fast path.
+        statStride = padW;
+        stat32 = new Uint32Array(brightPad.buffer, brightPad.byteOffset, (padW * height) >>> 2);
+    }
+    else
+        stat32 = new Uint32Array(brightness.buffer, brightness.byteOffset, brightness.length >>> 2);
     for (let y = 0; y < bHeight; y++) {
         const yPos = cap(y * block, 0, maxY);
         for (let x = 0; x < bWidth; x++) {
@@ -89,48 +199,248 @@ function toBitmap(img) {
             let sum = 0;
             let min = 0xff;
             let max = 0;
-            for (let yy = 0, pos = yPos * img.width + xPos; yy < block; yy = yy + 1, pos = pos + img.width) {
-                for (let xx = 0; xx < block; xx++) {
-                    const pixel = brightness[pos + xx];
-                    sum += pixel;
-                    min = Math.min(min, pixel);
-                    max = Math.max(max, pixel);
+            // The stat-LUT fast path needs the 8-pixel row start to be 32-bit aligned
+            // so each row can be read as two full u32 words without any shifts.
+            if ((xPos & 3) === 0) {
+                for (let yy = 0, pos = yPos * statStride + xPos; yy < block; yy++, pos += statStride) {
+                    const p = pos >>> 2;
+                    const w0 = stat32[p] >>> 0;
+                    const w1 = stat32[p + 1] >>> 0;
+                    const a0 = w0 & 0xffff;
+                    const a1 = w0 >>> 16;
+                    const b0 = w1 & 0xffff;
+                    const b1 = w1 >>> 16;
+                    sum += SUM16[a0] + SUM16[a1] + SUM16[b0] + SUM16[b1];
+                    const min0 = MIN16[a0];
+                    const min1 = MIN16[a1];
+                    const min2 = MIN16[b0];
+                    const min3 = MIN16[b1];
+                    if (min0 < min)
+                        min = min0;
+                    if (min1 < min)
+                        min = min1;
+                    if (min2 < min)
+                        min = min2;
+                    if (min3 < min)
+                        min = min3;
+                    const max0 = MAX16[a0];
+                    const max1 = MAX16[a1];
+                    const max2 = MAX16[b0];
+                    const max3 = MAX16[b1];
+                    if (max0 > max)
+                        max = max0;
+                    if (max1 > max)
+                        max = max1;
+                    if (max2 > max)
+                        max = max2;
+                    if (max3 > max)
+                        max = max3;
+                }
+            }
+            else {
+                for (let yy = 0, pos = yPos * width + xPos; yy < block; yy++, pos += width) {
+                    for (let xx = 0; xx < block; xx++) {
+                        const pixel = brightness[pos + xx];
+                        sum += pixel;
+                        if (pixel < min)
+                            min = pixel;
+                        if (pixel > max)
+                            max = pixel;
+                    }
                 }
             }
+            const bIdx = bWidth * y + x;
+            const range = max - min;
             // Average brightness of block
-            let average = Math.floor(sum / block ** 2);
-            if (max - min <= GRAYSCALE_RANGE) {
+            let average = sum >>> 6;
+            if (range <= GRAYSCALE_RANGE) {
+                // Low-contrast blocks are unstable if we threshold from their raw mean.
+                // Bias toward the local dark floor, then smooth with already-seen
+                // neighbors so finder rings don't disappear in washed-out regions.
                 average = min / 2;
                 if (y > 0 && x > 0) {
                     const idx = (x, y) => y * bWidth + x;
-                    const prev = (blocks[idx(x, y - 1)] + 2 * blocks[idx(x - 1, y)] + blocks[idx(x - 1, y - 1)]) / 4;
-                    if (min < prev)
-                        average = prev;
+                    const neighborNumerator = (blockState[idx(x, y - 1)] & 0xff) +
+                        2 * (blockState[idx(x - 1, y)] & 0xff) +
+                        (blockState[idx(x - 1, y - 1)] & 0xff);
+                    if (min * 4 < neighborNumerator)
+                        average = neighborNumerator / 4;
                 }
             }
-            blocks[bWidth * y + x] = int(average);
+            blockState[bIdx] = int(average) | (min << 8) | (max << 16);
+            if (range > 40 && average < 224)
+                hiRangeCnt++;
+            if (range <= 10)
+                veryLowCnt++;
         }
     }
-    const matrix = new Bitmap({ width: img.width, height: img.height });
+    const hiRangeFrac = hiRangeCnt / blockLen;
+    const veryLowFrac = veryLowCnt / blockLen;
+    // These two scene gates are the main "policy" layer on top of the local cut:
+    // - `spotBias` darkens globally flat, slightly colorful scenes that otherwise
+    //   miss bright-spot / washed-out QR modules.
+    // - `useVarField` avoids paying the variance-field cost on scenes where the
+    //   plain 5x5 mean is already stable enough.
+    const spotBias = veryLowFrac > 0.55 &&
+        veryLowFrac < 0.66 &&
+        hiRangeFrac < 0.02 &&
+        spreadMean > 10 &&
+        spreadMean < 20
+        ? -1
+        : 0;
+    const useVarField = veryLowFrac < 0.62 || spreadMean > 30;
+    const iWidth = bWidth + 1;
+    const iHeight = bHeight + 1;
+    const integLen = iHeight * iWidth;
+    // `integ` is the standard summed-area table of block means.
+    const integ = new Uint32Array(integLen);
+    // `integSqr` is the square-integral / summed-area table of `v * v` over the
+    // same block means, not a u8 pixel buffer. Those prefix sums can overflow
+    // 32-bit integer storage on large images, and Float32 was the measured
+    // faster compromise vs Float64 for this heuristic field.
+    const integSqr = useVarField ? new Float32Array(integLen) : undefined;
+    for (let y = 0; y < bHeight; y++) {
+        let rowSum = 0;
+        let rowSq = 0;
+        const bRow = y * bWidth;
+        const iRow = (y + 1) * iWidth;
+        const iPrev = y * iWidth;
+        for (let x = 0; x < bWidth; x++) {
+            const v = blockState[bRow + x] & 0xff;
+            rowSum += v;
+            if (integSqr)
+                rowSq += v * v;
+            integ[iRow + x + 1] = integ[iPrev + x + 1] + rowSum;
+            if (integSqr)
+                integSqr[iRow + x + 1] = integSqr[iPrev + x + 1] + rowSq;
+        }
+    }
+    const matrix = new Bitmap({ width, height });
+    const rows = Math.ceil(width / 32);
+    // Decode intentionally writes the packed bitmap words directly here. The
+    // per-pixel Bitmap API is too expensive on this hot path, so this must stay
+    // in sync with Bitmap's internal `value` layout.
+    const bm = matrix.value;
+    const rad = 2;
+    const win = rad * 2 + 1;
+    const area = win * win;
     for (let y = 0; y < bHeight; y++) {
         const yPos = cap(y * block, 0, maxY);
-        const top = cap(y, 2, bHeight - 3);
+        const top = cap(y, rad, bHeight - rad - 1);
+        const y0 = top - rad;
+        const y1 = top + rad;
+        const r0 = y0 * iWidth;
+        const r1 = (y1 + 1) * iWidth;
         for (let x = 0; x < bWidth; x++) {
             const xPos = cap(x * block, 0, maxX);
-            const left = cap(x, 2, bWidth - 3);
+            const shift = xPos & 31;
+            const col = xPos >>> 5;
+            const left = cap(x, rad, bWidth - rad - 1);
+            const x0 = left - rad;
+            const x1 = left + rad;
             // 5x5 blocks average
-            let sum = 0;
-            for (let yy = -2; yy <= 2; yy++) {
-                const y2 = bWidth * (top + yy) + left;
-                for (let xx = -2; xx <= 2; xx++)
-                    sum += blocks[y2 + xx];
-            }
-            const average = sum / 25;
-            for (let y = 0, pos = yPos * img.width + xPos; y < block; y += 1, pos += img.width) {
-                for (let x = 0; x < block; x++) {
-                    if (brightness[pos + x] <= average)
-                        matrix.set(xPos + x, yPos + y, true);
+            const sum = integ[r1 + (x1 + 1)] - integ[r0 + (x1 + 1)] - integ[r1 + x0] + integ[r0 + x0];
+            // `average` is the coarse threshold surface: a 5x5 neighborhood mean of
+            // the 8x8 block means. The adjustments below decide when to move away
+            // from that surface for the current block.
+            const average = (sum / area) | 0;
+            let cut = average;
+            const bIdx = bWidth * y + x;
+            const blk = blockState[bIdx];
+            const blockAvg = blk & 0xff;
+            const min = (blk >>> 8) & 0xff;
+            const max = blk >>> 16;
+            const range = max - min;
+            if (average < min)
+                continue;
+            if (average >= max) {
+                const m = 0xff;
+                for (let yy = 0, row = yPos * rows + col; yy < block; yy++, row += rows) {
+                    const lo = (m << shift) >>> 0;
+                    bm[row] |= lo;
+                    if (shift > 24)
+                        bm[row + 1] |= m >>> (32 - shift);
                 }
+                continue;
+            }
+            // `localAdj`: nudge toward the current block when it is darker than
+            // its neighborhood. This helps preserve dark rings / modules that are
+            // locally meaningful but diluted by the 5x5 field.
+            let localAdj = (blockAvg - average) >> 4;
+            if (localAdj < 0)
+                localAdj = 0;
+            if (localAdj > 1)
+                localAdj = 1;
+            // `chromaAdj`: in colorful, mid-tone blocks, slight extra darkening
+            // helps where luma alone underestimates QR structure.
+            let chromaAdj = 0;
+            if (range > 6 && average > 48 && average < 232) {
+                const spreadBoost = spreadMean > 8 ? spreadMean - 8 : 0;
+                const mid = 128 - Math.abs(average - 128);
+                chromaAdj = int((spreadBoost * (range - 6) * mid) / 2200000);
+                if (chromaAdj > 1)
+                    chromaAdj = 1;
+            }
+            // `varAdj`: if the surrounding block field has real variance, darken
+            // more aggressively when the local mean still sits far above the
+            // block minimum. This is what rescues many weak finder cases.
+            let varAdj = 0;
+            if (integSqr && range >= 6 && range <= 128) {
+                const sq = integSqr[r1 + (x1 + 1)] - integSqr[r0 + (x1 + 1)] - integSqr[r1 + x0] + integSqr[r0 + x0];
+                const meanSq = sq / area;
+                let variance = meanSq - average * average;
+                if (variance < 0)
+                    variance = 0;
+                const gap = average - min;
+                const num = gap * (variance - 196);
+                const den = (variance + 832) * 9;
+                // `variance` is clamped non-negative, so `den` stays strictly positive.
+                varAdj = int(num / den);
+                if (varAdj < -1)
+                    varAdj = -1;
+                if (varAdj > 4)
+                    varAdj = 4;
+            }
+            cut = average + localAdj + chromaAdj + varAdj;
+            // Small scene-level nudges are intentionally separate from the three
+            // local terms above: they are cheap and only target known whole-scene
+            // failure modes such as washed-out bright-spot images.
+            if (spreadMean > 10 && range >= 8 && range <= 96 && average > min + 8 && average < 192)
+                cut++;
+            if (veryLowFrac > 0.68 && veryLowFrac < 0.86 && range >= 6 && range <= 20 && average < 196)
+                cut++;
+            cut += spotBias;
+            if (cut < min)
+                cut = min;
+            if (cut > max)
+                cut = max;
+            // Emit one 8-pixel row of the current 8x8 block: compare against the
+            // block cut, pack the 8 black/white decisions into one byte, then OR
+            // that byte into the bitmap word(s) at the current x-bit offset.
+            for (let yy = 0, pos = yPos * width + xPos, row = yPos * rows + col; yy < block; yy++, pos += width, row += rows) {
+                let m = 0;
+                if (brightness[pos] <= cut)
+                    m |= 1;
+                if (brightness[pos + 1] <= cut)
+                    m |= 2;
+                if (brightness[pos + 2] <= cut)
+                    m |= 4;
+                if (brightness[pos + 3] <= cut)
+                    m |= 8;
+                if (brightness[pos + 4] <= cut)
+                    m |= 16;
+                if (brightness[pos + 5] <= cut)
+                    m |= 32;
+                if (brightness[pos + 6] <= cut)
+                    m |= 64;
+                if (brightness[pos + 7] <= cut)
+                    m |= 128;
+                if (m === 0)
+                    continue;
+                const lo = (m << shift) >>> 0;
+                bm[row] |= lo;
+                if (shift > 24)
+                    bm[row + 1] |= m >>> (32 - shift);
             }
         }
     }
@@ -235,17 +545,53 @@ function pattern(p, size) {
         },
         scanLine(b, y, xStart, xEnd, fn) {
             const runs = res.runs();
+            // Finder scanning also couples to Bitmap internals so it can scan packed
+            // 32-bit words directly instead of re-reading one pixel bit at a time.
+            const words = b.words;
+            const vals = b.value;
+            const row = y * words;
+            const pattern = res.pattern;
+            // Scan one packed bitmap row by jumping whole equal-bit runs inside 32-bit
+            // words; this keeps finder scanning from degenerating into per-pixel work.
+            const bitAt = (x) => ((vals[row + (x >>> 5)] >>> (x & 31)) & 1) === 1;
+            const runLen = (x, want) => {
+                let wi = row + (x >>> 5);
+                let bit = x & 31;
+                let w = (vals[wi] >>> bit) >>> 0;
+                let left = xEnd - x;
+                let len = 0;
+                while (left > 0) {
+                    const room = 32 - bit;
+                    let n = want ? ctz32(~w >>> 0) : ctz32(w);
+                    if (n > room)
+                        n = room;
+                    if (n > left)
+                        n = left;
+                    len += n;
+                    if (n < room && n < left)
+                        break;
+                    left -= n;
+                    if (left <= 0)
+                        break;
+                    wi++;
+                    bit = 0;
+                    w = vals[wi] >>> 0;
+                }
+                return len;
+            };
             let pos = 0;
             let x = xStart;
             // If we start in middle of an image, skip first pattern run,
             // since we don't know run length of pixels from left side
             if (xStart)
-                while (x < xEnd && !!b.get(x, y) === res.pattern[0])
-                    x++;
+                x += runLen(x, pattern[0]);
             for (; x < xEnd; x++) {
+                const cur = bitAt(x);
                 // Same run, continue counting
-                if (!!b.get(x, y) === res.pattern[pos]) {
-                    runs[pos]++;
+                if (cur === pattern[pos]) {
+                    const n = runLen(x, cur);
+                    runs[pos] += n;
+                    x += n - 1;
                     // If not last element - continue counting
                     if (x !== b.width - 1)
                         continue;
@@ -937,10 +1283,9 @@ export function decodeQR(img, opts = {}) {
         if (!Number.isSafeInteger(img[field]) || img[field] <= 0)
             throw new Error(`invalid img.${field}=${img[field]} (${typeof img[field]})`);
     }
-    if (!Array.isArray(img.data) &&
-        !(img.data instanceof Uint8Array) &&
-        !(img.data instanceof Uint8ClampedArray))
-        throw new Error(`invalid image.data=${img.data} (${typeof img.data})`);
+    const { data } = img;
+    if (!Array.isArray(data) && !isBytes(data))
+        throw new Error(`invalid image.data=${data} (${typeof data})`);
     if (opts.cropToSquare !== undefined && typeof opts.cropToSquare !== 'boolean')
         throw new Error(`invalid opts.cropToSquare=${opts.cropToSquare}`);
     for (const fn of ['pointsOnDetect', 'imageOnBitmap', 'imageOnDetect', 'imageOnResult']) {