@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
JavaScript
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) };
}