@scanmate/image-fix 0.0.3 → 0.0.5

package/README.md

@@ -1,69 +1,40 @@
-# @scanmate/image-fix
+# `@scanmate/image-fix`
 
-Put a scanned page back on top of the page it came from.
+> **Deprecated Facade Package.** `@scanmate/image-fix` has been split into focused, modular packages. This package remains available as a backward-compatible facade re-exporting all core APIs.
 
-You render page 1 of a PDF, you send the document out, and a photograph or a
-flatbed scan of it comes back — turned a couple of degrees, at some other
-resolution, cropped differently, under a shadow. Two questions are then almost
-impossible to answer:
+---
 
-1. **Was any of the printed text changed?** OCR both and diff, in principle.
-   In practice, an OCR engine reads a crooked page at a different scale as a
-   different document: line grouping differs, so the diff is noise.
-2. **Was the box at (x, y) signed?** That question is about a fixed rectangle,
-   and a rectangle only means something once both images agree where (x, y) is.
+## Modern Package Structure
 
-This library answers the geometry so you can answer those. Give it the original
-and the scan; it gives you the scan resampled onto the original's canvas, plus
-the transform it used and how much it trusts it.
+For all new projects and upgrades, prefer importing directly from the focused packages:
 
-**Pure JavaScript. No native bindings.** OpenCV and `sharp` are both off the
-table when the target is an Azure Function app: they compile per platform, so
-the bytes that work on your laptop are not the bytes that run in the cloud, and
-a deployment that skips the rebuild fails at *import* time — after the cold
-start, in production. Everything here runs the same everywhere.
+| You used in `@scanmate/image-fix` | Now lives in package | Primary Purpose |
+|---|---|---|
+| `alignScan`, `alignPages`, `polishTranslation`, estimators | **[`@scanmate/align`](../align)** | Geometric registration & alignment |
+| `compareRegions`, `diffDocument`, `renderDiff`, `diffPage` | **[`@scanmate/diff`](../diff)** | Visual change detection & form region verification |
+| `decodeImage`, `encodeImage`, `inkMap`, `warpRaster`, `Matrix3` | **[`@scanmate/ink`](../ink)** | Low-level pixel kernel, illumination division & geometry |
+| `extractPair`, `extractPages`, `inspectPage`, `renderPage` | **[`@scanmate/extract`](../extract)** | PDF document rendering, inspection & DPI auto-resolution |
 
-## Install
+---
 
-```sh
-npm install @scanmate/image-fix
-```
-
-## Quick start
-
-```ts
-import { readFile } from 'node:fs/promises'
-import { alignScan, compareRegions } from '@scanmate/image-fix'
-
-const original = await readFile('contract.page1.png')   // rendered from the PDF
-const scanned = await readFile('returned.jpg')          // what came back
-
-const result = alignScan(original, scanned)
-
-console.log(result.confidence)                // 0.96
-console.log(result.transform.rotationDeg)     // -2.68
-console.log(result.transform.scaleX)          // 1.449
+## Architectural Changes & Breaking Notes
 
-// result.raster is on the original's canvas, so PDF coordinates still hold.
-const [signature] = compareRegions(original, result.raster, [
-  { id: 'signature', rect: { x: 76, y: 905, width: 420, height: 78 } },
-])
+1. **Asynchronous Codec Operations**: All functions that encode or decode images (`decodeImage`, `encodeImage`, `alignScan`, `compareRegions`, `diffDocument`, `renderDiff`) are now **asynchronous** (`Promise`-based) because the image codec migrated to libvips via `sharp`. This yields a **~20x speedup** when encoding full-page PNGs and enables native support for TIFF, HEIF, WebP, and AVIF formats.
+2. **Metadata Inspection**: `sniffFormat` has been replaced by `readImageMetadata` in `@scanmate/ink`.
 
-console.log(signature.filled)   // true
-console.log(signature.added)    // 0.056 - 5.6% of the box is ink that is not in the original
-```
+---
 
-`result.image` is the aligned page as PNG bytes, ready to hand to an OCR
-engine. `result.raster` is the same thing undecoded, if your OCR engine takes
-raw RGBA.
+## Installation
 
-## How it works
+```bash
+# Using npm
+npm install @scanmate/image-fix
 
-```text
-  decode ─► ink ─► coarse guess ─► rough warp ─► ORB features ─► RANSAC ─► warp
-                   scale + skew                  + matching      + model
+# Or install the modular packages directly:
+npm install @scanmate/align @scanmate/diff @scanmate/ink @scanmate/extract
 ```
 
+---
 > What follows is the reasoning. For the full algorithm - the formulae, every
 > constant, the coordinate-frame algebra and the measured error - see
 > [`documentation/fix.md`](https://github.com/russoedu/scanmate/blob/main/documentation/fix.md).
@@ -110,182 +81,126 @@ FAST corners, oriented by the intensity centroid of their patch, described by
 256 steered BRIEF bits — an ORB, written out, because the native one is
 unavailable here.
 
-Running this *after* the coarse warp is what makes it work. The two images are
-now at the same scale and nearly the same angle, so a fixed-offset descriptor
-describes the same thing on both, and any correspondence that jumps across the
-page can be thrown out on sight. RANSAC then recovers only the small residual,
-which is composed onto the coarse transform.
-
-RANSAC is not optional. A page of text is full of things that genuinely look
-identical — every lowercase "e", every corner of every table cell — so matching
-produces a lot of confident nonsense, and least squares over all of it is
-dragged wherever the wrong matches point. RANSAC ignores the average: it fits
-the smallest sample that determines a transform and counts how many of the rest
-agree. Measured on the test suite, it recovers the right answer with 60% of the
-matches wrong.
-
-If the feature stage comes up short — a near-blank form has few corners — the
-coarse estimate is returned alone and `result.method` says `'coarse'`.
-
-### 4. The warp
-
-Inverse mapping: walk each output pixel and reach back into the scan, rather
-than pushing scan pixels forward, which leaves the output full of pinholes
-wherever the transform stretches, like spray-painting through a rotated
-stencil. Minification pre-filters first, so shrinking a 300 dpi scan averages
-the strokes instead of beating against them into moiré.
-
-## Choosing a model
+## Quick Start
 
-The `model` option is a bet about what the scan physically went through. Fewer
-degrees of freedom is harder to fool; more is more expressive.
-
-| model | DOF | use when |
-| --- | --- | --- |
-| `similarity` (default) | 4 | a flatbed or sheet-fed scan. The page is flat, so it can only be turned, resized and moved. |
-| `affine` | 6 | one axis is stretched — a feed roller slipping. |
-| `homography` | 8 | a photograph taken off-axis, where the far edge of the page really is smaller than the near one. |
-
-Use the simplest one the physical situation allows. A homography fitted to a
-flatbed scan has four extra parameters to spend on fitting noise.
-
-## API
+```ts
+import { alignScan, compareRegions, decodeImage } from '@scanmate/image-fix'
+import { readFile } from 'node:fs/promises'
 
-### `alignScan(original, scanned, options?): AlignResult`
+const original = await decodeImage(await readFile('contract_p1.png'))
+const scanned = await decodeImage(await readFile('returned_scan.jpg'))
 
-Synchronous, deliberately. All of it is CPU-bound with no I/O to wait on; an
-`async` signature would imply the event loop is free during the call, and it is
-not. To align several pages at once, put it in a worker thread.
+const result = await alignScan(original, scanned, { model: 'similarity' })
 
-Inputs are PNG or JPEG bytes (`Buffer`, `Uint8Array`, `ArrayBuffer`) or an
-already-decoded `Raster`, so you can decode once and align one page against
-several scans.
+const [sigReport] = compareRegions(original, result.raster, [
+  { id: 'signature', rect: { x: 76, y: 905, width: 420, height: 78 } },
+])
+```
 
-```ts
-interface AlignResult {
-  raster: Raster          // the scan, on the original's canvas
-  image: Uint8Array | null // encoded per options.output
-  matrix: Matrix3         // original coordinates -> scanned coordinates
-  inverse: Matrix3        // scanned -> original
-  transform: TransformSummary   // scale, rotation, shear, translation
-  confidence: number      // 0..1, from ink correlation after warping
-  method: 'features' | 'coarse'
-  diagnostics: AlignDiagnostics
-}
+---
+
+## Facade Architecture & Dependency Topology
+
+```mermaid
+flowchart TD
+    App["Application / Legacy Caller"] --> Facade["@scanmate/image-fix<br/>(Backward Compatibility Facade)"]
+    
+    subgraph ModularPackages["ScanMate Core Ecosystem"]
+        Align["@scanmate/align<br/>Registration & RANSAC Engine"]
+        Diff["@scanmate/diff<br/>Change Detection & Region Reports"]
+        Extract["@scanmate/extract<br/>PDF Parsing & Skia Rendering"]
+        Ink["@scanmate/ink<br/>Pixel Kernel & Sharp Codec"]
+    end
+
+    Facade --> Align
+    Facade --> Diff
+    Facade --> Extract
+    Facade --> Ink
+
+    Align --> Ink
+    Diff --> Ink
+    Extract --> Ink
+    Diff -. optional .-> Align
+    Extract -. optional .-> Align
 ```
 
-`confidence` measures agreement in the *output*, not confidence in the process.
-Above ~0.6 is a solid match on a printed page; below ~0.3, treat the alignment
-as failed and do not trust any region report built on it.
+---
 
-Useful options (all optional):
+## Comprehensive Re-Export API Reference
 
-| option | default | what it does |
-| --- | --- | --- |
-| `model` | `'similarity'` | see above |
-| `workingSize` | `1400` | longest side for feature detection. Bigger is more precise and quadratically slower |
-| `coarseSize` | `512` | longest side for the coarse guess |
-| `maxFeatures` | `1200` | keypoint budget per image |
-| `ransacThreshold` | `3` | inlier radius, in working-resolution pixels |
-| `minInliers` | `12` | below this the feature stage is not trusted |
-| `maxSkewDeg` | `12` | largest per-page skew considered |
-| `interpolation` | `'bilinear'` | or `'bicubic'` (sharper strokes when upscaling), `'nearest'` |
-| `background` | white | RGBA fill where the scan does not cover the canvas |
-| `output` | `'png'` | `'jpeg'` or `'none'`. Encoding is most of the cost on a big page |
-| `seed` | fixed | seeds RANSAC and the descriptor pattern, so the same bytes give the same matrix |
-
-### `compareRegions(original, aligned, regions, options?): RegionReport[]`
-
-Answers "was this box filled in?" as arithmetic: count the ink inside the
-rectangle that is in the scan and not in the original.
+### 1. Alignment Methods (Delegates to [`@scanmate/align`](../align))
 
-```ts
-const reports = compareRegions(original, result.raster, [
-  { id: 'signature', rect: { x: 76, y: 905, width: 420, height: 78 } },
-  { id: 'consent', rect: { x: 76, y: 800, width: 18, height: 18 }, threshold: 0.05 },
-])
-```
+#### `alignScan(original, scanned, options?: AlignOptions): Promise<AlignResult>`
+Resamples scanned page onto original canvas.
+- **Options**:
+  - `model` (`'similarity'` | `'affine'` | `'homography'`, default: `'similarity'`): Geometric model.
+  - `workingSize` (default: 1400): Longest dimension for feature matching.
+  - `coarseSize` (default: 512): Initial coarse sweep resolution.
+  - `maxFeatures` (default: 1200): ORB keypoint cap per image.
+  - `ransacThreshold` (default: 3.0): Inlier reprojection error bound in px.
+  - `minInliers` (default: 12): Minimum inliers needed to trust feature stage.
+  - `interpolation` (`'bilinear'` | `'bicubic'` | `'nearest'`): Resampling kernel.
+  - `output` (`'png'` | `'jpeg'` | `'none'`): Encoded output format.
 
-Rectangles are in the **original's** coordinates — which is the whole point of
-aligning first. Passing a raw scan produces confident nonsense, so the function
-refuses two images on different canvases outright.
+#### `alignPages(pages, options?: AlignPagesOptions): Promise<AlignedPage[]>`
+Multi-page document batch alignment handler.
 
-The `tolerance` option (default 2 px) fattens the original's ink before
-diffing. Alignment is good to about a pixel, never to zero, and printed text is
-mostly edges, so without it a half-pixel shift lights up the outline of every
-character as new ink — the way a proofreader ignores a letter sitting a hair
-off the baseline. What it cannot absorb is a signature, which is ink where the
-original has none.
+---
 
-`filled` is `added >= threshold` (default 2% of the region). `score` is `added`
-as a multiple of that threshold, clamped to 1, if you want a number rather than
-a boolean.
+### 2. Diffing & Change Detection (Delegates to [`@scanmate/diff`](../diff))
 
-### `diffDocument(original, aligned, regions?, options?)`
+#### `compareRegions(original, aligned, regions, options?: RegionOptions): RegionReport[]`
+Evaluates form fields to check if signatures or checkboxes were filled.
+- **Options**:
+  - `tolerance` (default: 2): Morphological dilation radius in pixels.
+  - `threshold` (default: 0.02): Added ink ratio for `filled: true`.
 
-Page-wide added/removed ink plus the same per-region detail, in one pass.
-A useful pre-check before OCR: if `added` across the whole page is under ~2%,
-nothing was written on it.
+#### `diffDocument(original, aligned, regions?, options?: RegionOptions): DocumentDiff`
+Computes whole-page and per-region ink addition/subtraction metrics in one pass.
 
-### `renderDiff(original, aligned, options?): Raster`
+#### `renderDiff(original, aligned, options?: RegionOptions): Raster`
+Renders 4-color RGBA visual overlay (Red = scan additions, Blue = template deletions, Grey = matched ink).
 
-An RGBA overlay to look at with your own eyes. Red is ink the scan added, blue
-is ink it lost, grey is ink both agree on. A correctly aligned signed form is
-almost entirely grey with a red signature; a misaligned one is red and blue
-confetti along every stroke — the fastest way to tell those two failures apart.
+#### `diffPage(options: DiffOptions): Promise<PageDiff>`
+Full page change detection isolating unexpected handwritten edits via 2-pass connected component analysis.
 
-### Building blocks
+---
 
-The stages are exported individually, for pipelines that need to stop part way:
-`decodeImage`, `encodeImage`, `toGrayscale`, `inkMap`, `binarize`, `dilate`,
-`estimateSkew`, `contentExtent`, `estimateCoarse`, `detectAndDescribe`,
-`matchFeatures`, `fitSimilarity` / `fitAffine` / `fitHomography`, `ransac`,
-`phaseCorrelate`, `warpRaster`, `warpGray`, and the `Matrix3` helpers.
+### 3. Kernel & Pixel Operations (Delegates to [`@scanmate/ink`](../ink))
 
-### Test fixtures
+#### `decodeImage(buffer, options?: DecodeOptions): Promise<Raster>`
+Decodes image bytes to RGBA `Raster` via `sharp`.
+- **Options**: `pageNumber` (for multi-page TIFF), `maxWidth`, `maxHeight`.
 
-`createSyntheticDocument`, `simulateScan`, `drawSignature` and `drawTick`
-generate a printed form and a realistically bad scan of it, with the ground
-truth matrix returned alongside. They are exported rather than kept in the test
-folder because the same trick smoke-tests a deployment without shipping sample
-scans:
+#### `encodeImage(raster, options?: EncodeOptions): Promise<Uint8Array>`
+Encodes RGBA `Raster` to PNG/JPEG bytes via `sharp`.
+- **Options**: `format` (`'png'`, `'jpeg'`, `'webp'`, `'avif'`), `quality` (1-100), `compression` (0-9).
 
-```ts
-import { alignScan, createSyntheticDocument, simulateScan } from '@scanmate/image-fix'
+#### `inkMap(gray, options?: InkOptions): GrayImage`
+Performs background division ($I_{ink} = 1 - I / I_{bg}$).
+- **Options**: `blurRadius` (default: 25), `invert` (default: true).
 
-const page = createSyntheticDocument()
-const scan = simulateScan(page.raster, { rotationDeg: -2.7, scale: 1.45, noise: 0.02 })
-const result = alignScan(page.raster, scan.raster, { output: 'none' })
+#### `warpRaster(raster, output, invMatrix, options?: WarpOptions): void`
+Resamples input `Raster` using inverse 3x3 homography matrix.
+- **Options**: `interpolation` (`'bilinear'`, `'bicubic'`, `'nearest'`), `background` (`RGBA`).
 
-// result.matrix should agree with scan.matrix to about a pixel.
-```
+---
+
+### 4. PDF Extraction & Inspection (Delegates to [`@scanmate/extract`](../extract))
 
-## Limits
+#### `extractPair(options: ExtractPairOptions): Promise<PairedDocument>`
+Parses, auto-detects scan DPI, and renders paired original/scanned PDF pages.
+- **Options**: `original`, `scanned`, `dpi` (`'native'` or fixed number), `pageSelection`.
 
-- **One page at a time.** It aligns a scan to a page, not a multi-page PDF to a
-  multi-page scan. Split them first.
-- **The page must be recognisably the same page.** It is registration, not
-  retrieval: it will happily align the wrong document badly and tell you so
-  through a low `confidence`. Check that number.
-- **Flat pages only.** A creased or curled page needs a non-rigid warp;
-  `homography` will get the plane right and leave the curl.
-- **Not scale-free.** `maxScaleRatio` (default 6) bounds how far apart the two
-  resolutions may be. Beyond that, resample first.
-- **Blank pages degrade gracefully, not magically.** With almost no printing
-  there is nothing to register on; you get `method: 'coarse'` and a low
-  confidence, which is the honest answer.
+#### `inspectPage(pdf, pageIndex): Promise<PageMetadata>`
+Inspects PDF operator streams and classifies page as `'scanned'`, `'born-digital'`, or `'mixed'`.
 
-## Performance
+---
 
-Single-threaded, on one core: a 850x1100 original against a 1400x1800 scan runs
-in roughly 1.6 s, of which the feature stage is about half. Lower `workingSize`
-to trade accuracy for speed; set `output: 'none'` if you are going to hand
-`raster` straight to something else, since PNG encoding a big page is a
-substantial share of the total.
+## License
 
-Memory peaks at a few copies of the largest image. Nothing here streams, so a
-100 megapixel scan will hurt.
+MIT © [ScanMate Team](https://github.com/russoedu/scanmate)
 
-## Licence
+## Where the algorithms went
 
-MIT
+[`documentation/algorithms.md`](./documentation/algorithms.md) maps every algorithm this package used to carry to the package that documents it now.