@scanmate/align 0.0.2

package/dist/src/coarse-estimation/estimate-coarse.use-case.d.ts

@@ -0,0 +1,43 @@
+import type { GrayImage, Matrix3 } from '@scanmate/ink';
+/**
+ * A first, cheap answer good enough to make the expensive one possible.
+ *
+ * Descriptor matching has a blind spot: BRIEF compares fixed pixel offsets, so
+ * a scan at 300 dpi and a page rendered at 150 describe the same corner with
+ * two unrelated bit strings. Something has to establish roughly how big the
+ * scan is before the matcher runs, and nothing in the file says.
+ *
+ * So guess, several ways, and let the pixels judge:
+ *
+ * - **frame** — assume the scan is the whole page, so the frames correspond.
+ * - **content** — assume the *printing* corresponds. Robust to a scan with
+ *   wider margins, which the frame guess gets badly wrong.
+ * - **deskew** — measure each page's own skew, and match the printing in the
+ *   frame where each sits straight. This is the one that usually wins.
+ *
+ * Each gets a phase-correlation nudge, then all of them are warped and scored
+ * on ink correlation. Guessing several times and measuring is far more robust
+ * than one clever guess, and at this resolution each attempt costs very little.
+ */
+export interface CoarseOptions {
+    /** Longest side of the images the search runs on. */
+    workingSize?: number;
+    /** Largest per-page skew considered, in degrees. */
+    maxSkewDeg?: number;
+    /** Largest scale ratio between the two images that will be entertained. */
+    maxScaleRatio?: number;
+}
+export interface CoarseResult {
+    /** Maps full-resolution original coordinates to full-resolution scan coordinates. */
+    matrix: Matrix3;
+    /** Ink correlation achieved by this transform, in `[-1, 1]`. */
+    score: number;
+    /** Which guess won, for diagnostics. */
+    strategy: string;
+    skew: {
+        original: number;
+        scanned: number;
+    };
+}
+export declare function estimateCoarse(originalInk: GrayImage, scannedInk: GrayImage, options?: CoarseOptions): CoarseResult;
+//# sourceMappingURL=estimate-coarse.use-case.d.ts.map

package/dist/src/coarse-estimation/index.d.ts

@@ -0,0 +1,4 @@
+/** A first, cheap scale-and-skew guess, good enough to make feature matching possible. */
+export { estimateCoarse } from './estimate-coarse.use-case.js';
+export type { CoarseOptions, CoarseResult } from './estimate-coarse.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/feature-matching/detect-features.use-case.d.ts

@@ -0,0 +1,72 @@
+import type { GrayImage } from '@scanmate/ink';
+/**
+ * FAST corners with steered BRIEF descriptors — an ORB, written out.
+ *
+ * This is the piece OpenCV would normally hand you, and it is here because the
+ * deployment target rules out a native binding. The three parts each answer a
+ * separate question:
+ *
+ * - **FAST** answers *where*. A pixel is a corner when a contiguous arc of the
+ *   16 pixels on a circle around it is all clearly brighter, or all clearly
+ *   darker, than it is. On a page that fires on stroke ends, serifs, and the
+ *   corners of rules and boxes — landmarks that survive being rescanned.
+ * - **The intensity centroid** answers *which way up*. The vector from the
+ *   patch's centre to its centre of mass is a direction the ink itself defines,
+ *   so it turns with the page.
+ * - **BRIEF** answers *what it looks like*, as 256 yes/no questions of the form
+ *   "is this pixel darker than that one?", asked at positions rotated by that
+ *   angle. Comparing two of those is one XOR and a bit count, which is why
+ *   brute-force matching thousands of them is affordable.
+ *
+ * The descriptor is not scale invariant on its own, hence the pyramid: the same
+ * corner is described at several sizes so a scan at a different dpi still
+ * matches.
+ */
+export interface Keypoint {
+    /** Coordinates in the *input* image, pixel centres, regardless of the level found at. */
+    x: number;
+    y: number;
+    score: number;
+    /** Dominant ink direction in radians. */
+    angle: number;
+    level: number;
+    /** Pixel size of the patch described, in input pixels. */
+    size: number;
+}
+export interface FeatureSet {
+    keypoints: Keypoint[];
+    /** 8 x 32 bits per keypoint, laid out contiguously. */
+    descriptors: Uint32Array;
+}
+export interface FeatureOptions {
+    maxFeatures?: number;
+    /** Contrast a circle pixel must clear to count, in `[0, 1]` ink units. */
+    fastThreshold?: number;
+    /** Pyramid levels, including the original. */
+    levels?: number;
+    /** Ratio between consecutive levels. */
+    scaleFactor?: number;
+    /** Side of the described patch, in pixels of its own level. */
+    patchSize?: number;
+    /** Cells per axis used to spread keypoints over the page instead of over its densest paragraph. */
+    gridSize?: number;
+    seed?: number;
+}
+export declare const DESCRIPTOR_WORDS = 8;
+export declare function detectAndDescribe(image: GrayImage, options?: FeatureOptions): FeatureSet;
+interface Corner {
+    x: number;
+    y: number;
+    score: number;
+}
+/** FAST-9 with a 3x3 non-maximum suppression pass over the corner scores. */
+export declare function detectFast(image: GrayImage, threshold: number, border: number): Corner[];
+/**
+ * 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.
+ */
+export declare function orientation(image: GrayImage, cx: number, cy: number, radius: number): number;
+export {};
+//# sourceMappingURL=detect-features.use-case.d.ts.map

package/dist/src/feature-matching/index.d.ts

@@ -0,0 +1,6 @@
+/** ORB features on both pages, and the Hamming matcher that pairs them. */
+export { detectAndDescribe } from './detect-features.use-case.js';
+export type { FeatureOptions, FeatureSet, Keypoint } from './detect-features.use-case.js';
+export { hamming, matchFeatures, popcount } from './match-features.use-case.js';
+export type { MatchOptions } from './match-features.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/feature-matching/match-features.use-case.d.ts

@@ -0,0 +1,38 @@
+import type { PointMatch } from '@scanmate/ink';
+import type { FeatureSet } from './detect-features.use-case.js';
+/**
+ * Brute-force descriptor matching.
+ *
+ * Brute force is the right algorithm here, not a concession. A page yields
+ * around a thousand keypoints per side; a million 256-bit comparisons is eight
+ * million XOR-and-popcount operations, which is milliseconds. Building an index
+ * to avoid that would cost more than it saves and would only return
+ * approximate neighbours.
+ *
+ * The filters matter more than the search does:
+ *
+ * - **Ratio test.** Keep a match only when the best candidate is clearly better
+ *   than the runner-up. On a page of repeated letterforms the nearest neighbour
+ *   is often meaningless, and the giveaway is that the second nearest is just
+ *   as close.
+ * - **Cross-check.** Both sides must name each other. One-directional bests are
+ *   not symmetric, and the asymmetric ones are usually wrong.
+ * - **Displacement gate.** The images are already roughly aligned when this
+ *   runs, so a correspondence that jumps half the page is not a correspondence.
+ */
+export interface MatchOptions {
+    /** Lowe's ratio. Lower is stricter. */
+    ratio?: number;
+    /** Reject matches further apart than this many bits out of 256. */
+    maxDistance?: number;
+    /** Require both descriptors to pick each other. */
+    crossCheck?: boolean;
+    /** Reject correspondences that move further than this, in pixels. `Infinity` disables the gate. */
+    maxDisplacement?: number;
+}
+export declare function matchFeatures(source: FeatureSet, target: FeatureSet, options?: MatchOptions): PointMatch[];
+/** Hamming distance between two 256-bit descriptors. */
+export declare function hamming(a: Uint32Array, offsetA: number, b: Uint32Array, offsetB: number): number;
+/** SWAR bit count: pair off, then nibble off, then one multiply to sum the bytes. */
+export declare function popcount(value: number): number;
+//# sourceMappingURL=match-features.use-case.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `@scanmate/align` - put a scanned page back on top of the page it came from.
+ *
+ * ```ts
+ * import { decodeImage } from '@scanmate/ink'
+ * import { alignScan } from '@scanmate/align'
+ *
+ * const result = await alignScan(await decodeImage('page1.png'), await decodeImage('returned.jpg'))
+ * console.log(result.confidence, result.diagnostics.selectedModel, result.transform.rotationDeg)
+ * ```
+ *
+ * `result.raster` sits on the original's canvas, at the original's width and
+ * height, so every coordinate known from the PDF still means what it meant.
+ */
+export { alignPages, alignScan, polishTranslation } from './scan-alignment/index.js';
+export type { AlignDiagnostics, AlignOptions, AlignPagesOptions, AlignResult, ModelAttempt } from './scan-alignment/index.js';
+/** The model-selection rule `model: 'all'` applies, for callers running their own sweep. */
+export { DEFAULT_MODELS, prefers } from './scan-alignment/index.js';
+export type { ScoredModel } from './scan-alignment/index.js';
+export { estimateCoarse } from './coarse-estimation/index.js';
+export type { CoarseOptions, CoarseResult } from './coarse-estimation/index.js';
+export { detectAndDescribe, hamming, matchFeatures, popcount } from './feature-matching/index.js';
+export type { FeatureOptions, FeatureSet, Keypoint, MatchOptions } from './feature-matching/index.js';
+export { phaseCorrelate } from './phase-correlation/index.js';
+export type { PhaseCorrelationResult } from './phase-correlation/index.js';
+export { findInliers, fitAffine, fitHomography, fitModel, fitSimilarity, minimumSamples, ransac } from './transform-fitting/index.js';
+export type { Correspondence, RansacOptions, RansacResult } from './transform-fitting/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/phase-correlation/index.d.ts

@@ -0,0 +1,4 @@
+/** Sub-pixel translation between two images, from the FFT. */
+export { phaseCorrelate } from './phase-correlate.use-case.js';
+export type { PhaseCorrelationResult } from './phase-correlate.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/phase-correlation/phase-correlate.use-case.d.ts

@@ -0,0 +1,34 @@
+import type { GrayImage } from '@scanmate/ink';
+/**
+ * Global translation from the Fourier shift theorem.
+ *
+ * Shifting an image does not change the magnitude of its spectrum, only the
+ * phase — and it changes the phase by an amount proportional to the shift. So
+ * divide out the magnitudes entirely, keep the phase difference, transform
+ * back, and what comes out is a single spike at the offset between the two
+ * images.
+ *
+ * Its value here is that it does not care what is *on* the page. Feature
+ * matching needs corners to match; a mostly blank form does not have enough of
+ * them, and neither does a page that scanned faint. Phase correlation uses
+ * every pixel at once, which makes it the fallback when features fail, and a
+ * good final polish when they succeed.
+ *
+ * It only finds translation. Rotation and scale have to be dealt with first.
+ */
+export interface PhaseCorrelationResult {
+    /** Shift that takes `a` onto `b`: a feature at `p` in `a` sits at `p + (dx, dy)` in `b`. */
+    dx: number;
+    dy: number;
+    /** Height of the correlation spike. Near 1 is a clean single answer; near 0 is noise. */
+    peak: number;
+}
+/**
+ * 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.
+ */
+export declare function phaseCorrelate(a: GrayImage, b: GrayImage): PhaseCorrelationResult;
+//# sourceMappingURL=phase-correlate.use-case.d.ts.map

package/dist/src/scan-alignment/align-pages.use-case.d.ts

@@ -0,0 +1,22 @@
+import type { AlignedPage, ProgressCallback, ScanPage } from '@scanmate/ink';
+import type { AlignOptions, AlignResult } from './align-result.contract.js';
+export interface AlignPagesOptions extends AlignOptions {
+    /** Called before and after each page. The only logging seam - see `StageEvent` in `@scanmate/ink`. */
+    onProgress?: ProgressCallback;
+}
+/**
+ * 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.
+ */
+export declare function alignPages<Page extends ScanPage>(pages: readonly Page[], options?: AlignPagesOptions): Promise<Array<Page & AlignedPage<AlignResult>>>;
+//# sourceMappingURL=align-pages.use-case.d.ts.map

package/dist/src/scan-alignment/align-result.contract.d.ts

@@ -0,0 +1,116 @@
+import type { AlignedImage, ImageFormat, InkOptions, Interpolation, TransformModel, TransformSummary } from '@scanmate/ink';
+export interface AlignOptions {
+    /**
+     * Transform family to fit, or `'all'` to let the page decide.
+     *
+     * `'all'` (the default) tries the families in {@link AlignOptions.models}
+     * order, cheapest and most robust first, and stops at the first one that
+     * reaches {@link AlignOptions.confidenceTarget}. Name one family to fit only
+     * that: `similarity` for a flatbed or sheet-fed scan, which can only turn,
+     * resize and move a flat page; `affine` when one axis is stretched;
+     * `homography` for a photograph taken off-axis, where the far edge of the page
+     * is genuinely smaller than the near one.
+     */
+    model?: TransformModel | 'all';
+    /**
+     * With `model: 'all'`, stop trying further models once one reaches this
+     * confidence, in `[0, 1]`. A value above 1 is never reached, so every model
+     * is tried. Default `0.9`.
+     */
+    confidenceTarget?: number;
+    /** With `model: 'all'`, which families to try and in what order. */
+    models?: readonly TransformModel[];
+    /**
+     * With `model: 'all'`, how much a more complex model must beat a simpler one
+     * by to replace it. Without it, a homography wins on a flat page by fitting
+     * the page's noise. Default `0.02`.
+     */
+    modelPreferenceMargin?: number;
+    /** Longest side used for feature detection. Bigger is more precise and quadratically slower. */
+    workingSize?: number;
+    /** Longest side used for the coarse guess. */
+    coarseSize?: number;
+    maxFeatures?: number;
+    /** Inlier radius for RANSAC, in working-resolution pixels. */
+    ransacThreshold?: number;
+    /** Fewer surviving correspondences than this and the feature stage is not trusted. */
+    minInliers?: number;
+    /** Largest per-page skew the coarse stage considers, in degrees. */
+    maxSkewDeg?: number;
+    /** Cap on how much bigger or smaller the scan may be than the original. */
+    maxScaleRatio?: number;
+    /** How far a correspondence may move, as a fraction of the page diagonal, after the coarse warp. */
+    maxDisplacementRatio?: number;
+    /** Background/ink separation. The defaults suit printed pages on white. */
+    ink?: InkOptions;
+    interpolation?: Interpolation;
+    /** RGBA fill where the scan does not cover the original's canvas. */
+    background?: [number, number, number, number];
+    /** Encoding of `result.image`. `'none'` skips encoding, which is most of the cost on a big page. */
+    output?: ImageFormat | 'none';
+    /** Quality when `output` is a lossy format. */
+    quality?: number;
+    /** Seeds RANSAC and the descriptor pattern, so the same input gives the same matrix. */
+    seed?: number;
+}
+/** One model the sweep tried, and how it did. */
+export interface ModelAttempt {
+    model: TransformModel;
+    /** `null` when RANSAC found no consensus, so the model was never scored. */
+    confidence: number | null;
+    inliers: number;
+    inlierRatio: number;
+    /** Mean RANSAC reprojection error over the inliers, in working-resolution pixels. `NaN` when rejected. */
+    reprojectionError: number;
+    /** RANSAC found no consensus worth trusting for this model. */
+    rejected: boolean;
+    /** This attempt's transform is the one returned. */
+    selected: boolean;
+}
+export interface AlignDiagnostics {
+    coarseScore: number;
+    coarseStrategy: string;
+    /** Each page's own skew, in degrees, as measured independently. */
+    skewDeg: {
+        original: number;
+        scanned: number;
+    };
+    features: {
+        original: number;
+        scanned: number;
+    };
+    matches: number;
+    /** Inliers behind the returned transform. Zero when the coarse estimate was returned. */
+    inliers: number;
+    inlierRatio: number;
+    /** Mean RANSAC reprojection error over the returned model's inliers, in working-resolution pixels. */
+    reprojectionError: number;
+    /** Ink correlation after alignment, in `[-1, 1]`. */
+    correlation: number;
+    /** Ink mask overlap after alignment, in `[0, 1]`. */
+    intersectionOverUnion: number;
+    /**
+     * The family of the returned transform. The coarse estimate is itself a
+     * similarity, so a coarse fallback reports `similarity` - `method` says which.
+     */
+    selectedModel: TransformModel;
+    /** Every model tried, in order. Its length says whether the sweep stopped early. */
+    attempts: ModelAttempt[];
+    /** Milliseconds spent, end to end. */
+    durationMs: number;
+}
+export interface AlignResult extends AlignedImage {
+    transform: TransformSummary;
+    /**
+     * How much to trust the result, in `[0, 1]`.
+     *
+     * Derived from ink correlation after warping, so it measures agreement in the
+     * output rather than confidence in the process. Above ~0.6 is a solid match on
+     * a printed page; below ~0.3 treat the alignment as failed.
+     */
+    confidence: number;
+    /** `features` when RANSAC found a consensus, `coarse` when the coarse estimate had to stand alone. */
+    method: 'features' | 'coarse';
+    diagnostics: AlignDiagnostics;
+}
+//# sourceMappingURL=align-result.contract.d.ts.map

package/dist/src/scan-alignment/align-scan.use-case.d.ts

@@ -0,0 +1,59 @@
+import type { ImageInput } from '@scanmate/ink';
+import type { AlignOptions, AlignResult } from './align-result.contract.js';
+/**
+ * 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.
+ */
+export declare function alignScan(original: ImageInput, scanned: ImageInput, options?: AlignOptions): Promise<AlignResult>;
+//# sourceMappingURL=align-scan.use-case.d.ts.map

package/dist/src/scan-alignment/alignment-referee.use-case.d.ts

@@ -0,0 +1,19 @@
+import type { GrayImage, Matrix3 } from '@scanmate/ink';
+/**
+ * How well a proposed transform actually lines the two pages up.
+ *
+ * Every candidate in a model sweep is judged the same way, on the same two
+ * downscaled ink maps, so the downscales - and the original's mask - are done
+ * once when the referee is created rather than once per candidate. What is left
+ * per call is one warp and two scores.
+ */
+export interface Agreement {
+    /** Ink correlation after warping, in `[-1, 1]`. */
+    correlation: number;
+    /** Ink mask overlap after warping, in `[0, 1]`. */
+    iou: number;
+}
+export declare function createReferee(originalInk: GrayImage, scannedInk: GrayImage, workingSize: number): (matrix: Matrix3) => Agreement;
+/** A correlation as a confidence: clamped to `[0, 1]`, because anti-correlated ink is no alignment at all. */
+export declare function toConfidence(agreement: Agreement): number;
+//# sourceMappingURL=alignment-referee.use-case.d.ts.map

package/dist/src/scan-alignment/feature-refinement.use-case.d.ts

@@ -0,0 +1,52 @@
+import type { GrayImage, Matrix3, PointMatch, TransformModel } from '@scanmate/ink';
+import type { CoarseResult } from '../coarse-estimation/index.js';
+/**
+ * Feature refinement, in two halves so that trying several models costs one
+ * feature pass rather than one per model.
+ *
+ * Matching is done between the original and the *coarsely corrected* scan, and
+ * that is what makes the whole thing work: the two now sit at the same scale and
+ * nearly the same angle, so a fixed-offset binary descriptor describes the same
+ * thing on both, and a correspondence that jumps across the page can be rejected
+ * on sight. What RANSAC recovers is only the small residual, which is then
+ * composed onto the coarse transform.
+ *
+ * Everything in {@link prepareMatches} - two downscales, a rough warp, ORB on
+ * both pages and the brute-force matcher - is independent of which transform
+ * family is about to be fitted, and it is nearly all of the cost. Only
+ * {@link fitResidual} depends on the model, and it touches no pixels at all.
+ */
+export interface MatchingOptions {
+    workingSize: number;
+    maxFeatures: number;
+    maxDisplacementRatio: number;
+    seed: number;
+}
+/** Everything the model fits share. Compute once, fit many. */
+export interface PreparedMatches {
+    matches: PointMatch[];
+    features: {
+        original: number;
+        scanned: number;
+    };
+    /** How much the original was shrunk to its working frame; lifts a residual back to full resolution. */
+    scale: number;
+}
+export declare function prepareMatches(originalInk: GrayImage, scannedInk: GrayImage, coarse: CoarseResult, options: MatchingOptions): PreparedMatches;
+export interface FittingOptions {
+    ransacThreshold: number;
+    minInliers: number;
+    seed: number;
+}
+/** One model's answer: the full transform, and how much of the evidence agreed with it. */
+export interface ResidualFit {
+    /** Maps full-resolution original coordinates to full-resolution scan coordinates. */
+    matrix: Matrix3;
+    inliers: number;
+    inlierRatio: number;
+    /** Mean RANSAC reprojection error over the inliers, in working-resolution pixels. */
+    reprojectionError: number;
+}
+/** Fit one model to the shared matches, or `null` when RANSAC finds no consensus worth trusting. */
+export declare function fitResidual(prepared: PreparedMatches, coarse: CoarseResult, model: TransformModel, options: FittingOptions): ResidualFit | null;
+//# sourceMappingURL=feature-refinement.use-case.d.ts.map

package/dist/src/scan-alignment/index.d.ts

@@ -0,0 +1,9 @@
+/** The whole alignment: decode, estimate, pick a model, warp, and say how far to trust it. */
+export { alignPages } from './align-pages.use-case.js';
+export type { AlignPagesOptions } from './align-pages.use-case.js';
+export type { AlignDiagnostics, AlignOptions, AlignResult, ModelAttempt } from './align-result.contract.js';
+export { alignScan } from './align-scan.use-case.js';
+export { DEFAULT_MODELS, prefers } from './model-selection.policy.js';
+export type { ScoredModel } from './model-selection.policy.js';
+export { polishTranslation } from './polish-translation.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/scan-alignment/model-selection.policy.d.ts

@@ -0,0 +1,34 @@
+import type { TransformModel } from '@scanmate/ink';
+/**
+ * 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. */
+export declare const DEFAULT_MODELS: readonly TransformModel[];
+/** A fitted model and how well it did. */
+export interface ScoredModel {
+    model: TransformModel;
+    confidence: number;
+}
+/**
+ * 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.
+ */
+export declare function prefers(candidate: ScoredModel, incumbent: ScoredModel | null, margin: number): boolean;
+/** The models to sweep, in the order given, each once. Throws on an empty list rather than silently fitting nothing. */
+export declare function sweepOrder(models: readonly TransformModel[]): TransformModel[];
+//# sourceMappingURL=model-selection.policy.d.ts.map

package/dist/src/scan-alignment/polish-translation.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { GrayImage, Matrix3 } from '@scanmate/ink';
+/**
+ * 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.
+ */
+export declare function polishTranslation(originalInk: GrayImage, scannedInk: GrayImage, matrix: Matrix3, workingSize?: number): Matrix3;
+//# sourceMappingURL=polish-translation.use-case.d.ts.map

package/dist/src/transform-fitting/fit-transform.use-case.d.ts

@@ -0,0 +1,41 @@
+import type { Matrix3, PointMatch, TransformModel } from '@scanmate/ink';
+/**
+ * Fitting a transform to a set of correspondences.
+ *
+ * Three models, and the choice between them is a bet about what the scan went
+ * through. A flatbed scanner moves the page in one plane, so a **similarity**
+ * (turn it, resize it, slide it) is the whole story and its four parameters
+ * are pinned down by very few points — which is exactly what you want when
+ * most of your matches are wrong. A sheet-fed scanner can stretch one axis;
+ * that needs **affine**. A photograph taken at an angle needs the full
+ * **homography**, and pays for those eight parameters by being far easier to
+ * fit to nonsense.
+ *
+ * Prefer the simplest model the physical situation allows.
+ */
+/** Correspondences the fitters consume. `distance` is ignored here. */
+export type Correspondence = Pick<PointMatch, 'source' | 'target'>;
+/** How many correspondences the model needs before it is determined at all. */
+export declare function minimumSamples(model: TransformModel): number;
+export declare function fitModel(model: TransformModel, matches: readonly Correspondence[], indices?: readonly number[]): Matrix3 | null;
+/**
+ * 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.
+ */
+export declare function fitSimilarity(matches: readonly Correspondence[], indices?: readonly number[]): Matrix3 | null;
+/** Least-squares affine: two independent 3x3 normal systems sharing one matrix. */
+export declare function fitAffine(matches: readonly Correspondence[], indices?: readonly number[]): Matrix3 | null;
+/**
+ * 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.
+ */
+export declare function fitHomography(matches: readonly Correspondence[], indices?: readonly number[]): Matrix3 | null;
+//# sourceMappingURL=fit-transform.use-case.d.ts.map

package/dist/src/transform-fitting/index.d.ts

@@ -0,0 +1,6 @@
+/** Fitting a similarity, affine or homography to correspondences, and RANSAC to find which ones to trust. */
+export { fitAffine, fitHomography, fitModel, fitSimilarity, minimumSamples } from './fit-transform.use-case.js';
+export type { Correspondence } from './fit-transform.use-case.js';
+export { findInliers, ransac } from './ransac.use-case.js';
+export type { RansacOptions, RansacResult } from './ransac.use-case.js';
+//# sourceMappingURL=index.d.ts.map