@scanmate/ocr 0.0.3 → 0.1.0

package/dist/src/index.d.ts

@@ -30,8 +30,10 @@ export { compareTexts } from './text-similarity/index.js';
 export type { ScoreMetric, TextMetrics } from './text-similarity/index.js';
 export { DEFAULT_NORMALISE, normaliseText, tokenise } from './text-normalisation/index.js';
 export type { NormaliseOptions } from './text-normalisation/index.js';
-export { claimWords, DEFAULT_RECHECK_PASSES, judgeRun, judgeRuns, matchWords, printPolarity, recheckRun } from './page-reading/index.js';
-export type { Claims, MatchOptions, PrintPolarity, Recheck, RecheckOptions, RecheckPass, Reference, Verdict, WordMatch } from './page-reading/index.js';
+export { collectTemplates, FIGURE_CHARACTERS, glyphCells, glyphWords, placeGlyphs, printPolarity, templateKey, TEXT_CHARACTERS, verifyPrintedRun } from './print-verification/index.js';
+export type { Box, CellOptions, PrintedRun, PrintPolarity, PrintVerification, Templates, VerifyOptions } from './print-verification/index.js';
+export { claimWords, DEFAULT_RECHECK_PASSES, judgeRun, judgeRuns, matchWords, readRun, recheckRun } from './page-reading/index.js';
+export type { Claims, MatchOptions, Recheck, RecheckOptions, RecheckPass, Reference, Verdict, WordMatch } from './page-reading/index.js';
 export { cosine, dice, jaccard, jaroWinkler, levenshtein, levenshteinSimilarity, wordDistance, wordRecall } from './text-similarity/index.js';
 export { diacriticsMap, foldConfusables, foldDiacritics } from './text-normalisation/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-reading/index.d.ts

@@ -3,6 +3,6 @@ export { claimWords, judgeRun, judgeRuns, matchWords } from './match-words.use-c
 export type { Claims, MatchOptions, Reference, Verdict, WordMatch } from './match-words.use-case.js';
 export { ocrPages } from './ocr-pages.use-case.js';
 export type { OcrOptions, OcrReport, PageOcr, PlacedText, PositionedText, ReadablePage, RunReading, SideText, TextDifference } from './ocr-report.contract.js';
-export { DEFAULT_RECHECK_PASSES, printPolarity, recheckRun } from './recheck-run.use-case.js';
-export type { PrintPolarity, Recheck, RecheckOptions, RecheckPass } from './recheck-run.use-case.js';
+export { DEFAULT_RECHECK_PASSES, readRun, recheckRun } from './recheck-run.use-case.js';
+export type { Recheck, RecheckOptions, RecheckPass } from './recheck-run.use-case.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-reading/match-words.use-case.d.ts

@@ -59,7 +59,12 @@ export declare function claimWords(references: readonly Reference[], words: read
  * and read within the similarity threshold.
  */
 export declare function judgeRun(expected: string, found: string, options: MatchOptions): Verdict;
-export declare function judgeRuns(references: readonly Reference[], claims: Claims, options: MatchOptions): WordMatch;
+/**
+ * @param verified - Runs the print check matched glyph by glyph and found
+ *   changed. Their differences are evidence in themselves; every other one is
+ *   a reading, which the pixels still have to agree with.
+ */
+export declare function judgeRuns(references: readonly Reference[], claims: Claims, options: MatchOptions, verified?: ReadonlySet<number>): WordMatch;
 /** Claim and judge in one go, for a page read once. */
 export declare function matchWords(references: readonly Reference[], words: readonly PlacedText[], lineOf: readonly number[], options: MatchOptions): WordMatch;
 //# sourceMappingURL=match-words.use-case.d.ts.map

package/dist/src/page-reading/ocr-report.contract.d.ts

@@ -1,5 +1,6 @@
 import type { AlignedPage, PageImage, ProgressCallback } from '@scanmate/ink';
 import type { OcrEngine, TesseractEngineOptions } from '../ocr-engine/index.js';
+import type { VerifyOptions } from '../print-verification/index.js';
 import type { RecheckOptions } from './recheck-run.use-case.js';
 import type { NormaliseOptions } from '../text-normalisation/index.js';
 import type { ScoreMetric, TextMetrics } from '../text-similarity/index.js';
@@ -11,6 +12,9 @@ export interface PositionedText {
     width: number;
     height: number;
     endsLine?: boolean;
+    /** How the run is set, when the text layer says: a figure is matched against glyphs of the same face and size. */
+    fontName?: string;
+    fontSize?: number;
 }
 /**
  * What `ocrPages` reads: an aligned page, and optionally its enhanced image
@@ -56,6 +60,13 @@ export interface OcrOptions {
      * time; `false` reports the page reading as it is. See `recheckRun`.
      */
     recheck?: RecheckOptions | false;
+    /**
+     * Match every printed figure against the original's own glyphs instead of
+     * trusting what the scan reads there; `false` leaves figures to the reading.
+     * See `verifyPrintedRun`. On by default, and only possible when the original
+     * has a text layer.
+     */
+    printCheck?: VerifyOptions | false;
     onProgress?: ProgressCallback;
 }
 /** A word or line, placed on the page in points from the top-left. */
@@ -94,6 +105,13 @@ export interface TextDifference {
      * the match threshold (`'text'`). Always `'text'` for missing and added.
      */
     reason: 'numbers' | 'text';
+    /**
+     * The scan's ink here was matched against the original's own glyphs, and they
+     * are not the same glyphs. A difference carrying this was *seen* rather than
+     * read, so it stands on its own; one without it is a reading, and a reading
+     * disagreeing with identical ink is a misreading.
+     */
+    verified?: boolean;
     /** Where on the page, in points from the top-left. */
     x: number;
     y: number;
@@ -137,6 +155,11 @@ export interface PageOcr {
         attempted: number;
         cleared: number;
     };
+    /** Printed figures matched against the original's own glyphs, and how many read as something else. */
+    printChecks: {
+        checked: number;
+        different: number;
+    };
     warnings: string[];
 }
 export interface OcrReport {

package/dist/src/page-reading/recheck-run.use-case.d.ts

@@ -1,5 +1,6 @@
 import type { Raster } from '@scanmate/ink';
 import type { OcrEngine } from '../ocr-engine/index.js';
+import type { PrintPolarity } from '../print-verification/index.js';
 import type { MatchOptions, Reference } from './match-words.use-case.js';
 /**
  * A second look at one run the page reading got wrong, before calling it a
@@ -37,8 +38,6 @@ export interface RecheckOptions {
     agree?: number;
 }
 export declare const DEFAULT_RECHECK_PASSES: readonly RecheckPass[];
-/** Which way the original prints a run: dark text on light, or light text on a dark bar. */
-export type PrintPolarity = 'dark-on-light' | 'light-on-dark';
 export interface Recheck {
     cleared: boolean;
     /** An agreeing reading when cleared; `null` otherwise. */
@@ -47,14 +46,31 @@ export interface Recheck {
     passes: number;
     agreed: number;
 }
+/**
+ * Reads one run's crop once per pass, and says what each pass read - without
+ * judging it against anything.
+ *
+ * `recheckRun` asks "does this still say what the original prints?", which is
+ * the right question while reading a page. It is the wrong question once the
+ * pixels have disagreed with the reading, because a systematic misreading -
+ * a face, a size, a resolution the engine handles badly - misreads the
+ * *original* just as surely as the scan. Reading both sides the same way and
+ * comparing the two readings to each other cancels exactly that error, and
+ * needs the readings themselves rather than a verdict.
+ *
+ * @param engine - The engine to read with.
+ * @param image - The page to crop from, and its resolution.
+ * @param run - The run to read, placed on that page.
+ * @param options - Which passes to try; the matching rules pick the charset.
+ * @param polarity - Whether the original prints this run light on dark.
+ * @returns What each pass read, in order; empty when the run cannot be cropped.
+ */
+export declare function readRun(engine: OcrEngine, image: {
+    raster: Raster;
+    dpi: number;
+}, run: Reference, options: MatchOptions & RecheckOptions, polarity?: PrintPolarity): Promise<string[]>;
 export declare function recheckRun(engine: OcrEngine, image: {
     raster: Raster;
     dpi: number;
 }, run: Reference, options: MatchOptions & RecheckOptions, polarity?: PrintPolarity): Promise<Recheck>;
-/**
- * Which way the original prints a run, read off its own crisp rendering: the
- * glyphs are the pixels far from the background, and the background is most of
- * the box.
- */
-export declare function printPolarity(raster: Raster, dpi: number, run: Reference): PrintPolarity;
 //# sourceMappingURL=recheck-run.use-case.d.ts.map

package/dist/src/print-verification/glyph-cells.use-case.d.ts

@@ -0,0 +1,86 @@
+import type { GrayImage } from '@scanmate/ink';
+/**
+ * Where each printed character sits inside a run, found in the original's own
+ * rendering rather than guessed from font metrics.
+ *
+ * A generated PDF renders its glyphs cleanly: between two characters there is a
+ * column of paper - whatever the page puts behind the run, white or the colour
+ * of a total bar - and the only thing that varies is how wide. So the run's box
+ * is read as a column profile - how much ink stands in each column - and the
+ * groups of inked columns are the characters, in order. Nothing here needs to
+ * know the font, its advance widths, or its kerning, all of which a text layer
+ * leaves out and every face does differently.
+ *
+ * When the groups do not come to the number of characters expected - glyphs
+ * that touch, a comma that merges with the digit beside it - the run is left
+ * alone rather than guessed at: the caller can only verify what it can place.
+ * That is all-or-nothing over a whole run, which costs more the longer the run
+ * is: one pair of touching letters in a 52-character sentence loses the other
+ * fifty. `glyphWords` splits a run at its spaces first - the widest gaps in the
+ * same profile - so a sentence is verified word by word and only the word that
+ * will not segment is given up.
+ *
+ * **Direction.** A run's characters advance along the run, which is not always
+ * left to right: a form's margin instruction is often printed at a right angle
+ * to the page. The profile is taken along whichever axis the run's `angle`
+ * says, and quarter turns are the only ones handled - anything between would
+ * need the crop resampled, and is left unverifiable instead of guessed at.
+ */
+/** A rectangle in PDF points from the page's top-left corner. */
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Degrees the run is turned by, if it is; only quarter turns are handled. */
+    angle?: number;
+}
+export interface CellOptions {
+    /** The least a pixel may stand out from the run's own paper and count as print. Default `0.19`. */
+    contrast?: number;
+    /** Empty columns that still join two groups into one character. Default `0`. */
+    join?: number;
+    /** The run is printed light on a dark bar, so its paper is the dark part. */
+    lightOnDark?: boolean;
+}
+/**
+ * The box of each printed character of a run, left to right.
+ *
+ * @param page - The original page, greyscale, `0` black to `1` white.
+ * @param dpi - What that page was rendered at.
+ * @param run - The run's box, in points.
+ * @param count - How many characters the run prints, spaces excluded.
+ * @param options - Contrast against the run's paper, column joining, and polarity.
+ * @returns One box per character, or `null` when they cannot be told apart.
+ */
+export declare function glyphCells(page: GrayImage, dpi: number, run: Box, count: number, options?: CellOptions): Box[] | null;
+/**
+ * The box of each word of a run, in order, split at the run's own spaces.
+ *
+ * @param page - The original page, greyscale.
+ * @param dpi - What that page was rendered at.
+ * @param run - The run's box, in points, with its angle.
+ * @param counts - Characters in each word, in order, spaces excluded.
+ * @param options - Contrast against the run's paper, column joining, and polarity.
+ * @returns One box per word, or `null` when the words cannot be told apart.
+ */
+export declare function glyphWords(page: GrayImage, dpi: number, run: Box, counts: readonly number[], options?: CellOptions): Box[] | null;
+/**
+ * Where every character of a run sits, or `null` where it could not be placed.
+ *
+ * The whole run is tried first, which is what a figure wants: short, its glyphs
+ * separate, and nothing gained by taking it apart. When that fails the run is
+ * split at its spaces and each word placed on its own, so one pair of touching
+ * letters costs its own word rather than the sentence around it - on the W-9's
+ * certification line, two characters rather than fifty-two.
+ *
+ * @param page - The original page, greyscale.
+ * @param dpi - What that page was rendered at.
+ * @param run - The run's box, in points, with its angle.
+ * @param text - What the run prints; spaces divide the words.
+ * @param options - Contrast against the run's paper, column joining, and polarity.
+ * @returns One entry per printed character, spaces excluded, or `null` when not
+ *   even the words could be told apart.
+ */
+export declare function placeGlyphs(page: GrayImage, dpi: number, run: Box, text: string, options?: CellOptions): Array<Box | null> | null;
+//# sourceMappingURL=glyph-cells.use-case.d.ts.map

package/dist/src/print-verification/glyph-templates.use-case.d.ts

@@ -0,0 +1,40 @@
+import type { GrayImage } from '@scanmate/ink';
+import type { Box } from './glyph-cells.use-case.js';
+/**
+ * What each character looks like in print, taken from the original itself.
+ *
+ * The original is the only place a rival glyph can honestly come from: it is
+ * the document's own face, at the document's own size, rendered by whatever
+ * rendered the page. Every run whose characters can be told apart contributes
+ * its glyphs, filed by face and size, and a run is then verified against the
+ * ones that share its face and size. A run printed light on a dark bar is
+ * turned dark on light first, so a figure on a shaded total line is matched
+ * against the same digits as one on paper. Nothing is rendered, no font is embedded,
+ * and a face the page never prints has no templates - so nothing is claimed
+ * about it.
+ */
+/** A run of the original's text layer, where it sits and how it is set. */
+export interface PrintedRun extends Box {
+    text: string;
+    fontName?: string;
+    fontSize?: number;
+}
+/** Glyph images by face, size and character. */
+export type Templates = ReadonlyMap<string, GrayImage[]>;
+/** The key a run's glyphs are filed under. */
+export declare function templateKey(run: PrintedRun, character: string): string;
+/**
+ * Collects a glyph image for every character the page prints and can place.
+ *
+ * @param page - The original page, greyscale.
+ * @param dpi - What it was rendered at.
+ * @param runs - Its text layer.
+ * @returns Glyph images, by {@link templateKey}.
+ */
+export declare function collectTemplates(page: GrayImage, dpi: number, runs: readonly PrintedRun[]): Templates;
+/**
+ * The greyscale of one box of the page, or `null` when it lies outside it;
+ * inverted when the run it belongs to is printed light on dark.
+ */
+export declare function cut(page: GrayImage, dpi: number, box: Box, invert?: boolean): GrayImage | null;
+//# sourceMappingURL=glyph-templates.use-case.d.ts.map

package/dist/src/print-verification/index.d.ts

@@ -0,0 +1,10 @@
+export { glyphCells, glyphWords, placeGlyphs } from './glyph-cells.use-case.js';
+export type { Box, CellOptions } from './glyph-cells.use-case.js';
+export { collectTemplates, templateKey } from './glyph-templates.use-case.js';
+export type { PrintedRun, Templates } from './glyph-templates.use-case.js';
+export { mergeVerifiedFigures } from './merge-reading.mapper.js';
+export { printPolarity } from './print-polarity.policy.js';
+export type { PrintPolarity } from './print-polarity.policy.js';
+export { FIGURE_CHARACTERS, TEXT_CHARACTERS, verifyPrintedRun } from './verify-print.use-case.js';
+export type { PrintVerification, VerifyOptions } from './verify-print.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/print-verification/merge-reading.mapper.d.ts

@@ -0,0 +1,19 @@
+import type { PrintedRun } from './glyph-templates.use-case.js';
+import type { PrintVerification } from './verify-print.use-case.js';
+/**
+ * Puts what the ink settled into what the scan was read as.
+ *
+ * The check speaks for the figures it decided, and for nothing else. It looks at
+ * digits, cell by cell, and leaves a cell it cannot call. So its answer is merged
+ * into the reading one character at a time rather than replacing it: replacing it
+ * would erase a changed letter, or a digit too soft to judge, along with the
+ * misreadings this is here to clear - and erasing a real change is the one thing
+ * the check must never do.
+ *
+ * @param read - What the scan was read as; empty when nothing was read there.
+ * @param run - The run as the original prints it.
+ * @param verification - What `verifyPrintedRun` decided about it.
+ * @returns The reading with the decided figures settled.
+ */
+export declare function mergeVerifiedFigures(read: string, run: PrintedRun, verification: PrintVerification): string;
+//# sourceMappingURL=merge-reading.mapper.d.ts.map

package/dist/src/print-verification/print-polarity.policy.d.ts

@@ -0,0 +1,11 @@
+import type { GrayImage } from '@scanmate/ink';
+import type { Box } from './glyph-cells.use-case.js';
+/** Which way the original prints a run: dark text on light, or light text on a dark bar. */
+export type PrintPolarity = 'dark-on-light' | 'light-on-dark';
+/**
+ * Which way the original prints a run, read off its own crisp rendering: the
+ * glyphs are the pixels far from the background, and the background is most of
+ * the box.
+ */
+export declare function printPolarity(page: GrayImage, dpi: number, run: Box): PrintPolarity;
+//# sourceMappingURL=print-polarity.policy.d.ts.map

package/dist/src/print-verification/verify-print.use-case.d.ts

@@ -0,0 +1,122 @@
+import type { GrayImage } from '@scanmate/ink';
+import type { PrintedRun, Templates } from './glyph-templates.use-case.js';
+/**
+ * Whether a printed figure is still the figure that was printed, decided by
+ * matching its ink rather than by reading it.
+ *
+ * OCR asks an open question - what does this say? - and at the resolution of a
+ * returned scan it answers badly: a 0 on a shaded bar at 120 dpi comes back as
+ * a 9, and a digit written over another comes back as whatever the language
+ * model prefers. The closed question is far easier: is this still the glyph the
+ * original printed here, or does it look more like a different one?
+ *
+ * The print is crisp and the scan is not, so the print is first softened to the
+ * scan's own sharpness - the amount that makes the scan's glyphs sit best on
+ * the original's, measured on the run itself - and every glyph is compared at
+ * that sharpness. Without it a blurred 0 matches a crisp 8 as well as it
+ * matches a crisp 0.
+ *
+ * Each character of a figure is matched twice over. Once against the original's
+ * own ink at that very place - same face, same size, same position, so a scan
+ * of it correlates highly however grey or grainy it is - and once against every
+ * other character the page prints in that face and size. The printed glyph has
+ * to win by a margin to pass, and a rival has to win by a margin to count as a
+ * change; anything in between is left undecided rather than guessed at.
+ *
+ * A run whose glyphs cannot be told apart is left to the reading, and so is a
+ * run on a page that prints too few characters in that face for the rivals to
+ * be represented - a glyph whose own template is missing could otherwise be
+ * confirmed as the one it replaced, simply for lacking anything better to
+ * match.
+ *
+ * **Two scopes.** `'figures'` checks the digits of a figure against the ten
+ * digits, and nothing else: a full stop read as a comma is how a figure is
+ * written, not what it says. It is cheap enough to run over every printed run
+ * of a page, which is how a changed amount is caught even when the reading
+ * never noticed.
+ *
+ * `'text'` checks every character against letters and digits alike. The rival
+ * set is six times larger and the work grows with it, so this is not for a
+ * whole page - it is for one run somebody is already arguing about, where the
+ * reading disagrees and the ink at that run says nothing moved. There it
+ * answers the question the reading could not: are these the same glyphs?
+ *
+ * Its two answers are not worth the same. Swept over 327 runs of four real
+ * documents, `'text'` called four unchanged runs changed - a `t` read as a `k`,
+ * a `g` as a `t` - where `'figures'` has never made a false call on any scan
+ * measured here. Letters at 8 pt through a scanner are simply more confusable
+ * than digits, and the margin that separates the ten does not separate the
+ * sixty-two. So `agrees === true` is good evidence that a run is untouched, and
+ * `agrees === false` is a reason to look closer rather than a verdict; callers
+ * are expected to use it to clear a dispute, not to open one.
+ */
+/** What a figure's characters are checked against: the ten digits, and only those. */
+export declare const FIGURE_CHARACTERS = "0123456789";
+/**
+ * What a run of text is checked against, under `scope: 'text'`: letters and
+ * digits. Punctuation is left out deliberately - a comma and a full stop differ
+ * by a few pixels at these sizes, and telling them apart is neither reliable
+ * nor worth reporting.
+ */
+export declare const TEXT_CHARACTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+export interface VerifyOptions {
+    /** How far the winner must correlate ahead of the loser, `0` to `1`. Default `0.12`. */
+    minMargin?: number;
+    /** How well a rival must match before a character counts as changed. Default `0.5`. */
+    minScore?: number;
+    /** How well the printed glyph must match before the ink counts as unchanged. Default `0.7`. */
+    minPrinted?: number;
+    /** Characters the page must print in this face and size for the run to be checked. Default `8`, or `24` for text. */
+    minRivals?: number;
+    /**
+     * What to check: the digits of a figure (`'figures'`, the default, cheap
+     * enough for a whole page), or every letter and digit of the run (`'text'`,
+     * for a single run under dispute).
+     */
+    scope?: 'figures' | 'text';
+    /** How badly the printed glyph must match for a character to count as changed. Default `0.85`. */
+    maxPrinted?: number;
+    /** Digits in a row before a group is treated as a figure. Default `2`. */
+    minDigits?: number;
+    /** The characters a figure's glyphs are matched against. Default {@link FIGURE_CHARACTERS}. */
+    characters?: string;
+}
+/** One character of a figure, and how its ink matched. */
+export interface CellVerification {
+    /** Position in the run's text. */
+    at: number;
+    /** What the original prints there. */
+    printed: string;
+    /** How well the scan's ink matches the original's own ink there. */
+    printedScore: number;
+    /** The best any other character managed. */
+    rival: string;
+    rivalScore: number;
+    /** What this cell was taken to be, or `null` when it was too close to call. */
+    read: string | null;
+}
+export interface PrintVerification {
+    /** The run as its ink reads, printed characters kept where nothing was checked. */
+    reading: string;
+    /** The ink says what the original printed. */
+    agrees: boolean;
+    /** Cells decided, one way or the other. */
+    checked: number;
+    /** The smallest margin any decided cell was decided by. */
+    confidence: number;
+    /** Every character checked, with the scores behind the verdict. */
+    cells: CellVerification[];
+}
+/**
+ * Checks the figures of one run against the original's print.
+ *
+ * @param original - The original page, greyscale.
+ * @param scan - The scan, aligned onto the original's canvas, greyscale.
+ * @param dpi - What the original was rendered at.
+ * @param run - The run to check, from the original's text layer.
+ * @param templates - Glyphs collected from the original by `collectTemplates`.
+ * @param options - Margin, figure length and the characters figures use.
+ * @returns What the ink says, or `null` when the run could not be checked.
+ */
+export declare function verifyPrintedRun(original: GrayImage, scan: GrayImage, dpi: number, run: PrintedRun, templates: Templates, options?: VerifyOptions): PrintVerification | null;
+//# sourceMappingURL=verify-print.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/ocr",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "How closely a scan's text matches the original's: OCR matched run by run on the page, figures held exact, every difference located.",
   "license": "MIT",
   "author": "Eduardo Russo",
@@ -41,7 +41,7 @@
     "!**/*.js.map"
   ],
   "dependencies": {
-    "@scanmate/ink": "^0.0.2",
+    "@scanmate/ink": "^0.1.0",
     "@tesseract.js-data/eng": "^1.0.0",
     "fastest-levenshtein": "^1.0.16",
     "tesseract.js": "^7.0.0"
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@scanmate/align": "^0.0.2",
-    "@scanmate/extract": "^0.0.3"
+    "@scanmate/align": "^0.1.0",
+    "@scanmate/extract": "^0.1.0"
   }
 }