UNPKG

@forgesworn/qr

Version:

Dependency-free QR code encoder and decoder for TypeScript, browsers, workers and Node, with optional WebAssembly and tracked camera scanning.

819 lines (818 loc) • 39.4 kB
import { imageLayout } from './image.js'; import { binarise, invert, invertLuminance, reductions, thresholds, toLuminance } from './binarise.js'; import { edgesOf, estimateSize, finderTriples, findFinders, locate, locateCorners } from './locate.js'; import { agreement, agreementRead, singleFormatAgreement, formatAgrees, keep, SECOND_LOOKS, secondLook, sized, readQuadraticMesh } from './refine.js'; import { agreedVersion, readSymbol, curvatureHeader, versionPeerHeader } from './symbol.js'; import { FORMAT_COORDS } from './encode.js'; const MAX_TRIPLES = 6; /** * Finds and reads one QR code in a picture. Returns undefined when no * readable code is found. */ export function decode(image, options = {}) { return decodeCounted(image, options); } /** Counts search work for tests; optional internal storage leaves ordinary decode() stateless. */ export function decodeCounted(image, options = {}, work, workspace) { const { width, height, stride, channels, inversion } = imageLayout(image, options); let storage; if (workspace) { if (!workspace.luminance || workspace.luminance.length < width * height) workspace.luminance = new Uint8Array(width * height); storage = workspace.luminance.subarray(0, width * height); } const luminance = toLuminance(image.data, width, height, channels, stride, storage); const budget = { maps: MAX_MAPS, second: SECOND_LOOKS, here: MAX_MAPS, invertedFallback: false, uniform: false, hints: [], curvature: [], meshGrids: [] }; const found = look(luminance, inversion, 1, budget, work); if (found) return found; if (budget.uniform) return undefined; // Nothing read at full size: the picture shrunk, coarse to fine, for codes // whose modules are large or carry texture or scan lines (decoder step 9). const shrunk = reductions(luminance); for (const f of REDUCTIONS) { if (Math.floor(width / f) < MIN_REDUCED || Math.floor(height / f) < MIN_REDUCED) continue; // With no maps left no size can read, nor keep a candidate for a second look. if (budget.maps === 0) break; budget.here = REDUCED_MAPS; const reduced = look(shrunk(f), inversion, f, budget, work); if (reduced) return reduced; } let inverse; let inverseCurvature; if (inversion !== 'normal' && budget.maps > 0 && budget.invertedFallback) { budget.here = REDUCED_MAPS; inverse = invertLuminance(luminance); inverseCurvature = []; budget.alternateInverse = inverseCurvature; const fallback = look(inverse, 'normal', 1, budget, work, true, inverseCurvature, true); if (fallback) return { ...fallback, inverted: true }; const inverseShrunk = reductions(inverse); for (const f of REDUCTIONS) { if (budget.maps === 0 || budget.here === 0) break; if (Math.floor(width / f) < MIN_REDUCED || Math.floor(height / f) < MIN_REDUCED) continue; const reduced = look(inverseShrunk(f), 'normal', f, budget, work, true, undefined, true); if (reduced) return { ...reduced, inverted: true }; } } const recovered = recoverVersion(luminance, budget, work); if (recovered) return recovered; const overflow = recoverOverflow(luminance, budget, work); if (overflow) return overflow; const curved = recoverCurvature(luminance, budget, work); if (curved) return curved; if (inverse && inverseCurvature) { const recovered = recoverCurvature(inverse, budget, work, inverseCurvature, true); if (recovered) return { ...recovered, inverted: true }; } const meshResult = recoverMeshGrids(budget); if (meshResult) return meshResult; const unattempted = recoverUnattemptedCurvature(luminance, inverse, budget, inverseCurvature, work); if (unattempted) return unattempted; const conflict = recoverHeaderConflict(luminance, inverse, budget, work); if (conflict) return conflict; const ordinary = recoverOrdinaryCurvature(luminance, inverse, budget, inverseCurvature, work); if (ordinary) return ordinary; const versionPeer = recoverVersionPeer(luminance, inverse, budget, work); if (versionPeer) return versionPeer; const alternate = recoverAlternateGrid(budget); if (alternate) return alternate; const rediscovered = recoverRediscoveredGrid(budget); if (rediscovered) return rediscovered; const selectedMesh = recoverRediscoveredGrid(budget, true); if (selectedMesh) return selectedMesh; return recoverQuadraticMesh(luminance, inverse, budget); } /** Maps sampled a frame, at most, at every size together: four passes, six triples, five sizes, six maps a size. */ const MAX_MAPS = 4 * MAX_TRIPLES * 5 * 6; /** The reduced-size pass's factors, coarse to fine. */ const REDUCTIONS = [8, 4, 2]; /** A reduced picture narrower or shorter than this cannot hold a version 1 symbol at a pixel a module. */ const MIN_REDUCED = 21; /** Maps each reduced size may take, out of what the frame has left. */ const REDUCED_MAPS = 30; function meshCollector(budget, candidate, f, publicInverse = false) { if (budget.meshGrids.length >= SECOND_LOOKS) return undefined; return modules => { if (budget.meshGrids.length >= SECOND_LOOKS) return; budget.meshGrids.push({ modules, size: candidate.location.size, ecc: candidate.ecc, mask: candidate.mask, mirrored: candidate.mirrored, inverted: publicInverse || candidate.inverted, location: where(candidate.location, f) }); }; } /** Same attempted maps, validated only after all earlier return paths fail. */ function recoverMeshGrids(budget) { for (const item of budget.meshGrids) { const { modules, size, mirrored, inverted, ecc, mask, location } = item; const read = mirrored ? (x, y) => modules[x * size + y] === 1 : (x, y) => modules[y * size + x] === 1; if (!formatAgrees(read, size, ecc, mask)) continue; const result = readSymbol(read, size); if (result && result.ecc === ecc && result.mask === mask) return { ...result, mirrored, inverted, location }; } return undefined; } /** * The ordinary search in each polarity, then the second look, on a picture * shrunk by `f` (1 for the picture itself). At reduced size a read counts * only if its format copies agree on its level and mask, and locations are * given in full-picture coordinates. */ function look(luminance, inversion, f, budget, work, strictOverride = false, inverseCurvature, publicInverse = false) { const levels = thresholds(luminance); if (f === 1 && !strictOverride) { budget.invertedFallback = levels.invertedFallback; budget.uniform = levels.uniform; } if (levels.uniform) return undefined; const bits = binarise(luminance, levels); const strict = f > 1 || strictOverride; const candidates = []; // The inverse changes colour where the picture does, so one set of edges serves both. const edges = edgesOf(bits); if (inversion !== 'inverted') { const found = search(bits, edges, false, candidates, budget, strict, f, work, f === 1 && !strictOverride, f === 1 ? inverseCurvature : undefined); if (found) return found; } if (inversion !== 'normal') { const found = search(invert(bits), edges, true, candidates, budget, strict, f, work, f === 1 && !strictOverride); if (found) return found; } // Nothing read: look again at the few maps whose format copies agreed. if (candidates.length === 0 || budget.second === 0) return undefined; for (const candidate of candidates) { if (budget.second === 0) break; budget.second--; if (work) work.second++; rememberAttempt(budget, candidate, f, publicInverse); const result = secondLook(luminance, levels, candidate, work, strict, false, meshCollector(budget, candidate, f, publicInverse)); if (result) return { ...result, mirrored: candidate.mirrored, inverted: candidate.inverted, location: where(candidate.location, f) }; } return undefined; } /** * A location in full-picture coordinates. Picture coordinates are continuous, * pixel i covering [i, i + 1), so a point x in a picture shrunk by f lies at x * f. */ function where(location, f) { if (f === 1) { return { topLeft: location.topLeft, topRight: location.topRight, bottomLeft: location.bottomLeft, alignment: location.alignment, }; } const up = (p) => ({ x: p.x * f, y: p.y * f }); return { topLeft: up(location.topLeft), topRight: up(location.topRight), bottomLeft: up(location.bottomLeft), alignment: location.alignment === undefined ? undefined : up(location.alignment), }; } function search(image, edges, inverted, candidates, budget, strict, f, work, collectHints = false, inverseCurvature) { if (budget.maps === 0 || budget.here === 0) return undefined; // A strict pass first; a looser one for blurred or small codes. for (const tolerance of [0.5, 0.8]) { const ranked = finderTriples(image, findFinders(image, tolerance, work, edges)); const triples = ranked.slice(0, MAX_TRIPLES); for (const triple of triples) { const first = locate(image, triple, undefined, work, edges); // An estimate past version 40 by no more than the retries reach still // tries the sizes of 177 or less among them. const size = first.length > 0 ? first[0].size : over(image, triple); if (size === undefined) continue; // The size estimate can be a version out; try the neighbours too. for (const delta of [0, -4, 4, -8, 8]) { for (const location of delta === 0 ? first : locate(image, triple, size + delta, work, edges)) { if (budget.maps === 0 || budget.here === 0) return undefined; budget.maps--; budget.here--; if (work) { work.maps++; if (f > 1) work.reduced = (work.reduced ?? 0) + 1; } const result = read(image, location, inverted, candidates, strict, f, collectHints ? budget.hints : undefined, triple, collectHints ? budget.curvature : inverseCurvature, collectHints || inverseCurvature ? budget : undefined, inverseCurvature !== undefined); if (result) return result; if (budget.maps === 0 || budget.here === 0) return undefined; } } } if (collectHints && ranked.length > MAX_TRIPLES) { ; (budget.overflow ??= []).push({ ranked, inverted }); } } return undefined; } /** The size estimate when it is past 177 by at most the retries' 8; otherwise undefined. */ function over(image, triple) { const size = estimateSize(image, triple); return size !== undefined && size > 177 && size <= 177 + 8 ? size : undefined; } function read(image, location, inverted, candidates, strict, f, hints, triple, curvature, conflictBudget, inverseLuminance = false) { const { size, project, matrix } = location; const modules = new Uint8Array(size * size); modules.fill(2); // Unsampled; projected light and dark modules are 0 and 1. let sample; if (matrix) { // project(x, y), written out so that no point is made for each module. const [m0, m1, m2, m3, m4, m5, m6, m7, m8] = matrix; const { data, width, height } = image; sample = (x, y) => { const index = y * size + x; if (modules[index] !== 2) return modules[index] === 1; const v = y + 0.5; const u = x + 0.5; const w = m6 * u + m7 * v + m8; const px = Math.floor((m0 * u + m1 * v + m2) / w); const py = Math.floor((m3 * u + m4 * v + m5) / w); const value = px >= 0 && py >= 0 && px < width && py < height ? data[py * width + px] : 0; modules[index] = value; return value === 1; }; } else { sample = (x, y) => { const index = y * size + x; if (modules[index] !== 2) return modules[index] === 1; const p = project(x, y); const px = Math.floor(p.x); const py = Math.floor(p.y); const value = px >= 0 && py >= 0 && px < image.width && py < image.height ? image.data[py * image.width + px] : 0; modules[index] = value; return value === 1; }; } if (strict && !agreementRead(sample, size)) { // The inverse-luminance fallback keeps its ordinary two-copy gate. A map // with an exact version anchor may still qualify for deferred refinement. if (curvature) keepCurvature(curvature, location, inverted, sample, conflictBudget, inverseLuminance); return undefined; } const straightRead = sample; const straight = readSymbol(straightRead, size); if (straight) { // At reduced size, a read whose format copies do not agree on its level and mask is no read. if (strict && !formatAgrees(straightRead, size, straight.ecc, straight.mask)) return undefined; return { ...straight, mirrored: false, inverted, location: where(location, f) }; } const mirroredRead = (x, y) => sample(y, x); const mirrored = readSymbol(mirroredRead, size); if (mirrored) { if (strict && !formatAgrees(mirroredRead, size, mirrored.ecc, mirrored.mask)) return undefined; return { ...mirrored, mirrored: true, inverted, location: where(location, f) }; } // A version mismatch can stop either symbol read before its format is read. // Populate both orientations before checking the candidate for a second look. for (let i = 0; i < 15; i++) { const [x, y] = FORMAT_COORDS[i]; sample(x, y); sample(y, x); const sx = i < 8 ? size - 1 - i : 8; const sy = i < 8 ? 8 : size - 7 + (i - 8); sample(sx, sy); sample(sy, sx); } if (curvature) keepCurvature(curvature, location, inverted, sample, conflictBudget, inverseLuminance); const agreed = agreement(modules, size); if (agreed && sized(modules, size, agreed.mirrored)) keep(candidates, { location, inverted, ...agreed }); if (agreed && hints && triple && hints.length < SECOND_LOOKS) { const version = agreedVersion(agreed.mirrored ? mirroredRead : straightRead, size); if (version !== undefined && 17 + 4 * version !== size) { const target = 17 + 4 * version; const duplicate = hints.some(h => h.size === target && h.inverted === inverted && h.triple.every((p, i) => p.x === triple[i].x && p.y === triple[i].y)); if (!duplicate) hints.push({ triple, size: target, inverted }); } } return undefined; } /** Retains header-qualified maps within one luminance basis, never mixing polarity-specific thresholds. */ function keepCurvature(candidates, location, inverted, sample, conflictBudget, inverseLuminance = false) { const { size, matrix } = location; for (const mirrored of [false, true]) { // One slot: first strong (0/1 errors) wins; first weak (2 errors) is kept // only until a strong candidate appears. Normal curvature collection never stops. const allowConflict = conflictBudget !== undefined && matrix !== undefined && (conflictBudget.conflict === undefined || conflictBudget.conflict.candidate.distance === 2); const read = mirrored ? (x, y) => sample(y, x) : sample; const header = curvatureHeader(read, size, allowConflict); if (!header) { // Existing curvature and format-conflict ranking is unchanged. Only a // rejected map can fill the first version-peer slot, across both bases. if (conflictBudget && matrix && !conflictBudget.versionPeer) { const peer = versionPeerHeader(read, size); if (peer) conflictBudget.versionPeer = { candidate: { location, inverted, mirrored, ...peer }, inverseLuminance, }; } continue; } if (header.conflict) { if (conflictBudget && (!conflictBudget.conflict || header.distance <= 1)) { const candidate = { location, inverted, mirrored, ecc: header.ecc, mask: header.mask, distance: header.distance }; conflictBudget.conflict = { candidate, inverseLuminance }; } continue; } const duplicate = candidates.some(c => c.inverted === inverted && c.mirrored === mirrored && c.ecc === header.ecc && c.mask === header.mask && c.location.size === size && c.location.matrix && matrix && c.location.matrix.every((v, i) => v === matrix[i])); if (!duplicate) keep(candidates, { location, inverted, mirrored, ...header }); } } /** Evidence-directed retries run only after every existing search and second look has failed. */ function recoverVersion(luminance, budget, work) { if (budget.hints.length === 0 || budget.maps === 0) return undefined; const levels = thresholds(luminance); const bits = binarise(luminance, levels); const edges = edgesOf(bits); let inverse; const candidates = []; let remaining = REDUCED_MAPS; for (const hint of budget.hints) { if (budget.maps === 0 || remaining === 0) break; const image = hint.inverted ? (inverse ??= invert(bits)) : bits; for (const location of locate(image, hint.triple, hint.size, work, edges)) { if (budget.maps === 0 || remaining === 0) break; budget.maps--; remaining--; if (work) work.maps++; const result = read(image, location, hint.inverted, candidates, true, 1); if (result) return result; } } // A queued map can still recover after the ordinary map allowance runs out. for (const candidate of candidates) { if (budget.second === 0) break; budget.second--; if (work) work.second++; rememberAttempt(budget, candidate, 1, false); const result = secondLook(luminance, levels, candidate, work, true, false, meshCollector(budget, candidate, 1)); if (result) return { ...result, mirrored: candidate.mirrored, inverted: candidate.inverted, location: where(candidate.location, 1) }; } return undefined; } /** A late, evidence-gated probe of the already-ranked full-size overflow. */ function recoverOverflow(luminance, budget, work) { if (!budget.overflow || budget.maps === 0) return undefined; const levels = thresholds(luminance); const bits = binarise(luminance, levels); const edges = edgesOf(bits); let inverse; let remaining = REDUCED_MAPS; const candidates = []; const seen = []; const admitted = []; for (const group of budget.overflow) { if (budget.maps === 0 || remaining === 0) break; const image = group.inverted ? (inverse ??= invert(bits)) : bits; for (let index = MAX_TRIPLES; index < group.ranked.length; index++) { if (budget.maps === 0 || remaining === 0) break; const triple = group.ranked[index]; if (seen.some(s => s.inverted === group.inverted && s.triple.every((p, i) => p.x === triple[i].x && p.y === triple[i].y))) continue; seen.push({ triple, inverted: group.inverted }); const probes = locateCorners(image, triple, undefined, edges); for (const probe of probes) { if (budget.maps === 0 || remaining === 0) break; budget.maps--; remaining--; if (work) work.maps++; const sample = (x, y) => { const p = probe.project(x, y); const px = Math.floor(p.x), py = Math.floor(p.y); return px >= 0 && py >= 0 && px < image.width && py < image.height && image.data[py * image.width + px] === 1; }; const format = agreementRead(sample, probe.size); if (!format) continue; const version = agreedVersion(format.mirrored ? (x, y) => sample(y, x) : sample, probe.size); if (version === undefined) continue; const target = 17 + 4 * version; if (budget.maps === 0 || remaining === 0) break; if (admitted.some(a => a.inverted === group.inverted && a.target === target && a.triple.every((p, i) => p.x === triple[i].x && p.y === triple[i].y))) continue; admitted.push({ triple, inverted: group.inverted, target }); for (const location of locate(image, triple, target, work, edges)) { if (budget.maps === 0 || remaining === 0) break; budget.maps--; remaining--; if (work) work.maps++; const found = read(image, location, group.inverted, candidates, true, 1); if (found) return found; } } } } for (const candidate of candidates) { if (budget.second === 0) break; budget.second--; if (work) work.second++; rememberAttempt(budget, candidate, 1, false); const result = secondLook(luminance, levels, candidate, work, true, false, meshCollector(budget, candidate, 1)); if (result) return { ...result, mirrored: candidate.mirrored, inverted: candidate.inverted, location: where(candidate.location, 1) }; } return undefined; } /** * Reads a symbol from its module grid, `size` by `size`, row by row, truthy * for dark, with no quiet zone. Mirrored grids read too. */ export function decodeModules(modules, size) { if (modules.length < size * size) throw new RangeError('Fewer modules than size x size'); const at = (i) => Boolean(modules[i]); const straightRead = (x, y) => at(y * size + x); const straight = readSymbol(straightRead, size); if (straight) return { ...straight, mirrored: false }; const mirrored = readSymbol((x, y) => at(x * size + y), size); return mirrored ? { ...mirrored, mirrored: true } : undefined; } /** A final bounded retry of original maps anchored by an exact version word. */ function recoverCurvature(luminance, budget, work, candidates = budget.curvature, publicInverse = false) { if (candidates.length === 0 || budget.second === 0) return undefined; const levels = thresholds(luminance); for (const candidate of candidates) { if (budget.second === 0) break; budget.second--; if (work) work.second++; rememberAttempt(budget, candidate, 1, publicInverse, true); const result = alternateSecondLook(budget, publicInverse, luminance, levels, candidate, work, true, true, meshCollector(budget, candidate, 1, publicInverse)); if (result) return { ...result, mirrored: candidate.mirrored, inverted: candidate.inverted, location: where(candidate.location, 1) }; } return undefined; } /** Remembers the seven earlier attempts and their refinement phase; no storage on a direct read. */ function rememberAttempt(budget, candidate, factor, inverseLuminance, late = false) { const attempted = budget.attempted ??= []; if (attempted.length < SECOND_LOOKS + 3) attempted.push({ candidate, factor, inverseLuminance, late }); } /** Candidates are original locator homographies, never the temporary bent mesh. */ function alreadyAttempted(budget, candidate, inverseLuminance, late) { const matrix = candidate.location.matrix; return (budget.attempted ?? []).some(attempt => { if (attempt.factor !== 1 || attempt.inverseLuminance !== inverseLuminance || (late !== undefined && attempt.late !== late)) return false; const other = attempt.candidate; if (other.location.size !== candidate.location.size || other.mirrored !== candidate.mirrored || other.inverted !== candidate.inverted || other.ecc !== candidate.ecc || other.mask !== candidate.mask) return false; const previous = other.location.matrix; return !!matrix && !!previous && matrix.length === previous.length && matrix.every((value, i) => value === previous[i]); }); } /** * After every earlier success path fails, allow one previously unattempted * exact-version candidate. This is one extra attempt, not another queue pass. */ function recoverUnattemptedCurvature(luminance, inverse, budget, inverseCandidates, work) { if (budget.second !== 0) return undefined; for (const inverseLuminance of [false, true]) { const image = inverseLuminance ? inverse : luminance; const candidates = inverseLuminance ? inverseCandidates : budget.curvature; if (!image || !candidates) continue; for (const candidate of candidates) { // locate and locateCorners always supply matrices. Do not guess whether // arbitrary future nonlinear projection functions describe the same map. if (!candidate.location.matrix || alreadyAttempted(budget, candidate, inverseLuminance)) continue; if (work) work.second++; let modules; rememberAttempt(budget, candidate, 1, inverseLuminance, true); const payload = alternateSecondLook(budget, inverseLuminance, image, thresholds(image), candidate, work, true, true, grid => { modules = grid; }); const inverted = inverseLuminance || candidate.inverted; const location = where(candidate.location, 1); if (payload) return { ...payload, mirrored: candidate.mirrored, inverted, location }; if (modules) { const grid = modules, size = candidate.location.size; const read = candidate.mirrored ? (x, y) => grid[x * size + y] === 1 : (x, y) => grid[y * size + x] === 1; if (formatAgrees(read, size, candidate.ecc, candidate.mask)) { const result = readSymbol(read, size); if (result && result.ecc === candidate.ecc && result.mask === candidate.mask) return { ...result, mirrored: candidate.mirrored, inverted, location }; } } return undefined; } } return undefined; } /** * One final attempt at a map with an exact version anchor and a uniquely * stronger format copy. Conflicting formats exclude it from all earlier queues. */ function recoverHeaderConflict(luminance, inverse, budget, work) { const retained = budget.conflict; if (!retained) return undefined; const { candidate, inverseLuminance } = retained; const image = inverseLuminance ? inverse : luminance; if (!image) return undefined; if (work) work.second++; let modules; rememberAttempt(budget, candidate, 1, inverseLuminance, true); const payload = alternateSecondLook(budget, inverseLuminance, image, thresholds(image), candidate, work, true, true, grid => { modules = grid; }); const inverted = inverseLuminance || candidate.inverted; const location = where(candidate.location, 1); if (payload) return { ...payload, mirrored: candidate.mirrored, inverted, location }; if (modules) { const grid = modules, size = candidate.location.size; const read = candidate.mirrored ? (x, y) => grid[x * size + y] === 1 : (x, y) => grid[y * size + x] === 1; if (formatAgrees(read, size, candidate.ecc, candidate.mask)) { const result = readSymbol(read, size); if (result && result.ecc === candidate.ecc && result.mask === candidate.mask) return { ...result, mirrored: candidate.mirrored, inverted, location }; } } return undefined; } /** * An ordinary refinement does not include the late frozen-anchor pass. After * every earlier recovery fails, try that pass on the first retained map which * had only ordinary refinement. This is one attempt, even when it fails. */ function recoverOrdinaryCurvature(luminance, inverse, budget, inverseCandidates, work) { for (const inverseLuminance of [false, true]) { const image = inverseLuminance ? inverse : luminance; const candidates = inverseLuminance ? inverseCandidates : budget.curvature; if (!image || !candidates) continue; for (const candidate of candidates) { if (!candidate.location.matrix || !alreadyAttempted(budget, candidate, inverseLuminance, false) || alreadyAttempted(budget, candidate, inverseLuminance, true)) continue; if (work) work.second++; let modules; rememberAttempt(budget, candidate, 1, inverseLuminance, true); const payload = alternateSecondLook(budget, inverseLuminance, image, thresholds(image), candidate, work, true, true, grid => { modules = grid; }); const inverted = inverseLuminance || candidate.inverted; const location = where(candidate.location, 1); if (payload) return { ...payload, mirrored: candidate.mirrored, inverted, location }; if (modules) { const grid = modules, size = candidate.location.size; const read = candidate.mirrored ? (x, y) => grid[x * size + y] === 1 : (x, y) => grid[y * size + x] === 1; if (formatAgrees(read, size, candidate.ecc, candidate.mask)) { const result = readSymbol(read, size); if (result && result.ecc === candidate.ecc && result.mask === candidate.mask) return { ...result, mirrored: candidate.mirrored, inverted, location }; } } return undefined; } } return undefined; } /** * First version-peer map only, after all released recovery paths fail. Earlier * late queues reject this header class; the identity check remains defensive. * An ordinary attempt does not include the late frozen-anchor refinement. */ function recoverVersionPeer(luminance, inverse, budget, work) { const retained = budget.versionPeer; if (!retained) return undefined; const { candidate, inverseLuminance } = retained; if (alreadyAttempted(budget, candidate, inverseLuminance, true)) return undefined; const image = inverseLuminance ? inverse : luminance; if (!image) return undefined; if (work) work.second++; let modules; const payload = alternateSecondLook(budget, inverseLuminance, image, thresholds(image), candidate, work, true, true, grid => { modules = grid; }); const inverted = inverseLuminance || candidate.inverted; const location = where(candidate.location, 1); if (payload) return { ...payload, mirrored: candidate.mirrored, inverted, location }; if (modules) { const grid = modules, size = candidate.location.size; const read = candidate.mirrored ? (x, y) => grid[x * size + y] === 1 : (x, y) => grid[y * size + x] === 1; if (formatAgrees(read, size, candidate.ecc, candidate.mask)) { const result = readSymbol(read, size); if (result && result.ecc === candidate.ecc && result.mask === candidate.mask) return { ...result, mirrored: candidate.mirrored, inverted, location }; } } return undefined; } /** Refinement geometry excludes the orientation and format hypothesis. */ function sameAlternateGeometry(a, b) { const left = a.location.matrix, right = b.location.matrix; return a.location.size === b.location.size && a.inverted === b.inverted && !!left && !!right && left.length === right.length && left.every((value, i) => Number.isFinite(value) && value === right[i]); } function sameAlternateHypothesis(a, b) { return a.mirrored === b.mirrored && a.ecc === b.ecc && a.mask === b.mask; } /** Keep only the first eligible failed late grid; later invalidation never backfills. */ function alternateSecondLook(budget, inverseLuminance, ...args) { const candidate = args[2], pending = budget.alternateGrid; if (!budget.quadraticMesh) args[8] = mesh => { if (!budget.quadraticMesh) budget.quadraticMesh = { candidate, inverseLuminance, mesh }; }; // Only a slot selected during this synchronous call may receive its mesh. // Wrap an existing collector; never introduce sampling or backfill an old slot. const collectSelectedMesh = args[6]; if (collectSelectedMesh && !budget.rediscoveredGrid) args[6] = modules => { collectSelectedMesh(modules); if (budget.rediscoveredGrid) budget.rediscoveredGrid.mesh = modules; }; // Every full-size late call goes through here, including the eighth call // which is deliberately absent from the earlier seven-attempt ledger. if (pending && pending.inverseLuminance === inverseLuminance && sameAlternateGeometry(pending.candidate, candidate) && sameAlternateHypothesis(pending.candidate, candidate)) pending.lateAttempted = true; if (pending) { if (!budget.rediscoveredGrid) args[7] = modules => keepRediscoveredGrid(budget, inverseLuminance, candidate, modules); return secondLook(...args); } let selected; const collectMesh = args[6]; // Wrap only an existing collector: never introduce new mesh sampling. if (collectMesh) args[6] = modules => { collectMesh(modules); if (selected) selected.mesh = modules; }; args[7] = modules => { keepRediscoveredGrid(budget, inverseLuminance, candidate, modules); for (const inverse of [false, true]) { if (inverse !== inverseLuminance) continue; const candidates = inverse ? budget.alternateInverse : budget.curvature; if (!candidates) continue; for (const alternative of candidates) { if (!sameAlternateGeometry(candidate, alternative) || sameAlternateHypothesis(candidate, alternative) || alreadyAttempted(budget, alternative, inverse, true)) continue; selected = { candidate: alternative, inverseLuminance: inverse, final: modules, lateAttempted: false }; budget.alternateGrid = selected; return; } } }; return secondLook(...args); } /** Existing grids only, strictly validated after every previous return path. */ function recoverAlternateGrid(budget) { const retained = budget.alternateGrid; if (!retained || retained.lateAttempted) return undefined; const { candidate, inverseLuminance } = retained, size = candidate.location.size; for (const grid of [retained.final, retained.mesh]) { if (!grid) continue; const read = candidate.mirrored ? (x, y) => grid[x * size + y] === 1 : (x, y) => grid[y * size + x] === 1; if (!formatAgrees(read, size, candidate.ecc, candidate.mask)) continue; const result = readSymbol(read, size); if (result && result.ecc === candidate.ecc && result.mask === candidate.mask) return { ...result, mirrored: candidate.mirrored, inverted: inverseLuminance || candidate.inverted, location: where(candidate.location, 1) }; } return undefined; } /** Retain the first strict format rediscovery from an existing failed late grid. */ function keepRediscoveredGrid(budget, inverseLuminance, original, modules) { if (budget.rediscoveredGrid) return; const size = original.location.size; if (size < 45 || size > 177 || (size - 17) % 4 !== 0) return; for (const mirrored of [original.mirrored, !original.mirrored]) { const read = mirrored ? (x, y) => modules[x * size + y] === 1 : (x, y) => modules[y * size + x] === 1; const agreed = singleFormatAgreement(read, size); if (!agreed || (mirrored === original.mirrored && agreed.ecc === original.ecc && agreed.mask === original.mask)) continue; budget.rediscoveredGrid = { candidate: { ...original, ...agreed, mirrored }, inverseLuminance, modules }; return; } } /** Final grid first, then only its same-call mesh; neither read selects another hypothesis. */ function recoverRediscoveredGrid(budget, mesh = false) { const retained = budget.rediscoveredGrid; if (!retained) return undefined; const { candidate, inverseLuminance } = retained, modules = mesh ? retained.mesh : retained.modules; if (!modules) return undefined; const size = candidate.location.size; const read = candidate.mirrored ? (x, y) => modules[x * size + y] === 1 : (x, y) => modules[y * size + x] === 1; if (!formatAgrees(read, size, candidate.ecc, candidate.mask)) return undefined; const payload = readSymbol(read, size); if (!payload || payload.ecc !== candidate.ecc || payload.mask !== candidate.mask) return undefined; return { ...payload, mirrored: candidate.mirrored, inverted: inverseLuminance || candidate.inverted, location: where(candidate.location, 1) }; } /** The first fully measured sparse late mesh receives one terminal curved read. */ function recoverQuadraticMesh(luminance, inverse, budget) { const retained = budget.quadraticMesh; if (!retained) return undefined; const image = retained.inverseLuminance ? inverse : luminance; if (!image) return undefined; const result = readQuadraticMesh(image, retained.candidate, retained.mesh); if (!result) return undefined; return { ...result.payload, mirrored: result.mirrored, inverted: retained.inverseLuminance || retained.candidate.inverted, location: where(retained.candidate.location, 1) }; }