@scanmate/align 0.0.2

package/dist/index.esm.js

@@ -0,0 +1,1184 @@
+import { nextPowerOfTwo, fft2d, downscaleGray, estimateSkew, contentExtent, similarity, warpGray, correlation, rebase, isPlausible, multiply, translation, binarize, intersectionOverUnion, resizeGray, boxBlur, createRandom, gaussian, solve, smallestEigenvector, invert, reprojectionError, conjugateScale, decodeImage, inkMap, toGrayscale, warpRaster, decompose, encodeImage } from '@scanmate/ink';
+
+/**
+ * Correlate two equally sized images.
+ *
+ * Both are Hann-windowed first. Without it the FFT sees the frame edges as a
+ * hard discontinuity repeating forever, and that cross pattern in the spectrum
+ * can be a stronger signal than the page.
+ */
+function phaseCorrelate(a, b) {
+  if (a.width !== b.width || a.height !== b.height) throw new Error('phaseCorrelate needs two images of the same size');
+  const width = nextPowerOfTwo(a.width);
+  const height = nextPowerOfTwo(a.height);
+  const size = width * height;
+  const aRe = new Float64Array(size);
+  const aIm = new Float64Array(size);
+  const bRe = new Float64Array(size);
+  const bIm = new Float64Array(size);
+  const windowX = hann(a.width);
+  const windowY = hann(a.height);
+  for (let y = 0; y < a.height; y++) {
+    const src = y * a.width;
+    const dst = y * width;
+    for (let x = 0; x < a.width; x++) {
+      const w = windowX[x] * windowY[y];
+      aRe[dst + x] = a.data[src + x] * w;
+      bRe[dst + x] = b.data[src + x] * w;
+    }
+  }
+  fft2d(aRe, aIm, width, height);
+  fft2d(bRe, bIm, width, height);
+  // Cross-power spectrum of b against a, normalised to unit magnitude so that
+  // every frequency contributes its phase and nothing else.
+  for (let i = 0; i < size; i++) {
+    const re = bRe[i] * aRe[i] + bIm[i] * aIm[i];
+    const im = bIm[i] * aRe[i] - bRe[i] * aIm[i];
+    const magnitude = Math.hypot(re, im);
+    if (magnitude < 1e-12) {
+      bRe[i] = 0;
+      bIm[i] = 0;
+    } else {
+      bRe[i] = re / magnitude;
+      bIm[i] = im / magnitude;
+    }
+  }
+  fft2d(bRe, bIm, width, height, true);
+  let peakIndex = 0;
+  let peakValue = -Infinity;
+  for (let i = 0; i < size; i++) if (bRe[i] > peakValue) {
+    peakValue = bRe[i];
+    peakIndex = i;
+  }
+  const px = peakIndex % width;
+  const py = Math.floor(peakIndex / width);
+  const dx = wrap(px + parabolic(sample(bRe, width, height, px - 1, py), peakValue, sample(bRe, width, height, px + 1, py)), width);
+  const dy = wrap(py + parabolic(sample(bRe, width, height, px, py - 1), peakValue, sample(bRe, width, height, px, py + 1)), height);
+  return {
+    dx,
+    dy,
+    peak: peakValue
+  };
+}
+/**
+ * Sub-pixel offset of a peak, by fitting a parabola through it and its neighbours.
+ *
+ * The correlation surface is sampled on the pixel grid, but the true offset is
+ * not a whole number of pixels. Three samples determine a parabola, and its
+ * vertex is a better estimate than the middle sample - typically to about a
+ * tenth of a pixel.
+ */
+function parabolic(left, center, right) {
+  const denominator = left - 2 * center + right;
+  if (Math.abs(denominator) < 1e-12) return 0;
+  const offset = 0.5 * (left - right) / denominator;
+  return Math.abs(offset) < 1 ? offset : 0;
+}
+function sample(data, width, height, x, y) {
+  const cx = (x % width + width) % width;
+  const cy = (y % height + height) % height;
+  return data[cy * width + cx];
+}
+/** Map an index in `[0, n)` onto a signed shift in `[-n/2, n/2)`. */
+function wrap(value, n) {
+  return value > n / 2 ? value - n : value;
+}
+function hann(n) {
+  const w = new Float64Array(n);
+  if (n === 1) {
+    w[0] = 1;
+    return w;
+  }
+  for (let i = 0; i < n; i++) w[i] = 0.5 * (1 - Math.cos(2 * Math.PI * i / (n - 1)));
+  return w;
+}
+
+function estimateCoarse(originalInk, scannedInk, options = {}) {
+  const {
+    workingSize = 512,
+    maxSkewDeg = 12,
+    maxScaleRatio = 6
+  } = options;
+  const original = downscaleGray(originalInk, workingSize);
+  const scanned = downscaleGray(scannedInk, workingSize);
+  const originalSkew = estimateSkew(original.image, {
+    maxAngleDeg: maxSkewDeg
+  });
+  const scannedSkew = estimateSkew(scanned.image, {
+    maxAngleDeg: maxSkewDeg
+  });
+  const originalFlat = contentExtent(original.image, 0);
+  const scannedFlat = contentExtent(scanned.image, 0);
+  const originalTilted = contentExtent(original.image, originalSkew);
+  const scannedTilted = contentExtent(scanned.image, scannedSkew);
+  const candidates = [];
+  const frameScale = geometricMean(scanned.image.width / original.image.width, scanned.image.height / original.image.height);
+  push(candidates, 'frame', similarity(frameScale, 0, {
+    x: original.image.width / 2,
+    y: original.image.height / 2
+  }, {
+    x: scanned.image.width / 2,
+    y: scanned.image.height / 2
+  }), maxScaleRatio);
+  if (originalFlat.density > 0 && scannedFlat.density > 0) push(candidates, 'content', fromExtents(originalFlat, scannedFlat, 0), maxScaleRatio);
+  if (originalTilted.density > 0 && scannedTilted.density > 0) push(candidates, 'deskew', fromExtents(originalTilted, scannedTilted, scannedSkew - originalSkew), maxScaleRatio);
+  let bestMatrix = similarity(Number.isFinite(frameScale) ? frameScale : 1, 0, {
+    x: original.image.width / 2,
+    y: original.image.height / 2
+  }, {
+    x: scanned.image.width / 2,
+    y: scanned.image.height / 2
+  });
+  let bestScore = -Infinity;
+  let bestStrategy = 'fallback';
+  for (const candidate of candidates) {
+    for (const variant of withTranslationPolish(candidate, original.image, scanned.image)) {
+      const warped = warpGray(scanned.image, variant.matrix, original.image.width, original.image.height, 0);
+      const score = correlation(original.image, warped);
+      if (score > bestScore) {
+        bestMatrix = variant.matrix;
+        bestScore = score;
+        bestStrategy = variant.strategy;
+      }
+    }
+  }
+  return {
+    // Measured on two independently shrunk copies; hand back full-resolution pixels.
+    matrix: rebase(bestMatrix, original.scale, scanned.scale),
+    score: bestScore === -Infinity ? 0 : bestScore,
+    strategy: bestStrategy,
+    skew: {
+      original: originalSkew,
+      scanned: scannedSkew
+    }
+  };
+}
+/** The coarse matrix, plus a copy nudged by whatever phase correlation says is left over. */
+function withTranslationPolish(candidate, original, scanned) {
+  const warped = warpGray(scanned, candidate.matrix, original.width, original.height, 0);
+  let shift;
+  try {
+    shift = phaseCorrelate(original, warped);
+  } catch {
+    return [candidate];
+  }
+  if (!Number.isFinite(shift.dx) || !Number.isFinite(shift.dy)) return [candidate];
+  if (Math.abs(shift.dx) < 0.25 && Math.abs(shift.dy) < 0.25) return [candidate];
+  // `warped` sits in the original's frame, so a residual shift of d means the
+  // original at p matches the warp at p + d: sample d further along.
+  return [candidate, {
+    strategy: `${candidate.strategy}+phase`,
+    matrix: multiply(candidate.matrix, translation(shift.dx, shift.dy))
+  }];
+}
+function fromExtents(original, scanned, angle) {
+  const scale = geometricMean(scanned.width / original.width, scanned.height / original.height);
+  return similarity(scale, angle, original.center, scanned.center);
+}
+function push(into, strategy, matrix, maxScaleRatio) {
+  if (isPlausible(matrix, maxScaleRatio)) into.push({
+    strategy,
+    matrix
+  });
+}
+/**
+ * Geometric rather than arithmetic mean of the two axis ratios.
+ *
+ * The quantity is a ratio, and the mean of a ratio and its reciprocal should be
+ * one. Arithmetic mean says 1.25.
+ */
+function geometricMean(a, b) {
+  if (Number.isNaN(a) || Number.isNaN(b) || a <= 0 || b <= 0) return NaN;
+  return Math.sqrt(a * b);
+}
+
+/** Longest side the referee judges at. Enough to see a stroke line up; cheap enough to call per model. */
+const REFEREE_SIZE = 800;
+function createReferee(originalInk, scannedInk, workingSize) {
+  const size = Math.min(workingSize, REFEREE_SIZE);
+  const original = downscaleGray(originalInk, size);
+  const scanned = downscaleGray(scannedInk, size);
+  const originalMask = binarize(original.image);
+  return matrix => {
+    const work = rebase(matrix, 1 / original.scale, 1 / scanned.scale);
+    const warped = warpGray(scanned.image, work, original.image.width, original.image.height, 0);
+    return {
+      correlation: correlation(original.image, warped),
+      iou: intersectionOverUnion(originalMask, binarize(warped))
+    };
+  };
+}
+/** A correlation as a confidence: clamped to `[0, 1]`, because anti-correlated ink is no alignment at all. */
+function toConfidence(agreement) {
+  return Math.max(0, Math.min(1, agreement.correlation));
+}
+
+const DESCRIPTOR_WORDS = 8;
+const DESCRIPTOR_BITS = DESCRIPTOR_WORDS * 32;
+/** Rotation bins for the steered pattern. 32 bins is 11.25 degrees, finer than ORB's own 12. */
+const ANGLE_BINS = 32;
+/** The Bresenham circle of radius 3, clockwise from the top. */
+const CIRCLE = [[0, -3], [1, -3], [2, -2], [3, -1], [3, 0], [3, 1], [2, 2], [1, 3], [0, 3], [-1, 3], [-2, 2], [-3, 1], [-3, 0], [-3, -1], [-2, -2], [-1, -3]];
+const ARC = 9;
+const COMPASS_MINIMUM = Math.floor((ARC - 1) / 4);
+function detectAndDescribe(image, options = {}) {
+  const {
+    maxFeatures = 1200,
+    fastThreshold = 0.08,
+    levels = 3,
+    scaleFactor = 1.3,
+    patchSize = 31,
+    gridSize = 8,
+    seed = 0xB81EF
+  } = options;
+  const patterns = steeredPatterns(patchSize, seed);
+  const halfPatch = (patchSize - 1) / 2;
+  const border = Math.ceil(halfPatch * Math.SQRT2) + 2;
+  const keypoints = [];
+  const descriptorChunks = [];
+  const perLevel = Math.ceil(maxFeatures / levels);
+  for (let level = 0; level < levels; level++) {
+    const levelScale = scaleFactor ** level;
+    const width = Math.round(image.width / levelScale);
+    const height = Math.round(image.height / levelScale);
+    if (width < border * 2 + 8 || height < border * 2 + 8) break;
+    const levelImage = level === 0 ? image : resizeGray(image, width, height);
+    // BRIEF compares single pixels, so it is exquisitely sensitive to noise;
+    // the smoothing is part of the descriptor, not a preprocessing nicety.
+    const smoothed = boxBlur(levelImage, 2);
+    const found = detectFast(levelImage, fastThreshold, border);
+    const kept = distribute(found, width, height, gridSize, perLevel);
+    for (const corner of kept) {
+      const angle = orientation(levelImage, corner.x, corner.y, halfPatch);
+      const bin = angleBin(angle);
+      const descriptor = describe(smoothed, corner.x, corner.y, patterns[bin]);
+      if (descriptor === null) continue;
+      descriptorChunks.push(descriptor);
+      keypoints.push({
+        x: (corner.x + 0.5) * levelScale,
+        y: (corner.y + 0.5) * levelScale,
+        score: corner.score,
+        angle,
+        level,
+        size: patchSize * levelScale
+      });
+    }
+  }
+  const descriptors = new Uint32Array(descriptorChunks.length * DESCRIPTOR_WORDS);
+  for (const [i, chunk] of descriptorChunks.entries()) descriptors.set(chunk, i * DESCRIPTOR_WORDS);
+  return {
+    keypoints,
+    descriptors
+  };
+}
+/** FAST-9 with a 3x3 non-maximum suppression pass over the corner scores. */
+function detectFast(image, threshold, border) {
+  const {
+    width,
+    height,
+    data
+  } = image;
+  const scores = new Float32Array(width * height);
+  const ring = new Float64Array(16);
+  for (let y = border; y < height - border; y++) {
+    for (let x = border; x < width - border; x++) {
+      const center = data[y * width + x];
+      const high = center + threshold;
+      const low = center - threshold;
+      // Cheap rejection on the four compass points, which sit 4 apart on the
+      // ring. Any run of ARC consecutive pixels must contain at least
+      // floor((ARC - 1) / 4) of them, so fewer than that cannot be a corner.
+      // For ARC = 9 that bound is 2, not the 3 that the widely quoted FAST-12
+      // version of this test uses - requiring 3 here silently discards real
+      // corners, among them the corner of a plain filled rectangle.
+      let bright = 0;
+      let dark = 0;
+      for (const k of [0, 4, 8, 12]) {
+        const value = data[(y + CIRCLE[k][1]) * width + x + CIRCLE[k][0]];
+        if (value > high) bright++;else if (value < low) dark++;
+      }
+      if (bright < COMPASS_MINIMUM && dark < COMPASS_MINIMUM) continue;
+      for (let k = 0; k < 16; k++) ring[k] = data[(y + CIRCLE[k][1]) * width + x + CIRCLE[k][0]];
+      if (!hasArc(ring, high, low)) continue;
+      let brightSum = 0;
+      let darkSum = 0;
+      for (let k = 0; k < 16; k++) {
+        if (ring[k] > high) brightSum += ring[k] - high;else if (ring[k] < low) darkSum += low - ring[k];
+      }
+      scores[y * width + x] = Math.max(brightSum, darkSum);
+    }
+  }
+  const corners = [];
+  for (let y = border; y < height - border; y++) {
+    for (let x = border; x < width - border; x++) {
+      const score = scores[y * width + x];
+      if (score <= 0) continue;
+      let isPeak = true;
+      for (let dy = -1; isPeak && dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+        if (dx === 0 && dy === 0) continue;
+        if (scores[(y + dy) * width + x + dx] > score) {
+          isPeak = false;
+          break;
+        }
+      }
+      if (isPeak) corners.push({
+        x,
+        y,
+        score
+      });
+    }
+  }
+  return corners;
+}
+/** True when 9 consecutive ring pixels (wrapping) are all above `high` or all below `low`. */
+function hasArc(ring, high, low) {
+  let runBright = 0;
+  let runDark = 0;
+  for (let k = 0; k < 16 + ARC - 1; k++) {
+    const value = ring[k % 16];
+    runBright = value > high ? runBright + 1 : 0;
+    runDark = value < low ? runDark + 1 : 0;
+    if (runBright >= ARC || runDark >= ARC) return true;
+  }
+  return false;
+}
+/**
+ * Keep the strongest corners, but spread over the page.
+ *
+ * Score alone concentrates every keypoint in the densest block of text, and a
+ * transform fitted to correspondences from one corner of the page extrapolates
+ * badly to the other three. Filling a grid first, then topping up from what is
+ * left, buys coverage without throwing away the best corners.
+ */
+function distribute(corners, width, height, gridSize, budget) {
+  if (corners.length <= budget) return corners;
+  const cells = new Map();
+  const cellWidth = width / gridSize;
+  const cellHeight = height / gridSize;
+  for (const corner of corners) {
+    const cx = Math.min(gridSize - 1, Math.floor(corner.x / cellWidth));
+    const cy = Math.min(gridSize - 1, Math.floor(corner.y / cellHeight));
+    const key = cy * gridSize + cx;
+    const bucket = cells.get(key);
+    if (bucket === undefined) cells.set(key, [corner]);else bucket.push(corner);
+  }
+  const perCell = Math.max(1, Math.floor(budget / Math.max(1, cells.size)));
+  const kept = [];
+  const leftovers = [];
+  for (const bucket of cells.values()) {
+    bucket.sort((a, b) => b.score - a.score);
+    kept.push(...bucket.slice(0, perCell));
+    leftovers.push(...bucket.slice(perCell));
+  }
+  if (kept.length < budget) {
+    leftovers.sort((a, b) => b.score - a.score);
+    kept.push(...leftovers.slice(0, budget - kept.length));
+  }
+  // With more cells than budget the floor above rounds to one per cell, which
+  // can overshoot; the budget is a promise, so trim by score.
+  if (kept.length > budget) {
+    kept.sort((a, b) => b.score - a.score);
+    return kept.slice(0, budget);
+  }
+  return kept;
+}
+/**
+ * Angle from the patch centre to its centre of intensity mass.
+ *
+ * On an ink image the mass is the writing, so the angle turns with the page —
+ * which is the entire trick that makes a binary descriptor rotation invariant.
+ */
+function orientation(image, cx, cy, radius) {
+  const {
+    width,
+    height,
+    data
+  } = image;
+  const r = Math.floor(radius);
+  let m10 = 0;
+  let m01 = 0;
+  for (let dy = -r; dy <= r; dy++) {
+    const y = cy + dy;
+    if (y < 0 || y >= height) continue;
+    const span = Math.floor(Math.sqrt(r * r - dy * dy));
+    const row = y * width;
+    for (let dx = -span; dx <= span; dx++) {
+      const x = cx + dx;
+      if (x < 0 || x >= width) continue;
+      const value = data[row + x];
+      m10 += dx * value;
+      m01 += dy * value;
+    }
+  }
+  return Math.atan2(m01, m10);
+}
+function angleBin(angle) {
+  const twoPi = Math.PI * 2;
+  const normalized = (angle % twoPi + twoPi) % twoPi;
+  return Math.floor(normalized / twoPi * ANGLE_BINS) % ANGLE_BINS;
+}
+function describe(image, cx, cy, pattern) {
+  const {
+    width,
+    height,
+    data
+  } = image;
+  const out = new Uint32Array(DESCRIPTOR_WORDS);
+  for (let bit = 0; bit < DESCRIPTOR_BITS; bit++) {
+    const base = bit * 4;
+    const x1 = cx + pattern[base];
+    const y1 = cy + pattern[base + 1];
+    const x2 = cx + pattern[base + 2];
+    const y2 = cy + pattern[base + 3];
+    if (x1 < 0 || y1 < 0 || x2 < 0 || y2 < 0 || x1 >= width || y1 >= height || x2 >= width || y2 >= height) return null;
+    if (data[y1 * width + x1] < data[y2 * width + x2]) out[bit >> 5] |= 1 << (bit & 31);
+  }
+  return out;
+}
+const patternCache = new Map();
+/**
+ * One integer sampling pattern per rotation bin, built once and cached.
+ *
+ * Rotating 256 point pairs per keypoint would mean a thousand trig calls each;
+ * quantising the angle instead turns the whole thing into a table lookup, at a
+ * cost of at most half a bin of angular error.
+ */
+function steeredPatterns(patchSize, seed) {
+  const key = `${patchSize}:${seed}`;
+  const cached = patternCache.get(key);
+  if (cached !== undefined) return cached;
+  const half = (patchSize - 1) / 2;
+  const sigma = patchSize / 5;
+  const random = createRandom(seed);
+  const base = new Float64Array(DESCRIPTOR_BITS * 4);
+  for (let i = 0; i < DESCRIPTOR_BITS * 4; i++) base[i] = clamp(Math.round(gaussian(random) * sigma), -half, half);
+  const patterns = [];
+  for (let bin = 0; bin < ANGLE_BINS; bin++) {
+    const angle = bin / ANGLE_BINS * Math.PI * 2;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const rotated = new Int32Array(DESCRIPTOR_BITS * 4);
+    for (let i = 0; i < DESCRIPTOR_BITS * 4; i += 2) {
+      const x = base[i];
+      const y = base[i + 1];
+      rotated[i] = Math.round(cos * x - sin * y);
+      rotated[i + 1] = Math.round(sin * x + cos * y);
+    }
+    patterns.push(rotated);
+  }
+  patternCache.set(key, patterns);
+  return patterns;
+}
+function clamp(value, min, max) {
+  return value < min ? min : Math.min(value, max);
+}
+
+/**
+ * "No candidate yet", as a value an Int32Array can actually hold.
+ *
+ * `Number.MAX_SAFE_INTEGER` cannot: writing it to an Int32Array truncates it to
+ * -1, and every subsequent "is this closer?" comparison then answers no.
+ */
+const UNSET = 0x7FFFFFFF;
+function matchFeatures(source, target, options = {}) {
+  const {
+    ratio = 0.8,
+    maxDistance = 96,
+    crossCheck = true,
+    maxDisplacement = Infinity
+  } = options;
+  const n = source.keypoints.length;
+  const m = target.keypoints.length;
+  if (n === 0 || m === 0) return [];
+  const bestForSource = new Int32Array(n).fill(-1);
+  const bestDistance = new Int32Array(n).fill(UNSET);
+  const secondDistance = new Int32Array(n).fill(UNSET);
+  const bestForTarget = new Int32Array(m).fill(-1);
+  const bestTargetDistance = new Int32Array(m).fill(UNSET);
+  const gated = Number.isFinite(maxDisplacement);
+  const gate = maxDisplacement * maxDisplacement;
+  for (let i = 0; i < n; i++) {
+    const a = source.keypoints[i];
+    const offsetA = i * DESCRIPTOR_WORDS;
+    let first = UNSET;
+    let second = UNSET;
+    let firstIndex = -1;
+    for (let j = 0; j < m; j++) {
+      const b = target.keypoints[j];
+      if (gated) {
+        const dx = a.x - b.x;
+        const dy = a.y - b.y;
+        if (dx * dx + dy * dy > gate) continue;
+      }
+      const distance = hamming(source.descriptors, offsetA, target.descriptors, j * DESCRIPTOR_WORDS);
+      if (distance < first) {
+        second = first;
+        first = distance;
+        firstIndex = j;
+      } else if (distance < second) {
+        second = distance;
+      }
+      if (distance < bestTargetDistance[j]) {
+        bestTargetDistance[j] = distance;
+        bestForTarget[j] = i;
+      }
+    }
+    bestForSource[i] = firstIndex;
+    bestDistance[i] = first;
+    secondDistance[i] = second;
+  }
+  const matches = [];
+  for (let i = 0; i < n; i++) {
+    const j = bestForSource[i];
+    if (j < 0) continue;
+    if (bestDistance[i] > maxDistance) continue;
+    if (secondDistance[i] !== UNSET && bestDistance[i] > ratio * secondDistance[i]) continue;
+    if (crossCheck && bestForTarget[j] !== i) continue;
+    const a = source.keypoints[i];
+    const b = target.keypoints[j];
+    matches.push({
+      source: {
+        x: a.x,
+        y: a.y
+      },
+      target: {
+        x: b.x,
+        y: b.y
+      },
+      distance: bestDistance[i]
+    });
+  }
+  return matches;
+}
+/** Hamming distance between two 256-bit descriptors. */
+function hamming(a, offsetA, b, offsetB) {
+  let total = 0;
+  for (let k = 0; k < DESCRIPTOR_WORDS; k++) total += popcount(a[offsetA + k] ^ b[offsetB + k]);
+  return total;
+}
+/** SWAR bit count: pair off, then nibble off, then one multiply to sum the bytes. */
+function popcount(value) {
+  let v = value - (value >> 1 & 0x55555555);
+  v = (v & 0x33333333) + (v >> 2 & 0x33333333);
+  v = v + (v >> 4) & 0x0F0F0F0F;
+  return Math.imul(v, 0x01010101) >> 24 & 0xFF;
+}
+
+/** How many correspondences the model needs before it is determined at all. */
+function minimumSamples(model) {
+  switch (model) {
+    case 'similarity':
+      {
+        return 2;
+      }
+    case 'affine':
+      {
+        return 3;
+      }
+    case 'homography':
+      {
+        return 4;
+      }
+  }
+}
+function fitModel(model, matches, indices) {
+  switch (model) {
+    case 'similarity':
+      {
+        return fitSimilarity(matches, indices);
+      }
+    case 'affine':
+      {
+        return fitAffine(matches, indices);
+      }
+    case 'homography':
+      {
+        return fitHomography(matches, indices);
+      }
+  }
+}
+/**
+ * Least-squares similarity, in closed form.
+ *
+ * No iteration and no matrix inverse: centre both point sets, and the rotation
+ * and scale fall out of two dot products. That closed form is why similarity
+ * survives a RANSAC sample that affine would choke on.
+ */
+function fitSimilarity(matches, indices) {
+  const picked = select(matches, indices);
+  if (picked.length < 2) return null;
+  let sx = 0;
+  let sy = 0;
+  let tx = 0;
+  let ty = 0;
+  for (const m of picked) {
+    sx += m.source.x;
+    sy += m.source.y;
+    tx += m.target.x;
+    ty += m.target.y;
+  }
+  const n = picked.length;
+  sx /= n;
+  sy /= n;
+  tx /= n;
+  ty /= n;
+  let dot = 0;
+  let cross = 0;
+  let norm = 0;
+  for (const m of picked) {
+    const px = m.source.x - sx;
+    const py = m.source.y - sy;
+    const qx = m.target.x - tx;
+    const qy = m.target.y - ty;
+    dot += px * qx + py * qy;
+    cross += px * qy - py * qx;
+    norm += px * px + py * py;
+  }
+  if (norm < 1e-12) return null;
+  const a = dot / norm;
+  const b = cross / norm;
+  if (Math.hypot(a, b) < 1e-9) return null;
+  return [a, -b, tx - a * sx + b * sy, b, a, ty - b * sx - a * sy, 0, 0, 1];
+}
+/** Least-squares affine: two independent 3x3 normal systems sharing one matrix. */
+function fitAffine(matches, indices) {
+  const picked = select(matches, indices);
+  if (picked.length < 3) return null;
+  const m = new Float64Array(9);
+  const bx = new Float64Array(3);
+  const by = new Float64Array(3);
+  for (const match of picked) {
+    const {
+      x,
+      y
+    } = match.source;
+    const {
+      x: u,
+      y: v
+    } = match.target;
+    m[0] += x * x;
+    m[1] += x * y;
+    m[2] += x;
+    m[4] += y * y;
+    m[5] += y;
+    m[8] += 1;
+    bx[0] += x * u;
+    bx[1] += y * u;
+    bx[2] += u;
+    by[0] += x * v;
+    by[1] += y * v;
+    by[2] += v;
+  }
+  m[3] = m[1];
+  m[6] = m[2];
+  m[7] = m[5];
+  const row0 = solve(m, bx, 3);
+  const row1 = solve(m, by, 3);
+  if (row0 === null || row1 === null) return null;
+  return [row0[0], row0[1], row0[2], row1[0], row1[1], row1[2], 0, 0, 1];
+}
+/**
+ * Direct Linear Transform with Hartley normalisation.
+ *
+ * The normalisation is not optional polish. Raw pixel coordinates put entries
+ * like `x * u` (order 10^6) next to a constant 1 in the same row, and the
+ * eigen solve then answers a question dominated by the big column. Centring
+ * each point set and scaling it to a mean radius of `sqrt(2)` puts every
+ * column on the same footing; the result is mapped back afterwards.
+ */
+function fitHomography(matches, indices) {
+  const picked = select(matches, indices);
+  if (picked.length < 4) return null;
+  const sourceNorm = normalizer(picked.map(m => m.source));
+  const targetNorm = normalizer(picked.map(m => m.target));
+  if (sourceNorm === null || targetNorm === null) return null;
+  // Accumulate A^T A directly: 9x9 regardless of how many points there are.
+  const ata = new Float64Array(81);
+  const row = new Float64Array(9);
+  for (const match of picked) {
+    const p = apply(sourceNorm, match.source.x, match.source.y);
+    const q = apply(targetNorm, match.target.x, match.target.y);
+    row.set([-p.x, -p.y, -1, 0, 0, 0, q.x * p.x, q.x * p.y, q.x]);
+    accumulate(ata, row);
+    row.set([0, 0, 0, -p.x, -p.y, -1, q.y * p.x, q.y * p.y, q.y]);
+    accumulate(ata, row);
+  }
+  const h = smallestEigenvector(ata, 9);
+  const normalized = [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7], h[8]];
+  let denormalized;
+  try {
+    denormalized = multiply(invert(targetNorm), multiply(normalized, sourceNorm));
+  } catch {
+    return null;
+  }
+  const scale = denormalized[8];
+  if (!Number.isFinite(scale) || Math.abs(scale) < 1e-12) return null;
+  return denormalized.map(v => v / scale);
+}
+function accumulate(ata, row) {
+  for (let i = 0; i < 9; i++) {
+    const vi = row[i];
+    if (vi === 0) continue;
+    for (let j = 0; j < 9; j++) ata[i * 9 + j] += vi * row[j];
+  }
+}
+/** Translate to the centroid and scale so the mean distance from it is `sqrt(2)`. */
+function normalizer(points) {
+  let cx = 0;
+  let cy = 0;
+  for (const p of points) {
+    cx += p.x;
+    cy += p.y;
+  }
+  cx /= points.length;
+  cy /= points.length;
+  let distance = 0;
+  for (const p of points) distance += Math.hypot(p.x - cx, p.y - cy);
+  distance /= points.length;
+  // Explicit about NaN: a degenerate point set must fail, not divide.
+  if (Number.isNaN(distance) || distance <= 1e-9) return null;
+  const s = Math.SQRT2 / distance;
+  return [s, 0, -s * cx, 0, s, -s * cy, 0, 0, 1];
+}
+function apply(m, x, y) {
+  return {
+    x: m[0] * x + m[1] * y + m[2],
+    y: m[3] * x + m[4] * y + m[5]
+  };
+}
+function select(matches, indices) {
+  return indices === undefined ? matches : indices.map(i => matches[i]);
+}
+
+function ransac(matches, options) {
+  const {
+    model,
+    threshold,
+    maxIterations = 2000,
+    confidence = 0.995,
+    seed = 0x5CA7F1
+  } = options;
+  const sampleSize = minimumSamples(model);
+  const minInliers = options.minInliers ?? Math.max(sampleSize + 2, Math.ceil(matches.length * 0.08));
+  if (matches.length < Math.max(sampleSize, minInliers)) return null;
+  const random = createRandom(seed);
+  const sample = Array.from({
+    length: sampleSize
+  }, () => 0);
+  let bestInliers = [];
+  let bestMatrix = null;
+  let limit = maxIterations;
+  let iterations = 0;
+  for (; iterations < limit && iterations < maxIterations; iterations++) {
+    drawSample(sample, matches.length, random);
+    const candidate = fitModel(model, matches, sample);
+    if (candidate === null || !isPlausible(candidate)) continue;
+    const inliers = findInliers(matches, candidate, threshold);
+    if (inliers.length <= bestInliers.length) continue;
+    bestInliers = inliers;
+    bestMatrix = candidate;
+    // Adaptive stopping: once a large fraction agrees, the chance that more
+    // draws find something better collapses, and so does the budget.
+    const ratio = inliers.length / matches.length;
+    if (ratio > 0 && ratio < 1) {
+      const denominator = Math.log(1 - ratio ** sampleSize);
+      if (denominator < 0) limit = Math.min(maxIterations, Math.ceil(Math.log(1 - confidence) / denominator) + 1);
+    } else if (ratio >= 1) {
+      limit = iterations + 1;
+    }
+  }
+  if (bestMatrix === null || bestInliers.length < minInliers) return null;
+  // Re-fit on every inlier. The minimal sample only ever located the consensus;
+  // the accurate transform comes from all of it.
+  let refined = fitModel(model, matches, bestInliers);
+  if (refined !== null && isPlausible(refined)) {
+    const refinedInliers = findInliers(matches, refined, threshold);
+    if (refinedInliers.length >= bestInliers.length) bestInliers = refinedInliers;else refined = bestMatrix;
+  } else {
+    refined = bestMatrix;
+  }
+  const matrix = refined ?? bestMatrix;
+  let total = 0;
+  for (const i of bestInliers) total += reprojectionError(matrix, matches[i].source, matches[i].target);
+  return {
+    matrix,
+    inliers: bestInliers,
+    inlierRatio: bestInliers.length / matches.length,
+    iterations,
+    error: bestInliers.length > 0 ? total / bestInliers.length : Infinity
+  };
+}
+function findInliers(matches, matrix, threshold) {
+  const inliers = [];
+  for (const [i, match] of matches.entries()) if (reprojectionError(matrix, match.source, match.target) <= threshold) inliers.push(i);
+  return inliers;
+}
+/** Distinct indices, drawn without replacement. */
+function drawSample(into, count, random) {
+  for (let i = 0; i < into.length; i++) {
+    let candidate = 0;
+    for (let attempt = 0; attempt < 32; attempt++) {
+      candidate = Math.min(count - 1, Math.floor(random() * count));
+      let duplicate = false;
+      for (let j = 0; j < i; j++) if (into[j] === candidate) {
+        duplicate = true;
+        break;
+      }
+      if (!duplicate) break;
+    }
+    into[i] = candidate;
+  }
+}
+
+function prepareMatches(originalInk, scannedInk, coarse, options) {
+  const original = downscaleGray(originalInk, options.workingSize);
+  const scanned = downscaleGray(scannedInk, options.workingSize);
+  // The coarse matrix speaks full-resolution pixels; restate it between the two
+  // working frames, which were shrunk by different amounts.
+  const coarseWork = rebase(coarse.matrix, 1 / original.scale, 1 / scanned.scale);
+  const rough = warpGray(scanned.image, coarseWork, original.image.width, original.image.height, 0);
+  const originalFeatures = detectAndDescribe(original.image, {
+    maxFeatures: options.maxFeatures,
+    seed: options.seed
+  });
+  const scannedFeatures = detectAndDescribe(rough, {
+    maxFeatures: options.maxFeatures,
+    seed: options.seed
+  });
+  const diagonal = Math.hypot(original.image.width, original.image.height);
+  const matches = matchFeatures(originalFeatures, scannedFeatures, {
+    maxDisplacement: diagonal * options.maxDisplacementRatio
+  });
+  return {
+    matches,
+    features: {
+      original: originalFeatures.keypoints.length,
+      scanned: scannedFeatures.keypoints.length
+    },
+    scale: original.scale
+  };
+}
+/** Fit one model to the shared matches, or `null` when RANSAC finds no consensus worth trusting. */
+function fitResidual(prepared, coarse, model, options) {
+  const consensus = ransac(prepared.matches, {
+    model,
+    threshold: options.ransacThreshold,
+    minInliers: options.minInliers,
+    seed: options.seed
+  });
+  if (consensus === null) return null;
+  // RANSAC's matrix maps the original's working frame onto the rough warp,
+  // which lives in that same frame. Scale it back up, then compose: original ->
+  // rough -> scan.
+  const residual = conjugateScale(consensus.matrix, prepared.scale);
+  return {
+    matrix: multiply(coarse.matrix, residual),
+    inliers: consensus.inliers.length,
+    inlierRatio: consensus.inlierRatio,
+    reprojectionError: consensus.error
+  };
+}
+
+/**
+ * Which transform to believe, when more than one fits.
+ *
+ * More degrees of freedom always fit at least as well, so a plain "highest
+ * confidence wins" would drift towards the most flexible model on every input.
+ * On a flatbed scan that is wrong in a way nothing downstream would notice: a
+ * homography fitted to a flat page bends slightly to follow the page's own noise,
+ * beats the similarity on ink correlation by a hair, passes `isPlausible`, and
+ * puts every region a pixel or two off. So a more complex model has to *earn* its
+ * extra parameters by a margin, and a simpler one within that margin is kept.
+ */
+/** Ascending cost, ascending fragility: the order a sweep should try them in. */
+const DEFAULT_MODELS = ['similarity', 'affine', 'homography'];
+const DEGREES_OF_FREEDOM = {
+  similarity: 4,
+  affine: 6,
+  homography: 8
+};
+/**
+ * Should `candidate` replace `incumbent` as the answer?
+ *
+ * - A more complex candidate must beat the incumbent by more than `margin`.
+ * - A simpler candidate wins if it comes within `margin` of the incumbent.
+ * - An equally complex one simply has to do better.
+ *
+ * Symmetric on purpose, so the answer does not depend on the order the models
+ * were tried in: whatever order `models` names, the simplest model within the
+ * margin of the best is the one returned.
+ */
+function prefers(candidate, incumbent, margin) {
+  if (incumbent === null) return true;
+  const extra = DEGREES_OF_FREEDOM[candidate.model] - DEGREES_OF_FREEDOM[incumbent.model];
+  if (extra > 0) return candidate.confidence > incumbent.confidence + margin;
+  if (extra < 0) return candidate.confidence >= incumbent.confidence - margin;
+  return candidate.confidence > incumbent.confidence;
+}
+/** The models to sweep, in the order given, each once. Throws on an empty list rather than silently fitting nothing. */
+function sweepOrder(models) {
+  const unique = [...new Set(models)];
+  if (unique.length === 0) throw new RangeError('models must name at least one transform model');
+  return unique;
+}
+
+/**
+ * Align a scan onto the page it was made from.
+ *
+ * ## What this is for
+ *
+ * Two questions about a returned form are easy to answer once the scan sits
+ * exactly on top of the original, and near-impossible before:
+ *
+ * 1. *Was anything in the printed text changed?* Run OCR on both and diff.
+ *    That only works if the two are the same page at the same size, otherwise
+ *    the OCR engine's own layout analysis is comparing different documents.
+ * 2. *Was the box at (x, y) signed?* That is a question about a fixed
+ *    rectangle, and a fixed rectangle only means something once both images
+ *    agree on where (x, y) is. See `@scanmate/diff`.
+ *
+ * ## The pipeline
+ *
+ * ```text
+ *   decode ─► ink ─► coarse guess ─► rough warp ─► features ─┬─► RANSAC(similarity) ─► score ─┐
+ *                    (scale/skew)                   (ORB)     ├─► RANSAC(affine)     ─► score ─┼─► warp
+ *                                                             └─► RANSAC(homography) ─► score ─┘
+ *   └──────────────────── once, whatever the model ───────────┘   └──── per model, cheap ────┘
+ * ```
+ *
+ * The coarse guess exists to make the feature stage possible at all: binary
+ * descriptors compare fixed pixel offsets, so they only match between images
+ * at comparable scale, and nothing in a JPEG tells you what dpi it was scanned
+ * at. Once the scan has been resampled to roughly the right size, matching is
+ * easy and RANSAC can throw away the inevitable wrong matches - a page of text
+ * is full of genuinely identical-looking corners.
+ *
+ * ## Choosing the model
+ *
+ * With `model: 'all'`, the default, everything left of the fork is done once:
+ * decoding, ink separation, the coarse search, ORB on both pages and matching
+ * are nearly all of the cost and do not depend on the transform family. Only
+ * RANSAC and one scoring warp run per model, and neither is expensive - RANSAC
+ * touches no pixels. The sweep tries models cheapest first, stops as soon as one
+ * reaches `confidenceTarget`, and a more complex model must beat a simpler one by
+ * `modelPreferenceMargin` to replace it. The full-resolution warp and the
+ * encode happen once, for the winner.
+ *
+ * If no model finds a consensus (a nearly blank form has few corners to find),
+ * the coarse estimate is returned on its own, and `method` says so.
+ *
+ * ## Why it is asynchronous
+ *
+ * The estimator is CPU-bound with no I/O to wait on, and an earlier version of
+ * this function was synchronous to say so. The codec changed that: decoding and
+ * encoding now run in libvips on libuv's threadpool, roughly an order of
+ * magnitude faster than the pure-JavaScript codec they replaced, and during
+ * those two stages the event loop genuinely is free. Between them it is not -
+ * the coarse search, ORB and RANSAC all run to completion on this thread - so
+ * to align several pages at once, still put this in a worker thread.
+ */
+async function alignScan(original, scanned, options = {}) {
+  const startedAt = Date.now();
+  const {
+    model = 'all',
+    confidenceTarget = 0.9,
+    models = DEFAULT_MODELS,
+    modelPreferenceMargin = 0.02,
+    workingSize = 1400,
+    coarseSize = 512,
+    maxFeatures = 1200,
+    ransacThreshold = 3,
+    minInliers = 12,
+    maxSkewDeg = 12,
+    maxScaleRatio = 6,
+    maxDisplacementRatio = 0.12,
+    ink,
+    interpolation = 'bilinear',
+    background = [255, 255, 255, 255],
+    output = 'png',
+    quality = 92,
+    seed = 0x5CA7F1
+  } = options;
+  const candidates = model === 'all' ? sweepOrder(models) : [model];
+  const originalRaster = await decodeImage(original);
+  const scannedRaster = await decodeImage(scanned);
+  const originalInk = inkMap(toGrayscale(originalRaster), ink);
+  const scannedInk = inkMap(toGrayscale(scannedRaster), ink);
+  // --- Model-independent, and nearly all of the cost: done once. ---
+  const coarse = estimateCoarse(originalInk, scannedInk, {
+    workingSize: coarseSize,
+    maxSkewDeg,
+    maxScaleRatio
+  });
+  const prepared = prepareMatches(originalInk, scannedInk, coarse, {
+    workingSize,
+    maxFeatures,
+    maxDisplacementRatio,
+    seed
+  });
+  const judge = createReferee(originalInk, scannedInk, workingSize);
+  // --- Per model: RANSAC, one scoring warp. ---
+  const attempts = [];
+  let best = null;
+  for (const candidate of candidates) {
+    const fit = fitResidual(prepared, coarse, candidate, {
+      ransacThreshold,
+      minInliers,
+      seed
+    });
+    if (fit === null) {
+      attempts.push({
+        model: candidate,
+        confidence: null,
+        inliers: 0,
+        inlierRatio: 0,
+        reprojectionError: NaN,
+        rejected: true,
+        selected: false
+      });
+      continue;
+    }
+    const agreement = judge(fit.matrix);
+    const confidence = toConfidence(agreement);
+    const attempt = {
+      model: candidate,
+      confidence,
+      inliers: fit.inliers,
+      inlierRatio: fit.inlierRatio,
+      reprojectionError: fit.reprojectionError,
+      rejected: false,
+      selected: false
+    };
+    attempts.push(attempt);
+    if (prefers({
+      model: candidate,
+      confidence
+    }, best, modelPreferenceMargin)) best = {
+      model: candidate,
+      fit,
+      agreement,
+      confidence,
+      attempt
+    };
+    if (best !== null && best.confidence >= confidenceTarget) break;
+  }
+  // --- Once, for the winner: the full-resolution warp and the encode. ---
+  const matrix = best === null ? coarse.matrix : best.fit.matrix;
+  const agreement = best === null ? judge(matrix) : best.agreement;
+  // The coarse estimate is a similarity; that is what it reports when it stands alone.
+  const selectedModel = best === null ? 'similarity' : best.model;
+  if (best !== null) best.attempt.selected = true;
+  const raster = warpRaster(scannedRaster, matrix, originalRaster.width, originalRaster.height, {
+    background,
+    interpolation,
+    prefilter: true
+  });
+  return {
+    raster,
+    image: output === 'none' ? null : await encodeImage(raster, {
+      format: output,
+      quality
+    }),
+    width: raster.width,
+    height: raster.height,
+    matrix,
+    inverse: invert(matrix),
+    transform: decompose(matrix, selectedModel),
+    confidence: toConfidence(agreement),
+    method: best === null ? 'coarse' : 'features',
+    diagnostics: {
+      coarseScore: coarse.score,
+      coarseStrategy: coarse.strategy,
+      skewDeg: {
+        original: coarse.skew.original * 180 / Math.PI,
+        scanned: coarse.skew.scanned * 180 / Math.PI
+      },
+      features: prepared.features,
+      matches: prepared.matches.length,
+      inliers: best?.fit.inliers ?? 0,
+      inlierRatio: best?.fit.inlierRatio ?? 0,
+      reprojectionError: best?.fit.reprojectionError ?? NaN,
+      correlation: agreement.correlation,
+      intersectionOverUnion: agreement.iou,
+      selectedModel,
+      attempts,
+      durationMs: Date.now() - startedAt
+    }
+  };
+}
+
+/**
+ * Align every page pair a document produced - typically the output of
+ * `@scanmate/extract` - and hand each back with its alignment attached.
+ *
+ * Pages run one after another, not concurrently. The estimator is CPU-bound and
+ * synchronous between decode and encode, so starting several on one thread only
+ * interleaves them and makes each slower; real parallelism needs worker threads,
+ * which is a decision for the caller or an orchestrator, not for a library call.
+ *
+ * Every page passes through untouched with `aligned` added, and the types say
+ * so: whatever else the producer attached - `@scanmate/extract`'s per-page
+ * `metadata`, the dpi each side was rendered at, the encoded bytes - is still
+ * there, and still typed, on the way out.
+ */
+async function alignPages(pages, options = {}) {
+  const {
+    onProgress,
+    ...alignOptions
+  } = options;
+  const aligned = [];
+  for (const [position, page] of pages.entries()) {
+    const index = position + 1;
+    onProgress?.({
+      stage: 'align',
+      phase: 'start',
+      page: page.page,
+      index,
+      total: pages.length
+    });
+    const result = await alignScan(page.original.raster, page.scanned.raster, alignOptions);
+    aligned.push({
+      ...page,
+      aligned: result
+    });
+    onProgress?.({
+      stage: 'align',
+      phase: 'done',
+      page: page.page,
+      index,
+      total: pages.length,
+      durationMs: result.diagnostics.durationMs,
+      detail: {
+        confidence: result.confidence,
+        model: result.diagnostics.selectedModel,
+        method: result.method,
+        attempts: result.diagnostics.attempts.length
+      }
+    });
+  }
+  return aligned;
+}
+
+/**
+ * Nudge an existing transform by whatever residual translation is still measurable.
+ *
+ * Exposed because it is occasionally useful on its own: if you already know the
+ * transform from a previous page of the same batch, this re-seats it on the
+ * current page for a fraction of the cost of a full alignment.
+ */
+function polishTranslation(originalInk, scannedInk, matrix, workingSize = 512) {
+  const original = downscaleGray(originalInk, workingSize);
+  const scanned = downscaleGray(scannedInk, workingSize);
+  const work = rebase(matrix, 1 / original.scale, 1 / scanned.scale);
+  const warped = warpGray(scanned.image, work, original.image.width, original.image.height, 0);
+  const shift = phaseCorrelate(original.image, warped);
+  if (!Number.isFinite(shift.dx) || !Number.isFinite(shift.dy)) return matrix;
+  const corrected = multiply(work, translation(shift.dx, shift.dy));
+  const candidate = rebase(corrected, original.scale, scanned.scale);
+  const before = correlation(original.image, warped);
+  const after = correlation(original.image, warpGray(scanned.image, corrected, original.image.width, original.image.height, 0));
+  return after > before ? candidate : matrix;
+}
+
+export { DEFAULT_MODELS, alignPages, alignScan, detectAndDescribe, estimateCoarse, findInliers, fitAffine, fitHomography, fitModel, fitSimilarity, hamming, matchFeatures, minimumSamples, phaseCorrelate, polishTranslation, popcount, prefers, ransac };
+//# sourceMappingURL=index.esm.js.map