@scanmate/ocr 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Russo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+![scanmate ocr](./scanmate-ocr.svg)
+
+# `@scanmate/ocr`
+
+Measures how closely a scan's text matches the original's: a score per page and for the document, ten measures, both texts in full, and every difference with its position on the page.
+
+```ts
+import { alignPages } from '@scanmate/align'
+import { extractPair } from '@scanmate/extract'
+import { ocrPages } from '@scanmate/ocr'
+
+const { pages } = await extractPair({ original: 'contract.pdf', scanned: 'returned.pdf' })
+const report = await ocrPages(await alignPages(pages))
+
+report.score                     // document score, weighted by characters
+report.pages[0].metrics          // levenshtein, jaccard, dice, cosine, CER, WER, word recall, ...
+report.pages[0].differences      // { kind: 'changed' | 'missing' | 'added', expected, found, x, y, ... }
+report.pages[0].original.text    // the original's text
+report.pages[0].scanned.text     // the scan's
+```
+
+## How it reads
+
+- **The original's side** comes from its PDF text layer whenever it has one. The layer is exact, so every error counted belongs to the scan. The scan's own text layer is never used, because hidden or stale text must not vouch for what the paper shows.
+- **The scan** is read with tesseract, at 300 dpi (it is enlarged first if lower), or from its `enhanced` image when `@scanmate/enhance` ran first.
+- **Matching by place, not order.** Alignment puts the scan on the original's canvas, so each word read is claimed by the run of the original printed where it was read. A two-column page read column by column is therefore not a page of errors, and every difference has a position.
+- **Figures must keep their digits.** A run whose digits read back differently has changed, however similar the rest is: "Total 1,250.00" read as "Total 7,250.00" is 93% similar. A figure whose separators alone differ ("5.768.700 00") is the same figure. Words keep OCR's tolerance (`matchThreshold`, 0.8).
+- **What is not an addition.** Words over something the original prints without text, such as a logo, are not additions. Nor are specks under 4 pt tall.
+
+## The recheck
+
+Before a run counts as a difference, it is cropped and re-read on its own, in up to six passes:
+
+- enlarged to 300–600 dpi;
+- read as a line or as a single word;
+- read as digits only, when the run is a figure;
+- with contrast stretched, and with light-on-dark text inverted.
+
+A run is cleared only when **two** passes agree with the original, judged by the same rules as the page. A single agreeing pass let forged digits through on a 93-dpi scan. Set `recheck: false` to report the page reading as it is.
+
+Measured on three real scans of a 7-page order form, with the text layer as ground truth:
+
+| Scan | Score | False differences | One-digit forgeries flagged |
+|---|---|---|---|
+| 144 dpi | 0.997 | 0 | 4/4 |
+| 120 dpi | 0.934 | 20 (217 without the recheck) | 4/4 |
+| 93 dpi | 0.660 | many: below what OCR can verify | 4/4, among many misreadings |
+
+## Text normalisation
+
+Text is normalised the same way on both sides before comparing: NFKC, typography (quotes, dashes, spaces), line-end hyphens, diacritics (the project's 86-base table), case, and OCR noise such as table rules and specks. Punctuation and OCR confusables (`0/o`, `1/l`, `rn/m`) are **kept** by default. Folding them hides exactly the substitutions a forger makes. Every step is an option (`normalise`).
+
+## The engine, and writing nothing to disk
+
+tesseract.js 7 (WebAssembly) with the English best_int model, which read as well as the standard model on real scans at a quarter of the size. Other languages: `npm install @tesseract.js-data/<code>` and pass `tesseract: { languages: ['eng', 'por'] }`.
+
+Nothing is downloaded and, by default, nothing is written. This matters where deployments are read-only, as on Azure Functions: tesseract.js would otherwise cache language data in the current directory. The only writes are explicit:
+
+| Option | Default | |
+|---|---|---|
+| `tesseract.cache.method` | `'none'` | `'write'` keeps unpacked data for reuse; `'readOnly'` uses data a previous run left; `'refresh'` rewrites it. |
+| `tesseract.cache.path` | `<os temp>/scanmate-ocr` | Where anything written goes, including language files staged when more than one language is read. |
+| `tesseract.model` | `'best'` | `'standard'` for the larger 4.0.0 model. |
+| `tesseract.languageData` | the data packages | A folder of `<code>.traineddata.gz` files instead. |
+
+`createTesseractEngine()` returns an engine whose `settings` report exactly what was resolved. Pass it as `engine` to share one across calls and pay the start-up once. Any other OCR engine can be used by implementing `OcrEngine`.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `original` | `'auto'` | Text layer when the original has one; `'text-layer'` insists on it; `'ocr'` always reads the original. |
+| `targetDpi` | `300` | Enlarge below this before reading; `null` reads the image as it is. |
+| `scoreMetric` | `'levenshteinSimilarity'` | Or `'wordRecall'`, `'jaccard'`, `'dice'`, `'cosine'`. |
+| `matchThreshold` | `0.8` | Word similarity below which a run has changed. |
+| `minWordConfidence` | `60` | For words to count as added. |
+| `recheck` | on | `{ passes, agree }`, or `false`. |

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";