quadqr-js 1.2.0 → 1.4.2

package/dist/esm/vision.js

@@ -292,6 +292,31 @@ function detectFinderCandidates(binary, width, height, options = {}) {
   return clusterFinderCandidates(raw, minConfirmations);
 }
 
+function recoverFinderSetFromTwo(binary, width, height, strongFinders, detector = {}) {
+  if (strongFinders.length !== 2) return strongFinders;
+  const moduleMean = (strongFinders[0].moduleSize + strongFinders[1].moduleSize) / 2;
+  const loose = detectFinderCandidates(binary, width, height, {
+    toleranceScale: Math.max(1.45, (detector.toleranceScale ?? 1) * 1.35),
+    moduleSpreadLimit: Math.max(0.72, detector.moduleSpreadLimit ?? 0.45),
+    minConfirmations: 1
+  });
+
+  const extra = loose.filter((candidate) => {
+    const moduleRatio = Math.abs(candidate.moduleSize - moduleMean) / Math.max(candidate.moduleSize, moduleMean);
+    if (moduleRatio > 0.62) return false;
+    return strongFinders.every((known) =>
+      Math.hypot(candidate.x - known.x, candidate.y - known.y) > Math.max(moduleMean, known.moduleSize) * 5
+    );
+  }).slice(0, 12);
+
+  if (!extra.length) return strongFinders;
+  return strongFinders.concat(extra).sort((a, b) =>
+    (b.confirmations - a.confirmations) ||
+    (a.score - b.score) ||
+    (b.moduleSize - a.moduleSize)
+  );
+}
+
 function dot(a, b) {
   return a.x * b.x + a.y * b.y;
 }
@@ -304,9 +329,15 @@ function cross(a, b) {
   return a.x * b.y - a.y * b.x;
 }
 
-function chooseFinderTriples(candidates, maxTriples = 16) {
-  const top = candidates.slice(0, Math.min(candidates.length, 14));
+function chooseFinderTriples(candidates, maxTriples = 16, options = {}) {
+  const perspectiveRecovery = options.perspectiveRecovery === true;
+  const topLimit = perspectiveRecovery ? 18 : 14;
+  const top = candidates.slice(0, Math.min(candidates.length, topLimit));
   const triples = [];
+  const maxCornerCos = options.maxCornerCos ?? (perspectiveRecovery ? 0.84 : 0.55);
+  const maxModuleSpread = options.maxFinderModuleSpread ?? (perspectiveRecovery ? 0.78 : 0.5);
+  const maxLegRatio = options.maxFinderLegRatio ?? (perspectiveRecovery ? 3.6 : 2.1);
+  const minLegModules = options.minFinderLegModules ?? (perspectiveRecovery ? 7.5 : 10);
 
   for (let a = 0; a < top.length - 2; a++) {
     for (let b = a + 1; b < top.length - 1; b++) {
@@ -321,9 +352,9 @@ function chooseFinderTriples(candidates, maxTriples = 16) {
           let v = sub(bl, tl);
           let d1 = Math.hypot(u.x, u.y);
           let d2 = Math.hypot(v.x, v.y);
-          if (d1 < tl.moduleSize * 10 || d2 < tl.moduleSize * 10) continue;
+          if (d1 < tl.moduleSize * minLegModules || d2 < tl.moduleSize * minLegModules) continue;
           const cos = Math.abs(dot(u, v) / (d1 * d2));
-          if (cos > 0.55) continue;
+          if (cos > maxCornerCos) continue;
           if (cross(u, v) < 0) {
             [tr, bl] = [bl, tr];
             u = sub(tr, tl);
@@ -337,13 +368,26 @@ function chooseFinderTriples(candidates, maxTriples = 16) {
             Math.abs(tr.moduleSize - moduleMean),
             Math.abs(bl.moduleSize - moduleMean)
           ) / moduleMean;
-          if (moduleSpread > 0.5) continue;
+          if (moduleSpread > maxModuleSpread) continue;
           const legRatio = Math.max(d1, d2) / Math.min(d1, d2);
-          if (legRatio > 2.1) continue;
+          if (legRatio > maxLegRatio) continue;
           const area = Math.abs(cross(u, v));
           const confirmScore = tl.confirmations + tr.confirmations + bl.confirmations;
-          const score = area / (1 + cos * 8 + moduleSpread * 5 + Math.max(0, legRatio - 1) * 2) + confirmScore * 100;
-          triples.push({ tl, tr, bl, moduleMean, score, orthogonality: 1 - cos });
+          const recoveryPenalty = perspectiveRecovery
+            ? 1 + Math.max(0, cos - 0.55) * 7 + Math.max(0, moduleSpread - 0.5) * 5 + Math.max(0, legRatio - 2.1) * 2
+            : 1;
+          const score = area / ((1 + cos * 8 + moduleSpread * 5 + Math.max(0, legRatio - 1) * 2) * recoveryPenalty) + confirmScore * 100;
+          triples.push({
+            tl,
+            tr,
+            bl,
+            moduleMean,
+            moduleSpread,
+            legRatio,
+            score,
+            orthogonality: 1 - cos,
+            perspectiveRecovery
+          });
         }
       }
     }
@@ -374,6 +418,14 @@ function alignmentTemplateValue(pattern, r, c) {
   return alignmentPatternIsBlack(pattern, r, c) ? 1 : 0;
 }
 
+const ALIGNMENT_SUBCELL_PROBES = Object.freeze([
+  Object.freeze([0, 0]),
+  Object.freeze([-0.32, 0]),
+  Object.freeze([0.32, 0]),
+  Object.freeze([0, -0.32]),
+  Object.freeze([0, 0.32])
+]);
+
 function alignmentScore(binary, width, height, center, basisU, basisV, scale, pattern) {
   let matches = 0;
   let total = 0;
@@ -391,7 +443,31 @@ function alignmentScore(binary, width, height, center, basisU, basisV, scale, pa
   return total ? matches / total : 0;
 }
 
-function searchAlignment(binary, width, height, triple, version) {
+function preciseAlignmentScore(binary, width, height, center, basisU, basisV, scale, pattern) {
+  let matches = 0;
+  let total = 0;
+  const radius = alignmentPatternRadius(pattern);
+  for (let r = -radius; r <= radius; r++) {
+    for (let c = -radius; c <= radius; c++) {
+      const expected = alignmentTemplateValue(pattern, r, c);
+      // Centre-only alignment scoring has a broad plateau: a candidate can be
+      // wrong by almost half a module while every centre still lands in the
+      // correct solid tile. This denser score is reserved for the slow recovery
+      // path, where Triangle16 needs sub-module geometry precision.
+      for (const [du, dv] of ALIGNMENT_SUBCELL_PROBES) {
+        const x = center.x + basisU.x * (c + du) * scale + basisV.x * (r + dv) * scale;
+        const y = center.y + basisU.y * (c + du) * scale + basisV.y * (r + dv) * scale;
+        const value = sampleBinaryAt(binary, width, height, x, y);
+        if (value === null) continue;
+        total++;
+        if (value === expected) matches++;
+      }
+    }
+  }
+  return total ? matches / total : 0;
+}
+
+function searchAlignment(binary, width, height, triple, version, options = {}) {
   const size = sizeForVersion(version);
   const separation = size - 7;
   const basisU = {
@@ -410,24 +486,158 @@ function searchAlignment(binary, width, height, triple, version) {
     y: triple.tl.y + basisU.y * (targetX - 3.5) + basisV.y * (targetY - 3.5)
   };
 
-  let best = { score: 0, center: predicted, scale: 1 };
-  const offsets = [-2.5, -1.5, -0.75, 0, 0.75, 1.5, 2.5];
-  const scales = [0.72, 0.85, 1, 1.15, 1.3];
+  const precise = options.preciseAlignment === true;
+  const localScoreFn = precise ? preciseAlignmentScore : alignmentScore;
+  const localOffsets = precise
+    ? [-2.5, -1.5, -0.75, -0.5, -0.25, 0, 0.25, 0.5, 0.75, 1.5, 2.5]
+    : [-2.5, -1.5, -0.75, 0, 0.75, 1.5, 2.5];
+  const finderSizes = [triple.tl.moduleSize, triple.tr.moduleSize, triple.bl.moduleSize];
+  const finderMin = Math.max(0.01, Math.min(...finderSizes));
+  const finderMax = Math.max(...finderSizes);
+  const finderScaleRatio = finderMax / finderMin;
+  const inferredTargetScale = clamp(
+    Math.sqrt(
+      Math.max(0.2, triple.tr.moduleSize / Math.max(0.01, triple.tl.moduleSize)) *
+      Math.max(0.2, triple.bl.moduleSize / Math.max(0.01, triple.tl.moduleSize))
+    ),
+    0.58,
+    1.75
+  );
+  const localScales = [...new Set([
+    0.72, 0.85, 1, 1.15, 1.3,
+    Number(inferredTargetScale.toFixed(3)),
+    Number((inferredTargetScale * 0.88).toFixed(3)),
+    Number((inferredTargetScale * 1.12).toFixed(3))
+  ])].filter((scale) => scale >= 0.52 && scale <= 1.9);
+
+  const centerAt = (offsetU, offsetV) => ({
+    x: predicted.x + basisU.x * offsetU + basisV.x * offsetV,
+    y: predicted.y + basisU.y * offsetU + basisV.y * offsetV
+  });
+  let best = { score: 0, center: predicted, scale: 1, offsetU: 0, offsetV: 0, broadSearch: false };
 
-  for (const ou of offsets) {
-    for (const ov of offsets) {
-      const center = {
-        x: predicted.x + basisU.x * ou + basisV.x * ov,
-        y: predicted.y + basisU.y * ou + basisV.y * ov
-      };
-      for (const scale of scales) {
-        const score = alignmentScore(binary, width, height, center, basisU, basisV, scale, target);
-        if (score > best.score) best = { score, center, scale };
+  const evaluateIntoBest = (offsetU, offsetV, scales, scoreFn, broadSearch = false) => {
+    const center = centerAt(offsetU, offsetV);
+    for (const scale of scales) {
+      const score = scoreFn(binary, width, height, center, basisU, basisV, scale, target);
+      if (score > best.score) best = { score, center, scale, offsetU, offsetV, broadSearch };
+    }
+  };
+
+  for (const ou of localOffsets) {
+    for (const ov of localOffsets) evaluateIntoBest(ou, ov, localScales, localScoreFn, false);
+  }
+
+  // A three-finder affine extrapolation becomes increasingly wrong as the
+  // symbol tilts away from the camera. Under strong yaw/pitch the primary
+  // bottom-right alignment marker can move 8-15 modules away from the affine
+  // prediction even though all three finder patterns remain strong. Use a
+  // bounded coarse-to-fine search only when the locator geometry signals that
+  // projective foreshortening is present.
+  const cornerSkew = Math.max(0, 1 - (triple.orthogonality ?? 1));
+  const projectiveSignal = Math.max(
+    Math.max(0, finderScaleRatio - 1),
+    Math.max(0, (triple.moduleSpread ?? 0) * 1.25),
+    cornerSkew * 0.75
+  );
+  const broadEnabled = options.perspectiveAlignmentRecovery !== false && (
+    options.perspectiveRecovery === true ||
+    projectiveSignal >= (options.perspectiveAlignmentSignalThreshold ?? 0.32)
+  );
+
+  if (broadEnabled && best.score < (options.perspectiveAlignmentEarlyAccept ?? 0.78)) {
+    const radius = clamp(
+      Number(options.perspectiveAlignmentRadius ?? (3.5 + projectiveSignal * 17)),
+      4,
+      options.perspectiveAlignmentMaxRadius ?? 17
+    );
+    const coarseStep = radius > 12 ? 3 : radius > 8 ? 2.5 : 2;
+    const coarseScales = [...new Set([
+      Number((inferredTargetScale * 0.78).toFixed(3)),
+      Number((inferredTargetScale * 0.92).toFixed(3)),
+      Number(inferredTargetScale.toFixed(3)),
+      Number((inferredTargetScale * 1.10).toFixed(3)),
+      Number((inferredTargetScale * 1.28).toFixed(3)),
+      0.68, 0.82, 1, 1.18, 1.38, 1.58
+    ])].filter((scale) => scale >= 0.48 && scale <= 2.05);
+    const coarseOffsets = [0];
+    for (let offset = coarseStep; offset <= radius + 0.001; offset += coarseStep) {
+      coarseOffsets.push(offset, -offset);
+    }
+    if (!coarseOffsets.some((value) => Math.abs(Math.abs(value) - radius) < 0.35)) {
+      coarseOffsets.push(radius, -radius);
+    }
+
+    const seeds = [];
+    for (const ou of coarseOffsets) {
+      for (const ov of coarseOffsets) {
+        if (Math.abs(ou) <= 2.75 && Math.abs(ov) <= 2.75) continue;
+        const center = centerAt(ou, ov);
+        let seedScore = 0;
+        let seedScale = 1;
+        // Keep the coarse pass cheap. Fine refinement below uses the denser
+        // sub-cell alignment score to reject data-cell lookalikes.
+        for (const scale of coarseScales) {
+          const score = alignmentScore(binary, width, height, center, basisU, basisV, scale, target);
+          if (score > seedScore) {
+            seedScore = score;
+            seedScale = scale;
+          }
+        }
+        seeds.push({ score: seedScore, scale: seedScale, offsetU: ou, offsetV: ov });
+      }
+    }
+    seeds.sort((a, b) => b.score - a.score);
+
+    let broadBest = null;
+    const fineSeeds = seeds.slice(0, options.perspectiveAlignmentFineSeeds ?? 6);
+    const fineOffsets = [-1.25, -0.75, -0.4, 0, 0.4, 0.75, 1.25];
+    for (const seed of fineSeeds) {
+      const fineScales = [...new Set([
+        Number((seed.scale * 0.86).toFixed(3)),
+        Number((seed.scale * 0.94).toFixed(3)),
+        Number(seed.scale.toFixed(3)),
+        Number((seed.scale * 1.06).toFixed(3)),
+        Number((seed.scale * 1.16).toFixed(3)),
+        Number(inferredTargetScale.toFixed(3)),
+        1.0, 1.15, 1.3
+      ])].filter((scale) => scale >= 0.46 && scale <= 2.1);
+      for (const du of fineOffsets) {
+        for (const dv of fineOffsets) {
+          const offsetU = seed.offsetU + du;
+          const offsetV = seed.offsetV + dv;
+          const center = centerAt(offsetU, offsetV);
+          for (const scale of fineScales) {
+            const score = preciseAlignmentScore(binary, width, height, center, basisU, basisV, scale, target);
+            if (!broadBest || score > broadBest.score) {
+              broadBest = { score, center, scale, offsetU, offsetV, broadSearch: true };
+            }
+          }
+        }
       }
     }
+
+    // The precise score probes each alignment module at several sub-cell
+    // positions, making it substantially harder for random payload cells to
+    // impersonate the primary reference. Prefer a strong projective candidate
+    // even if the cheap centre-only local score happened to be slightly higher.
+    if (broadBest && (
+      broadBest.score >= (options.perspectiveAlignmentPreciseThreshold ?? 0.80) ||
+      broadBest.score > best.score + 0.08
+    )) {
+      best = broadBest;
+    }
   }
 
-  return { ...best, basisU, basisV, predicted, target };
+  return {
+    ...best,
+    basisU,
+    basisV,
+    predicted,
+    target,
+    finderScaleRatio,
+    projectiveSignal
+  };
 }
 
 function projectedAlignmentScore(binary, width, height, homography, pattern) {
@@ -464,6 +674,183 @@ function scoreAlignmentGrid(binary, width, height, homography, version) {
   return { score, patternScores };
 }
 
+function localProjectiveBasis(homography, moduleX, moduleY) {
+  const center = projectPoint(homography, moduleX, moduleY);
+  const alongU = projectPoint(homography, moduleX + 1, moduleY);
+  const alongV = projectPoint(homography, moduleX, moduleY + 1);
+  return {
+    center,
+    basisU: { x: alongU.x - center.x, y: alongU.y - center.y },
+    basisV: { x: alongV.x - center.x, y: alongV.y - center.y }
+  };
+}
+
+function searchProjectedAlignment(binary, width, height, homography, pattern) {
+  const moduleX = pattern.col + 0.5;
+  const moduleY = pattern.row + 0.5;
+  const local = localProjectiveBasis(homography, moduleX, moduleY);
+  const moduleScale = Math.max(
+    0.5,
+    (Math.hypot(local.basisU.x, local.basisU.y) + Math.hypot(local.basisV.x, local.basisV.y)) / 2
+  );
+  const offsets = [-1, -0.5, 0, 0.5, 1];
+  const scales = [0.88, 1, 1.12];
+  let best = {
+    score: projectedAlignmentScore(binary, width, height, homography, pattern),
+    center: local.center,
+    scale: 1,
+    offsetU: 0,
+    offsetV: 0,
+    displacementModules: 0
+  };
+
+  for (const offsetU of offsets) {
+    for (const offsetV of offsets) {
+      const center = {
+        x: local.center.x + local.basisU.x * offsetU + local.basisV.x * offsetV,
+        y: local.center.y + local.basisU.y * offsetU + local.basisV.y * offsetV
+      };
+      for (const scale of scales) {
+        const score = alignmentScore(
+          binary,
+          width,
+          height,
+          center,
+          local.basisU,
+          local.basisV,
+          scale,
+          pattern
+        );
+        if (score > best.score) {
+          best = {
+            score,
+            center,
+            scale,
+            offsetU,
+            offsetV,
+            displacementModules: Math.hypot(offsetU, offsetV),
+            displacementPixels: Math.hypot(offsetU, offsetV) * moduleScale
+          };
+        }
+      }
+    }
+  }
+
+  return best;
+}
+
+function refineHomographyWithAlignmentGrid(
+  binary,
+  width,
+  height,
+  initialHomography,
+  version,
+  sourcePoints,
+  destinationPoints,
+  initialGrid,
+  options = {}
+) {
+  const patterns = alignmentPatternCentersForVersion(version);
+  if (patterns.length <= 1 || options.alignmentRefinement === false) {
+    return {
+      homography: initialHomography,
+      grid: initialGrid,
+      refined: false,
+      points: []
+    };
+  }
+
+  const primary = patterns.find((pattern) => pattern.primary);
+  const secondaries = patterns.filter((pattern) => !pattern.primary);
+  const minimumScore = options.alignmentRefinePatternThreshold ?? 0.84;
+  const maxPoints = Math.max(1, Math.min(18, Math.round(options.alignmentRefineMaxPoints ?? 12)));
+  const candidates = [];
+
+  for (const pattern of secondaries) {
+    const found = searchProjectedAlignment(binary, width, height, initialHomography, pattern);
+    if (found.score < minimumScore) continue;
+    if (found.displacementModules > (options.alignmentRefineMaxDisplacement ?? 1.45)) continue;
+    candidates.push({ pattern, ...found });
+  }
+
+  if (!candidates.length) {
+    return { homography: initialHomography, grid: initialGrid, refined: false, points: [] };
+  }
+
+  // Prefer confident references, but retain spatial distribution so dense
+  // versions use alignment information across the entire matrix rather than
+  // allowing a cluster of nearby markers to dominate the fit.
+  candidates.sort((a, b) =>
+    (b.score - a.score) ||
+    ((b.pattern.row + b.pattern.col) - (a.pattern.row + a.pattern.col))
+  );
+  const selected = [];
+  for (const candidate of candidates) {
+    if (selected.length >= maxPoints) break;
+    const tooClose = selected.some((item) =>
+      Math.hypot(item.pattern.col - candidate.pattern.col, item.pattern.row - candidate.pattern.row) < 6
+    );
+    if (!tooClose || selected.length < 3) selected.push(candidate);
+  }
+  if (!selected.length) return { homography: initialHomography, grid: initialGrid, refined: false, points: [] };
+
+  const refinedSource = sourcePoints.slice();
+  const refinedDestination = destinationPoints.slice();
+  const weights = [4, 4, 4, 5];
+  const pointInfo = [];
+
+  for (const candidate of selected) {
+    refinedSource.push(candidate.center);
+    refinedDestination.push({
+      x: candidate.pattern.col + 0.5,
+      y: candidate.pattern.row + 0.5
+    });
+    // A 3x3 marker carries less evidence than the 5x5 primary and the three
+    // finder patterns, so it helps average geometry without overpowering them.
+    weights.push(0.8 + candidate.score * 1.7);
+    pointInfo.push({
+      row: candidate.pattern.row,
+      col: candidate.pattern.col,
+      score: candidate.score,
+      x: candidate.center.x,
+      y: candidate.center.y,
+      displacementModules: candidate.displacementModules
+    });
+  }
+
+  let refinedHomography;
+  try {
+    refinedHomography = computeHomographyLeastSquares(refinedSource, refinedDestination, weights);
+  } catch {
+    return { homography: initialHomography, grid: initialGrid, refined: false, points: [] };
+  }
+
+  const refinedGrid = scoreAlignmentGrid(binary, width, height, refinedHomography, version);
+  const primaryBefore = primary
+    ? projectedAlignmentScore(binary, width, height, initialHomography, primary)
+    : 1;
+  const primaryAfter = primary
+    ? projectedAlignmentScore(binary, width, height, refinedHomography, primary)
+    : 1;
+  const allowedGridDrop = options.alignmentRefineAllowedGridDrop ?? 0.006;
+  const allowedPrimaryDrop = options.alignmentRefineAllowedPrimaryDrop ?? 0.04;
+
+  if (
+    refinedGrid.score + allowedGridDrop < initialGrid.score ||
+    primaryAfter + allowedPrimaryDrop < primaryBefore
+  ) {
+    return { homography: initialHomography, grid: initialGrid, refined: false, points: [] };
+  }
+
+  return {
+    homography: refinedHomography,
+    grid: refinedGrid,
+    refined: true,
+    points: pointInfo,
+    initialGridScore: initialGrid.score
+  };
+}
+
 function solveLinearSystemFloat(matrix, vector) {
   const n = vector.length;
   const a = matrix.map((row, index) => row.slice().concat([vector[index]]));
@@ -505,6 +892,43 @@ export function computeHomography(sourcePoints, destinationPoints) {
   return [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7], 1];
 }
 
+function computeHomographyLeastSquares(sourcePoints, destinationPoints, weights = null) {
+  // Same destination -> source convention as computeHomography(), but accepts
+  // more than four correspondences and averages locator/alignment measurement
+  // noise. This is used only as a refinement after a valid four-point projective
+  // solution already exists.
+  assert(
+    sourcePoints.length === destinationPoints.length && sourcePoints.length >= 4,
+    "At least four matching point pairs are required."
+  );
+
+  const normal = Array.from({ length: 8 }, () => Array(8).fill(0));
+  const rhs = Array(8).fill(0);
+
+  const addEquation = (row, value, weight) => {
+    for (let i = 0; i < 8; i++) {
+      rhs[i] += row[i] * value * weight;
+      for (let j = 0; j < 8; j++) normal[i][j] += row[i] * row[j] * weight;
+    }
+  };
+
+  for (let i = 0; i < sourcePoints.length; i++) {
+    const u = destinationPoints[i].x;
+    const v = destinationPoints[i].y;
+    const x = sourcePoints[i].x;
+    const y = sourcePoints[i].y;
+    const weight = Math.max(0.05, Number(weights?.[i] ?? 1));
+    addEquation([u, v, 1, 0, 0, 0, -u * x, -v * x], x, weight);
+    addEquation([0, 0, 0, u, v, 1, -u * y, -v * y], y, weight);
+  }
+
+  // Tiny Tikhonov regularisation keeps near-degenerate noisy fits numerically
+  // stable without moving a normal QR-sized solution in any meaningful way.
+  for (let i = 0; i < 8; i++) normal[i][i] += 1e-9;
+  const h = solveLinearSystemFloat(normal, rhs);
+  return [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7], 1];
+}
+
 export function projectPoint(h, u, v) {
   const denominator = h[6] * u + h[7] * v + h[8];
   return {
@@ -518,7 +942,7 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
   const minVersion = options.minVersion ?? 1;
   const maxVersion = options.maxVersion ?? 40;
   const maxCandidates = options.maxCandidates ?? 8;
-  const triples = chooseFinderTriples(finders, 20);
+  const triples = chooseFinderTriples(finders, options.perspectiveRecovery ? 30 : 20, options);
   const geometries = [];
 
   for (const triple of triples) {
@@ -530,7 +954,7 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
     for (const item of versions) {
       const version = item.version;
       const size = sizeForVersion(version);
-      const alignment = searchAlignment(binary, width, height, triple, version);
+      const alignment = searchAlignment(binary, width, height, triple, version, options);
       if (alignment.score < (options.alignmentThreshold ?? 0.72)) continue;
 
       const alignmentTarget = alignment.target;
@@ -554,8 +978,34 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
         continue;
       }
 
-      const alignmentGrid = scoreAlignmentGrid(binary, width, height, homography, version);
-      if (alignmentGrid.score < (options.alignmentGridThreshold ?? 0.68)) continue;
+      const initialAlignmentGrid = scoreAlignmentGrid(binary, width, height, homography, version);
+      const alignmentGridThreshold = options.alignmentGridThreshold ?? 0.68;
+      const refinementFloor = Math.max(0, alignmentGridThreshold - (options.alignmentRefineCandidateMargin ?? 0.10));
+      const skipRefinementScore = options.alignmentRefineSkipScore ?? 0.985;
+      const refinement = (
+        initialAlignmentGrid.score >= refinementFloor &&
+        initialAlignmentGrid.score < skipRefinementScore
+      )
+        ? refineHomographyWithAlignmentGrid(
+            binary,
+            width,
+            height,
+            homography,
+            version,
+            src,
+            dest,
+            initialAlignmentGrid,
+            options
+          )
+        : {
+            homography,
+            grid: initialAlignmentGrid,
+            refined: false,
+            points: []
+          };
+      homography = refinement.homography;
+      const alignmentGrid = refinement.grid;
+      if (alignmentGrid.score < alignmentGridThreshold) continue;
 
       const versionPenalty = item.error / 4;
       const alignmentConfidence = 0.55 * alignment.score + 0.45 * alignmentGrid.score;
@@ -574,6 +1024,9 @@ function geometryCandidatesFromBinary(binary, width, height, finders, threshold,
           target: { row: alignmentTarget.row, col: alignmentTarget.col },
           patterns: alignmentGrid.patternScores.length,
           gridScore: alignmentGrid.score,
+          initialGridScore: refinement.initialGridScore ?? initialAlignmentGrid.score,
+          refined: refinement.refined,
+          refinementPoints: refinement.points,
           patternScores: alignmentGrid.patternScores
         },
         threshold,
@@ -645,19 +1098,22 @@ export function detectCodeGeometry(imageData, options = {}) {
   const maxCandidates = options.maxCandidates ?? 8;
 
   const evaluatePass = (pass, recovery = false) => {
-    const finders = detectFinderCandidates(pass.binary, width, height, pass.detector ?? {});
-    const geometries = geometryCandidatesFromBinary(
+    const detector = pass.detector ?? {};
+    const finders = detectFinderCandidates(pass.binary, width, height, detector);
+    const geometryOptions = {
+      ...options,
+      finderMethod: pass.finderMethod,
+      perspectiveRecovery: recovery || options.perspectiveRecovery === true,
+      alignmentThreshold: recovery ? 0.68 : 0.72,
+      alignmentGridThreshold: recovery ? 0.64 : 0.68
+    };
+    let geometries = geometryCandidatesFromBinary(
       pass.binary,
       width,
       height,
       finders,
       pass.threshold,
-      {
-        ...options,
-        finderMethod: pass.finderMethod,
-        alignmentThreshold: recovery ? 0.68 : 0.72,
-        alignmentGridThreshold: recovery ? 0.64 : 0.68
-      }
+      geometryOptions
     );
 
     pushFinderDiagnostic(
@@ -667,10 +1123,39 @@ export function detectCodeGeometry(imageData, options = {}) {
       finders,
       geometries
     );
+
+    // Dense codes under projective distortion can leave two finder patterns
+    // perfectly strong while the third is stretched enough to miss the normal
+    // 1:1:3:1:1 tolerance. Only in that very specific recovery state, run one
+    // bounded looser detector and let the normal three-finder geometry checks
+    // reject false data-cell lookalikes. The clean fast path is unchanged.
+    if (!geometries.length && recovery && finders.length === 2) {
+      const recoveredFinders = recoverFinderSetFromTwo(pass.binary, width, height, finders, detector);
+      if (recoveredFinders.length > 2) {
+        const finderMethod = `${pass.finderMethod}-two-finder-recovery`;
+        geometries = geometryCandidatesFromBinary(
+          pass.binary,
+          width,
+          height,
+          recoveredFinders,
+          pass.threshold,
+          { ...geometryOptions, finderMethod }
+        );
+        pushFinderDiagnostic(
+          { ...options, width, height, diagnosticLabel: `${options.diagnosticLabel ?? "perspective"}-two-finder` },
+          finderMethod,
+          pass.threshold,
+          recoveredFinders,
+          geometries
+        );
+        if (geometries.length) return { finders: recoveredFinders, geometries };
+      }
+    }
+
     return { finders, geometries };
   };
 
-  // Fast path stays exactly one grayscale + finder pass. No Auto Color, extra
+  // Fast path stays exactly one grayscale + finder pass. No QuadQR Auto Color, extra
   // thresholding, or luminance image is computed when a normal frame works.
   const valueInfo = buildBinary(imageData, { grayMode: "value" });
   const fast = evaluatePass({
@@ -682,12 +1167,44 @@ export function detectCodeGeometry(imageData, options = {}) {
   if (fast.geometries.length) return fast.geometries.slice(0, maxCandidates);
   if (options.finderRecovery === false) return [];
 
-  // Camera recovery #1: Photoshop Auto Color-style per-channel levels before
+  // If the clean threshold already found exactly two strong locators, try the
+  // bounded perspective-tolerant third-finder pass before any color processing.
+  // This is substantially cheaper than QuadQR Auto Color and targets the dense-code
+  // projective failure mode directly.
+  if (fast.finders.length === 2) {
+    const recoveredFinders = recoverFinderSetFromTwo(valueInfo.binary, width, height, fast.finders, {});
+    if (recoveredFinders.length > 2) {
+      const finderMethod = "rgb-value-otsu-two-finder-recovery";
+      const recoveredGeometries = geometryCandidatesFromBinary(
+        valueInfo.binary,
+        width,
+        height,
+        recoveredFinders,
+        valueInfo.threshold,
+        {
+          ...options,
+          finderMethod,
+          alignmentThreshold: 0.68,
+          alignmentGridThreshold: 0.64
+        }
+      );
+      pushFinderDiagnostic(
+        { ...options, width, height, diagnosticLabel: `${options.diagnosticLabel ?? "perspective"}-two-finder` },
+        finderMethod,
+        valueInfo.threshold,
+        recoveredFinders,
+        recoveredGeometries
+      );
+      if (recoveredGeometries.length) return recoveredGeometries.slice(0, maxCandidates);
+    }
+  }
+
+  // Camera recovery #1: QuadQR Auto Color per-channel levels before
   // finder thresholding. Live camera frames are usually much larger than the
   // QR itself, so a single global histogram can be dominated by dark room/UI
-  // pixels around the guide. Photoshop looked strong in the user's cropped
-  // sample because its statistics were effectively code-centric. We emulate
-  // that by trying a few center-weighted analysis windows, while still applying
+  // pixels around the guide. QuadQR keeps recovery deliberately code-centric
+  // by using center-weighted analysis windows so surrounding scene pixels do not
+  // dominate the correction, while still applying
   // each correction to the full frame so finder coordinates never move.
   const requestedInsets = Array.isArray(options.finderAutoColorAnalysisInsets)
     ? options.finderAutoColorAnalysisInsets
@@ -733,7 +1250,7 @@ export function detectCodeGeometry(imageData, options = {}) {
 
   // Camera recovery #2: bracket the raw value-channel threshold, then retain
   // the legacy luminance pass for unusual captures. These are only built after
-  // both the normal and Auto Color finder passes fail.
+  // both the normal and QuadQR Auto Color finder passes fail.
   const highThreshold = clamp(valueInfo.baseThreshold + 18, 8, 247);
   const lowThreshold = clamp(valueInfo.baseThreshold - 14, 8, 247);
   const recoveryPasses = [];
@@ -847,7 +1364,7 @@ function buildAutoColorLevels(imageData, options = {}) {
   // Camera recovery deliberately supports analysing only the central part of
   // the visible frame. A phone preview often contains very dark UI/screen
   // edges outside the code; letting those pixels define the black point makes
-  // an otherwise useful Auto Color pass far too weak.
+  // an otherwise useful QuadQR Auto Color pass far too weak.
   for (let index = 0; index < pixelCount; index += step) {
     const x = x0 + (index % analysisWidth);
     const y = y0 + Math.floor(index / analysisWidth);
@@ -872,8 +1389,8 @@ function buildAutoColorLevels(imageData, options = {}) {
   let highs;
   const outputHighlight = Number(options.outputHighlight);
   if (Number.isFinite(outputHighlight)) {
-    // Strong Photoshop-like camera mode. Photoshop Auto Color on the supplied
-    // warm camera sample does not stretch the brightest observed paper/white
+    // Strong QuadQR camera color-recovery mode. QuadQR Auto Color does not
+    // stretch the brightest observed paper/white
     // cells all the way to 255. Instead it anchors the per-channel shadow
     // points close to black while keeping the observed highlight around a
     // neutral mid-high value. That produces much darker structural black and
@@ -946,7 +1463,7 @@ function buildAutoToneContrastColorTransform(samples, options = {}) {
   const highlightFraction = clamp(options.highlightFraction ?? 0.14, 0.04, 0.35);
   const saturation = clamp(options.saturation ?? 1.12, 1, 1.5);
 
-  // Auto Color-style neutralization: use the brightest portion of the frame as
+  // QuadQR Auto Color-style neutralization: use the brightest portion of the frame as
   // a likely white reference. This is especially effective on warm/yellow
   // phone-camera frames where the blue channel is suppressed.
   const luminanceHistogram = new Uint32Array(256);
@@ -1088,6 +1605,68 @@ export function samplePerspectiveMatrix(imageData, homography, size, options = {
   return { rgbGrid };
 }
 
+/**
+ * Sample the two protected regions of every Triangle16 module.
+ *
+ * Triangle16 uses a fixed "/" diagonal. Samples are intentionally placed well
+ * inside the upper-left and lower-right triangles, away from the diagonal and
+ * module borders. This makes the decoder much less sensitive to antialiasing,
+ * blur, resampling and small homography errors than center sampling.
+ */
+function rgbSampleSpread(values, center) {
+  if (!values.length) return 0;
+  return values.reduce((sum, rgb) => sum + Math.hypot(
+    rgb.r - center.r,
+    rgb.g - center.g,
+    rgb.b - center.b
+  ), 0) / values.length;
+}
+
+export function samplePerspectiveTriangleMatrix(imageData, homography, size, options = {}) {
+  const triangleGrid = Array.from({ length: size }, () => new Array(size));
+  const mode = options.sampleMode ?? "cross";
+  const radius = options.highDensitySampleRadius ?? options.triangleSampleRadius ??
+    (mode === "median" ? 0.055 : 0.065);
+  const inset = Math.max(0.18, Math.min(0.34, Number(options.highDensitySampleInset ?? options.triangleSampleInset ?? 0.27)));
+  const offsetX = Number.isFinite(options.sampleOffsetX) ? options.sampleOffsetX : 0;
+  const offsetY = Number.isFinite(options.sampleOffsetY) ? options.sampleOffsetY : 0;
+  const sampler = mode === "median" ? robustProjectedSample : averageProjectedSample;
+  const side = Math.max(0.18, inset - 0.06);
+  const middle = Math.min(0.52, 0.50 - inset * 0.04);
+  const firstAnchors = [
+    [inset, inset],
+    [side, middle],
+    [middle, side]
+  ];
+  const secondAnchors = firstAnchors.map(([x, y]) => [1 - x, 1 - y]);
+
+  const sampleRegion = (c, r, anchors) => {
+    const values = anchors.map(([x, y]) => sampler(
+      imageData,
+      homography,
+      c + x + offsetX,
+      r + y + offsetY,
+      radius
+    ));
+    const rgb = robustRgb(values);
+    return { rgb, spread: rgbSampleSpread(values, rgb) };
+  };
+
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      const first = sampleRegion(c, r, firstAnchors);
+      const second = sampleRegion(c, r, secondAnchors);
+      triangleGrid[r][c] = {
+        first: first.rgb,
+        second: second.rgb,
+        firstSpread: first.spread,
+        secondSpread: second.spread
+      };
+    }
+  }
+  return { triangleGrid };
+}
+
 function meanRgb(values) {
   if (!values.length) throw new Error("No calibration samples available.");
   return values.reduce(
@@ -1284,6 +1863,43 @@ export function sampleAxisAlignedGrid(imageData, bounds, size, radiusRatio = 0.1
   return { rgbGrid, moduleWidth: moduleW, moduleHeight: moduleH };
 }
 
+export function sampleAxisAlignedTriangleGrid(imageData, bounds, size, radiusRatio = 0.065, insetRatio = 0.27) {
+  const moduleW = bounds.width / size;
+  const moduleH = bounds.height / size;
+  const inset = Math.max(0.18, Math.min(0.34, insetRatio));
+  const radius = Math.max(0, Math.min(moduleW, moduleH) * radiusRatio);
+  const triangleGrid = Array.from({ length: size }, () => new Array(size));
+  const side = Math.max(0.18, inset - 0.06);
+  const middle = Math.min(0.52, 0.50 - inset * 0.04);
+  const firstAnchors = [[inset, inset], [side, middle], [middle, side]];
+  const secondAnchors = firstAnchors.map(([x, y]) => [1 - x, 1 - y]);
+
+  const sampleRegion = (r, c, anchors) => {
+    const values = anchors.map(([x, y]) => sampleAverageAxis(
+      imageData,
+      bounds.x + (c + x) * moduleW,
+      bounds.y + (r + y) * moduleH,
+      radius
+    ));
+    const rgb = robustRgb(values);
+    return { rgb, spread: rgbSampleSpread(values, rgb) };
+  };
+
+  for (let r = 0; r < size; r++) {
+    for (let c = 0; c < size; c++) {
+      const first = sampleRegion(r, c, firstAnchors);
+      const second = sampleRegion(r, c, secondAnchors);
+      triangleGrid[r][c] = {
+        first: first.rgb,
+        second: second.rgb,
+        firstSpread: first.spread,
+        secondSpread: second.spread
+      };
+    }
+  }
+  return { triangleGrid, moduleWidth: moduleW, moduleHeight: moduleH };
+}
+
 export const visionInternals = Object.freeze({
   buildGray,
   otsuThreshold,