@sythos/js_barcode_universal 1.5.8 → 1.5.10

package/src/ts/frameqr/tables.ts

@@ -0,0 +1,270 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Structural contract for the Sythos Canvas QR profile.
+ *
+ * DENSO WAVE's public material describes FrameQR(R) as a proprietary symbol
+ * with a freely shaped canvas, dedicated generation/reading software and no
+ * compatibility with ordinary QR readers. It does not publish the bitstream,
+ * placement or error-correction rules required for an interoperable encoder.
+ * Consequently this module does not claim to implement DENSO FrameQR.
+ *
+ * The implementable profile below starts with an ISO/IEC 18004 QR Model 2
+ * symbol at level H and clears a bounded group of data modules. Its worst-case
+ * damage is calculated per Reed-Solomon block and must remain within the
+ * standard QR correction radius. Function modules are never canvas modules.
+ * This provides a deterministic, independently testable canvas QR profile, but
+ * it is explicitly non-certified and not a substitute for proprietary FrameQR
+ * generation or validation software.
+ *
+ * @module frameqr/tables
+ */
+
+import {
+  blockLayout,
+  dataModuleOrder,
+  reservedModules,
+  versionSize,
+} from '../qr/tables.js';
+
+/** Public identity and compatibility boundary of the implementable profile. */
+export const FRAMEQR_PROFILE = Object.freeze({
+  id: 'sythos-canvas-qr/1',
+  name: 'Sythos Canvas QR profile',
+  certified: false,
+  densoFrameQrCompatible: false,
+  baseSymbology: 'QR Code Model 2',
+  requiredEcc: 'H',
+  standard: 'ISO/IEC 18004 QR Code baseline',
+});
+
+/** Canvas shapes whose module membership is fully deterministic. */
+export const FRAMEQR_CANVAS_SHAPES = Object.freeze(['square', 'circle', 'diamond']);
+
+function oddAtMost(value, maximum) {
+  let n = Math.max(1, Math.min(maximum, Math.floor(value)));
+  if ((n & 1) === 0) n--;
+  return Math.max(1, n);
+}
+
+function assertSymbolSize(symbolSize) {
+  if (!Number.isInteger(symbolSize) || symbolSize < 21 || symbolSize > 177 || (symbolSize - 17) % 4 !== 0) {
+    throw new RangeError(`Frame QR profile: ${symbolSize} is not a QR Model 2 symbol size`);
+  }
+}
+
+/**
+ * Canonicalise a canvas request.
+ *
+ * Coordinates and dimensions are module units. Odd dimensions make the centre
+ * unambiguous. Only quarter turns are accepted because arbitrary-angle raster
+ * membership would depend on renderer-specific sampling.
+ *
+ * @param {number} symbolSize QR module width/height (21..177).
+ * @param {object} [canvas]
+ * @returns {{shape:string,centerX:number,centerY:number,width:number,height:number,angle:number}}
+ */
+export function normalizeCanvasSpec(symbolSize, canvas = {}) {
+  assertSymbolSize(symbolSize);
+  if (canvas === null || typeof canvas !== 'object' || Array.isArray(canvas)) {
+    throw new TypeError('Frame QR profile: canvas must be an object');
+  }
+
+  const shape = String(canvas.shape ?? 'square').toLowerCase();
+  if (!FRAMEQR_CANVAS_SHAPES.includes(shape)) {
+    throw new RangeError(`Frame QR profile: unsupported canvas shape "${shape}"`);
+  }
+
+  const defaultSize = oddAtMost(Math.max(3, Math.round(symbolSize * 0.17)), symbolSize - 16);
+  const requestedSize = canvas.size;
+  const requestedWidth = canvas.width ?? requestedSize ?? defaultSize;
+  const requestedHeight = canvas.height ?? requestedSize ?? defaultSize;
+  const maximumDimension = symbolSize - 16;
+  for (const [name, value] of [['width', requestedWidth], ['height', requestedHeight]]) {
+    if (!Number.isFinite(Number(value)) || Number(value) < 1 || Number(value) > maximumDimension) {
+      throw new RangeError(
+        `Frame QR profile: canvas ${name} must be between 1 and ${maximumDimension} modules`
+      );
+    }
+  }
+  const width = oddAtMost(Number(requestedWidth), maximumDimension);
+  const height = oddAtMost(Number(requestedHeight), maximumDimension);
+  const centerX = Math.round(canvas.centerX ?? (symbolSize - 1) / 2);
+  const centerY = Math.round(canvas.centerY ?? (symbolSize - 1) / 2);
+  const angle = ((Number(canvas.angle ?? 0) % 360) + 360) % 360;
+
+  if (![0, 90, 180, 270].includes(angle)) {
+    throw new RangeError('Frame QR profile: angle must be 0, 90, 180 or 270 degrees');
+  }
+  if (centerX < 8 || centerY < 8 || centerX >= symbolSize - 8 || centerY >= symbolSize - 8) {
+    throw new RangeError('Frame QR profile: canvas centre must remain inside the finder-pattern boundary');
+  }
+
+  return { shape, centerX, centerY, width, height, angle };
+}
+
+/**
+ * Enumerate canvas modules, including any overlaps with QR function modules.
+ * A conforming encoder rejects such overlaps rather than damaging function
+ * patterns.
+ *
+ * @param {number} symbolSize
+ * @param {object} [canvas]
+ * @returns {Array<[number, number]>}
+ */
+export function canvasModules(symbolSize, canvas = {}) {
+  const spec = normalizeCanvasSpec(symbolSize, canvas);
+  const rotate = spec.angle === 90 || spec.angle === 270;
+  const width = rotate ? spec.height : spec.width;
+  const height = rotate ? spec.width : spec.height;
+  const halfWidth = (width - 1) / 2;
+  const halfHeight = (height - 1) / 2;
+  const modules = [];
+
+  for (let dy = -halfHeight; dy <= halfHeight; dy++) {
+    for (let dx = -halfWidth; dx <= halfWidth; dx++) {
+      const nx = halfWidth === 0 ? 0 : dx / halfWidth;
+      const ny = halfHeight === 0 ? 0 : dy / halfHeight;
+      let inside;
+      if (spec.shape === 'circle') inside = nx * nx + ny * ny <= 1 + Number.EPSILON;
+      else if (spec.shape === 'diamond') inside = Math.abs(nx) + Math.abs(ny) <= 1 + Number.EPSILON;
+      else inside = true;
+      if (inside) modules.push([spec.centerX + dx, spec.centerY + dy]);
+    }
+  }
+  return modules;
+}
+
+/** Build the interleaved-codeword to RS-block map used by QR Model 2. */
+function codewordBlockMap(layout) {
+  const dataCounts = new Array(layout.blockCount);
+  for (let block = 0; block < layout.blockCount; block++) {
+    dataCounts[block] = block < layout.group1Blocks
+      ? layout.group1DataCount
+      : layout.group2DataCount;
+  }
+
+  const map = [];
+  const maxData = Math.max(...dataCounts);
+  for (let i = 0; i < maxData; i++) {
+    for (let block = 0; block < layout.blockCount; block++) {
+      if (i < dataCounts[block]) map.push(block);
+    }
+  }
+  for (let i = 0; i < layout.eccPerBlock; i++) {
+    for (let block = 0; block < layout.blockCount; block++) map.push(block);
+  }
+  return map;
+}
+
+/**
+ * Calculate worst-case QR codeword damage caused by a canvas.
+ * A codeword is counted if any of its modules is touched. This is conservative:
+ * clearing an already-light module does no damage, but safety cannot depend on
+ * one payload or mask.
+ *
+ * @param {number} version QR version 1..40.
+ * @param {object} [canvas]
+ */
+export function analyzeCanvasDamage(version, canvas = {}) {
+  if (!Number.isInteger(version) || version < 1 || version > 40) {
+    throw new RangeError(`Frame QR profile: version must be an integer 1-40, got ${version}`);
+  }
+  const symbolSize = versionSize(version);
+  const spec = normalizeCanvasSpec(symbolSize, canvas);
+  const modules = canvasModules(symbolSize, spec);
+  const reserved = reservedModules(version);
+  const reservedOverlaps = modules.filter(([x, y]) => reserved.get(x, y));
+
+  const moduleKeys = new Set(modules.map(([x, y]) => `${x},${y}`));
+  const order = dataModuleOrder(version);
+  const touchedCodewords = new Set();
+  for (let bit = 0; bit < order.length / 2; bit++) {
+    if (moduleKeys.has(`${order[bit * 2]},${order[bit * 2 + 1]}`)) touchedCodewords.add(bit >> 3);
+  }
+
+  const layout = blockLayout(version, 'H');
+  const blockMap = codewordBlockMap(layout);
+  const touchedByBlockSets = Array.from({ length: layout.blockCount }, () => new Set());
+  for (const codeword of touchedCodewords) {
+    const block = blockMap[codeword];
+    if (block !== undefined) touchedByBlockSets[block].add(codeword);
+  }
+  const touchedCodewordsByBlock = touchedByBlockSets.map((set) => set.size);
+  const correctionBudgetPerBlock = Math.floor(layout.eccPerBlock / 2);
+  const safe = reservedOverlaps.length === 0 &&
+    touchedCodewordsByBlock.every((count) => count <= correctionBudgetPerBlock);
+
+  return {
+    profile: FRAMEQR_PROFILE.id,
+    certified: false,
+    version,
+    symbolSize,
+    canvas: spec,
+    canvasModuleCount: modules.length,
+    reservedOverlaps,
+    touchedCodewordCount: touchedCodewords.size,
+    touchedCodewordsByBlock,
+    correctionBudgetPerBlock,
+    safe,
+  };
+}
+
+/** Validate a canvas and return the non-certifying structural analysis. */
+export function validateCanvasSpec(version, canvas = {}) {
+  return analyzeCanvasDamage(version, canvas);
+}
+
+/** Self-check the fixed profile contract and representative QR geometries. */
+export function validateFrameQrTables() {
+  const problems = [];
+  if (FRAMEQR_PROFILE.certified !== false || FRAMEQR_PROFILE.densoFrameQrCompatible !== false) {
+    problems.push('profile compatibility boundary must remain explicitly non-certified');
+  }
+  if (new Set(FRAMEQR_CANVAS_SHAPES).size !== FRAMEQR_CANVAS_SHAPES.length) {
+    problems.push('canvas shape identifiers must be unique');
+  }
+  for (const version of [1, 2, 3, 4, 7, 10, 20, 30, 40]) {
+    const size = versionSize(version);
+    const spec = normalizeCanvasSpec(size);
+    const modules = canvasModules(size, spec);
+    const unique = new Set(modules.map(([x, y]) => `${x},${y}`));
+    if (unique.size !== modules.length) problems.push(`v${version}: duplicate canvas modules`);
+    if (modules.some(([x, y]) => x < 0 || y < 0 || x >= size || y >= size)) {
+      problems.push(`v${version}: canvas escapes the symbol`);
+    }
+    const analysis = analyzeCanvasDamage(version, spec);
+    if (analysis.touchedCodewordsByBlock.length !== blockLayout(version, 'H').blockCount) {
+      problems.push(`v${version}: damage analysis block count mismatch`);
+    }
+  }
+  return problems;
+}

package/src/ts/image/binarizer.ts

@@ -0,0 +1,270 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Greyscale to black-and-white.
+ *
+ * This is the single biggest determinant of whether a reader works on real
+ * photographs. Decoding logic is exact and either right or wrong; binarization
+ * is a judgement call made a million times per image, and every downstream
+ * stage inherits its mistakes. A symbol lost here is lost permanently.
+ *
+ * Two strategies:
+ *
+ *   global  — one threshold for the whole image. Fast, and correct for clean
+ *             synthetic images: screenshots, generated PNGs, flat scans.
+ *   hybrid  — a threshold per 8x8 block, smoothed across neighbours. Handles
+ *             the uneven lighting that dominates camera input: shadows,
+ *             glare, vignetting, a page curving away from the lens.
+ *
+ * @module image/binarizer
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { NotFoundError } from '../core/errors.js';
+
+/** Side of a block, in pixels. */
+const BLOCK = 8;
+const BLOCK_SHIFT = 3;
+
+/** Below this spread, a block is treated as uniform rather than as edges. */
+const MIN_DYNAMIC_RANGE = 24;
+
+/**
+ * One threshold for the entire image, chosen from the luminance histogram.
+ *
+ * Finds the two strongest peaks — ideally ink and paper — and cuts at the
+ * point of lowest population between them, weighted by distance so a narrow
+ * secondary peak does not drag the threshold onto a shoulder.
+ *
+ * @param {import('./luminance.js').LuminanceSource} source
+ * @returns {BitMatrix} Set bit = dark module.
+ */
+export function binarizeGlobal(source) {
+  const { grey, width, height } = source;
+  const buckets = new Int32Array(32);
+  for (let i = 0; i < grey.length; i++) buckets[grey[i] >> 3]++;
+
+  const threshold = pickThreshold(buckets);
+  const out = new BitMatrix(width, height);
+  for (let y = 0; y < height; y++) {
+    const base = y * width;
+    for (let x = 0; x < width; x++) {
+      if (grey[base + x] < threshold) out.set(x, y);
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {Int32Array} buckets
+ * @returns {number} Threshold in 0-255.
+ */
+function pickThreshold(buckets) {
+  const n = buckets.length;
+
+  let firstPeak = 0, firstPeakSize = 0;
+  for (let i = 0; i < n; i++) {
+    if (buckets[i] > firstPeakSize) {
+      firstPeakSize = buckets[i];
+      firstPeak = i;
+    }
+  }
+
+  // Score candidates by population scaled by squared distance from the first
+  // peak: the second peak must be both populous and clearly separated.
+  let secondPeak = 0, secondScore = 0;
+  for (let i = 0; i < n; i++) {
+    const d = i - firstPeak;
+    const score = buckets[i] * d * d;
+    if (score > secondScore) {
+      secondScore = score;
+      secondPeak = i;
+    }
+  }
+
+  let low = Math.min(firstPeak, secondPeak);
+  let high = Math.max(firstPeak, secondPeak);
+
+  if (high - low <= n >> 4) {
+    // Effectively unimodal — a blank region, or an image with no ink. Fall
+    // back to the midpoint of the occupied range rather than inventing edges.
+    let lo = 0, hi = n - 1;
+    while (lo < n && buckets[lo] === 0) lo++;
+    while (hi > 0 && buckets[hi] === 0) hi--;
+    return (((lo + hi) >> 1) << 3) + 4;
+  }
+
+  // Deepest valley between the peaks, biased toward the middle.
+  let valley = low, valleyScore = -1;
+  for (let i = low + 1; i < high; i++) {
+    const fromLow = i - low;
+    const fromHigh = high - i;
+    const score = fromLow * fromHigh * (firstPeakSize - buckets[i]);
+    if (score > valleyScore) {
+      valleyScore = score;
+      valley = i;
+    }
+  }
+  return (valley << 3) + 4;
+}
+
+/**
+ * Locally adaptive thresholding.
+ *
+ * Per 8x8 block: compute min, max and mean. A block with real contrast gets
+ * its own mean as the threshold. A block that is flat is ambiguous on its own
+ * — solid paper and solid ink look identical from the inside — so it inherits
+ * from its neighbourhood, which is what stops large quiet zones from being
+ * speckled into noise.
+ *
+ * Thresholds are then averaged over a 5x5 block window, so lighting gradients
+ * are followed smoothly instead of producing visible block seams that the
+ * detectors would read as edges.
+ *
+ * @param {import('./luminance.js').LuminanceSource} source
+ * @returns {BitMatrix}
+ */
+export function binarizeHybrid(source) {
+  const { grey, width, height } = source;
+
+  // Too small to block up meaningfully; the global pass is strictly better.
+  if (width < BLOCK * 5 || height < BLOCK * 5) return binarizeGlobal(source);
+
+  const bw = (width + BLOCK - 1) >> BLOCK_SHIFT;
+  const bh = (height + BLOCK - 1) >> BLOCK_SHIFT;
+  const means = new Int32Array(bw * bh);
+  const ranges = new Int32Array(bw * bh);
+
+  for (let by = 0; by < bh; by++) {
+    const y0 = by << BLOCK_SHIFT;
+    const y1 = Math.min(y0 + BLOCK, height);
+    for (let bx = 0; bx < bw; bx++) {
+      const x0 = bx << BLOCK_SHIFT;
+      const x1 = Math.min(x0 + BLOCK, width);
+
+      let sum = 0, min = 255, max = 0, count = 0;
+      for (let y = y0; y < y1; y++) {
+        const base = y * width;
+        for (let x = x0; x < x1; x++) {
+          const v = grey[base + x];
+          sum += v;
+          if (v < min) min = v;
+          if (v > max) max = v;
+          count++;
+        }
+      }
+      const idx = by * bw + bx;
+      means[idx] = count ? (sum / count) | 0 : 128;
+      ranges[idx] = max - min;
+    }
+  }
+
+  // Flat blocks adopt a threshold from context. Looking left and up is enough
+  // because those neighbours are already resolved, and it makes the pass
+  // single-shot rather than iterative.
+  for (let by = 0; by < bh; by++) {
+    for (let bx = 0; bx < bw; bx++) {
+      const idx = by * bw + bx;
+      if (ranges[idx] >= MIN_DYNAMIC_RANGE) continue;
+
+      let inherited = means[idx];
+      if (bx > 0 && by > 0) {
+        const neighbours = [
+          means[idx - 1],
+          means[idx - bw],
+          means[idx - bw - 1],
+        ];
+        const avg = (neighbours[0] + neighbours[1] + neighbours[2]) / 3;
+        // A flat block darker than its surroundings is ink; lighter is paper.
+        // Either way the local minimum is the safer threshold than the mean.
+        inherited = Math.min(avg, means[idx]);
+      }
+      means[idx] = inherited | 0;
+    }
+  }
+
+  const out = new BitMatrix(width, height);
+  const R = 2; // 5x5 block window
+
+  for (let by = 0; by < bh; by++) {
+    const y0 = by << BLOCK_SHIFT;
+    const y1 = Math.min(y0 + BLOCK, height);
+    const byLo = Math.max(0, by - R);
+    const byHi = Math.min(bh - 1, by + R);
+
+    for (let bx = 0; bx < bw; bx++) {
+      const bxLo = Math.max(0, bx - R);
+      const bxHi = Math.min(bw - 1, bx + R);
+
+      let sum = 0, count = 0;
+      for (let ny = byLo; ny <= byHi; ny++) {
+        for (let nx = bxLo; nx <= bxHi; nx++) {
+          sum += means[ny * bw + nx];
+          count++;
+        }
+      }
+      const threshold = sum / count;
+
+      const x0 = bx << BLOCK_SHIFT;
+      const x1 = Math.min(x0 + BLOCK, width);
+      for (let y = y0; y < y1; y++) {
+        const base = y * width;
+        for (let x = x0; x < x1; x++) {
+          if (grey[base + x] < threshold) out.set(x, y);
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Binarize with the named strategy.
+ *
+ * @param {import('./luminance.js').LuminanceSource} source
+ * @param {'global' | 'hybrid' | 'auto'} [strategy]
+ * @returns {BitMatrix}
+ */
+export function binarize(source, strategy = 'auto') {
+  if (!source || !source.grey) throw new NotFoundError('binarize: no luminance source');
+  switch (strategy) {
+    case 'global': return binarizeGlobal(source);
+    case 'hybrid': return binarizeHybrid(source);
+    case 'auto':
+      // Small images are almost always generated rather than photographed.
+      return source.width * source.height < 200 * 200
+        ? binarizeGlobal(source)
+        : binarizeHybrid(source);
+    default:
+      throw new NotFoundError(`Unknown binarizer strategy: ${strategy}`);
+  }
+}

package/src/ts/image/grid-sampler.ts

@@ -0,0 +1,164 @@
+/*!
+ * Sythos Barcode Suite
+ *
+ * MIT License
+ *
+ * Copyright (c) 2026 Sythos
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Original work. No code from any other barcode implementation.
+ */
+
+/**
+ * Resample a distorted symbol in the image into an upright module grid.
+ *
+ * Given a transform that maps grid coordinates to image coordinates, this
+ * samples the centre of every module. Sampling centres rather than averaging
+ * whole cells is deliberate: module edges are where blur and bleed live, and
+ * including them turns a marginal symbol into an unreadable one.
+ *
+ * @module image/grid-sampler
+ */
+
+import { BitMatrix } from '../core/bit-matrix.js';
+import { NotFoundError } from '../core/errors.js';
+import { PerspectiveTransform } from './perspective.js';
+
+/**
+ * Sample a `dimension` x `dimension` grid (or `width` x `height`).
+ *
+ * @param {BitMatrix} image Binarized source image.
+ * @param {number} width Modules across.
+ * @param {number} height Modules down.
+ * @param {PerspectiveTransform} transform Grid space -> image space.
+ * @returns {BitMatrix}
+ * @throws {NotFoundError} If the grid falls outside the image.
+ */
+export function sampleGrid(image, width, height, transform) {
+  const out = new BitMatrix(width, height);
+  const points = new Float32Array(width * 2);
+
+  for (let y = 0; y < height; y++) {
+    // Module centres: offset by half a module in both axes.
+    const gridY = y + 0.5;
+    for (let x = 0; x < width; x++) {
+      points[x * 2] = x + 0.5;
+      points[x * 2 + 1] = gridY;
+    }
+    transform.transform(points);
+
+    for (let x = 0; x < width; x++) {
+      const px = points[x * 2] | 0;
+      const py = points[x * 2 + 1] | 0;
+      if (px < 0 || py < 0 || px >= image.width || py >= image.height) {
+        throw new NotFoundError(
+          `Sampling grid escapes the image at module (${x}, ${y})`
+        );
+      }
+      if (image.get(px, py)) out.set(x, y);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Sample with a 3x3 majority vote per module.
+ *
+ * Slower, and worth it when a single-point sample lands on a speck of noise or
+ * a JPEG artefact. Readers fall back to this after a clean sample fails to
+ * decode, rather than paying for it on every attempt.
+ *
+ * @param {BitMatrix} image
+ * @param {number} width
+ * @param {number} height
+ * @param {PerspectiveTransform} transform
+ * @returns {BitMatrix}
+ */
+export function sampleGridVoting(image, width, height, transform) {
+  const out = new BitMatrix(width, height);
+
+  // Spacing between module centres, measured in image pixels, so the vote
+  // spreads across the module rather than a fixed pixel radius that would be
+  // meaningless at a different scale.
+  const p0 = transform.transformPoint(0.5, 0.5);
+  const p1 = transform.transformPoint(1.5, 0.5);
+  const p2 = transform.transformPoint(0.5, 1.5);
+  const stepX = Math.hypot(p1.x - p0.x, p1.y - p0.y);
+  const stepY = Math.hypot(p2.x - p0.x, p2.y - p0.y);
+  const rx = Math.max(1, Math.round(stepX / 4));
+  const ry = Math.max(1, Math.round(stepY / 4));
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const c = transform.transformPoint(x + 0.5, y + 0.5);
+      const cx = c.x | 0;
+      const cy = c.y | 0;
+      if (cx < 0 || cy < 0 || cx >= image.width || cy >= image.height) {
+        throw new NotFoundError(
+          `Sampling grid escapes the image at module (${x}, ${y})`
+        );
+      }
+
+      let dark = 0;
+      let total = 0;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+          const sx = cx + dx * rx;
+          const sy = cy + dy * ry;
+          if (sx < 0 || sy < 0 || sx >= image.width || sy >= image.height) continue;
+          total++;
+          if (image.get(sx, sy)) dark++;
+        }
+      }
+      if (total > 0 && dark * 2 > total) out.set(x, y);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Build the transform for a symbol whose four corners are known, and sample it.
+ *
+ * Corners are in reading order: top-left, top-right, bottom-right, bottom-left.
+ *
+ * @param {BitMatrix} image
+ * @param {number} dimension Modules per side.
+ * @param {Array<{x: number, y: number}>} corners
+ * @param {boolean} [voting]
+ * @returns {BitMatrix}
+ */
+export function sampleQuad(image, dimension, corners, voting = false) {
+  if (corners.length !== 4) throw new NotFoundError('sampleQuad needs exactly 4 corners');
+  const [tl, tr, br, bl] = corners;
+  const d = dimension;
+
+  const transform = PerspectiveTransform.quadToQuad(
+    0, 0, d, 0, d, d, 0, d,
+    tl.x, tl.y, tr.x, tr.y, br.x, br.y, bl.x, bl.y
+  );
+
+  return voting
+    ? sampleGridVoting(image, d, d, transform)
+    : sampleGrid(image, d, d, transform);
+}