@scanmate/ocr 0.1.0 → 0.2.0

package/README.md

@@ -23,14 +23,15 @@ const { pages } = await extractPair({ original: 'fw9-issued.pdf', scanned: 'fw9-
 const report = await ocrPages(await alignPages(pages))
 
 // The account number above, read for what it is:
-report.pages[0].differences      // [{ kind: 'changed', expected: 'Account 4412-9087-3355',
+report.pages[0].text.differences // [{ kind: 'changed', expected: 'Account 4412-9087-3355',
                                  //    found: 'Account 4412-9987-3355', reason: 'numbers',
                                  //    verified: true, x, y, width, height }]
-report.pages[0].printChecks      // { checked, different }: figures matched against the original's glyphs
+report.pages[0].text.printChecks // { checked, different }: figures matched against the original's glyphs
 report.score                     // document score, weighted by characters
-report.pages[0].metrics          // levenshtein, jaccard, dice, cosine, CER, WER, word recall, ...
-report.pages[0].original.text    // the original's text
-report.pages[0].scanned.text     // the scan's
+report.pages[0].text.metrics     // levenshtein, jaccard, dice, cosine, CER, WER, word recall, ...
+report.pages[0].text.original.text   // the original's text
+report.pages[0].text.scanned.text    // the scan's
+report.pages[0].aligned.raster   // the page itself comes back too
 ```
 
 ## How it reads

package/dist/index.esm.js

@@ -440,6 +440,33 @@ function union(texts) {
   };
 }
 
+/**
+ * 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.
+ */
 /**
  * The least a pixel may stand out from the paper around it and still count as
  * print, `0` to `1`. The run's own contrast decides above this.
@@ -1442,7 +1469,10 @@ async function ocrPages(pages, options = {}) {
         total: pages.length
       });
       const result = await readPage(page, engine, options);
-      results.push(result);
+      results.push({
+        ...page,
+        text: result
+      });
       options.onProgress?.({
         stage: 'ocr',
         phase: 'done',
@@ -1460,10 +1490,11 @@ async function ocrPages(pages, options = {}) {
         }
       });
     }
-    const characters = results.reduce((sum, r) => sum + r.metrics.characters, 0);
+    const readings = results.map(page => page.text);
+    const characters = readings.reduce((sum, reading) => sum + reading.metrics.characters, 0);
     return {
-      score: characters === 0 ? mean(results.map(r => r.score)) : results.reduce((sum, r) => sum + r.score * r.metrics.characters, 0) / characters,
-      pageMean: mean(results.map(r => r.score)),
+      score: characters === 0 ? mean(readings.map(r => r.score)) : readings.reduce((sum, r) => sum + r.score * r.metrics.characters, 0) / characters,
+      pageMean: mean(readings.map(r => r.score)),
       pages: results,
       engine: {
         name: engine.name,

package/dist/src/index.d.ts

@@ -23,7 +23,7 @@
  * typography, line-end hyphens, diacritics, case, and OCR noise.
  */
 export { ocrPages } from './page-reading/index.js';
-export type { OcrOptions, OcrReport, PageOcr, PlacedText, PositionedText, ReadablePage, RunReading, SideText, TextDifference } from './page-reading/index.js';
+export type { OcrOptions, OcrReport, PageOcr, PlacedText, ReadPage, RunReading, SideText, TextDifference } from './page-reading/index.js';
 export { createTesseractEngine, DEFAULT_TESSERACT_OPTIONS } from './ocr-engine/index.js';
 export type { OcrEngine, OcrLine, OcrWord, RecognisedText, RecogniseHints, TesseractCacheOptions, TesseractEngine, TesseractEngineOptions, TesseractSettings } from './ocr-engine/index.js';
 export { compareTexts } from './text-similarity/index.js';
@@ -31,7 +31,7 @@ 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 { 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 type { CellOptions, 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';

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

@@ -2,7 +2,7 @@
 export { claimWords, judgeRun, judgeRuns, matchWords } from './match-words.use-case.js';
 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 type { OcrOptions, OcrReport, ReadPage, PageOcr, PlacedText, RunReading, SideText, TextDifference } from './ocr-report.contract.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/ocr-pages.use-case.d.ts

@@ -1,4 +1,5 @@
-import type { OcrOptions, OcrReport, ReadablePage } from './ocr-report.contract.js';
+import type { ReadablePage } from '@scanmate/ink';
+import type { OcrOptions, OcrReport } from './ocr-report.contract.js';
 /**
  * Read every aligned page and say how closely the scan's text matches the
  * original's - per page, and for the document.
@@ -13,5 +14,5 @@ import type { OcrOptions, OcrReport, ReadablePage } from './ocr-report.contract.
  * One engine serves the whole call. Pass `engine` to share one across calls;
  * it is then left running.
  */
-export declare function ocrPages<Page extends ReadablePage>(pages: readonly Page[], options?: OcrOptions): Promise<OcrReport>;
+export declare function ocrPages<Page extends ReadablePage>(pages: readonly Page[], options?: OcrOptions): Promise<OcrReport<Page>>;
 //# sourceMappingURL=ocr-pages.use-case.d.ts.map

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

@@ -1,21 +1,10 @@
-import type { AlignedPage, PageImage, ProgressCallback } from '@scanmate/ink';
+import type { ProgressCallback, ReadablePage } 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';
 /** A run of text placed on the page, in PDF points from the top-left - what `@scanmate/extract` calls a text item. */
-export interface PositionedText {
-    text: string;
-    x: number;
-    y: number;
-    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
  * (`@scanmate/enhance`) and the original's text layer (`@scanmate/extract`).
@@ -23,14 +12,6 @@ export interface PositionedText {
  * ignored, deliberately - hidden or stale text must not vouch for what the
  * paper shows.
  */
-export type ReadablePage = AlignedPage & {
-    enhanced?: PageImage;
-    metadata?: {
-        original?: {
-            textItems?: readonly PositionedText[] | null;
-        };
-    };
-};
 export interface OcrOptions {
     /** An engine to use and leave running. Default: a tesseract engine made for this call and terminated after it. */
     engine?: OcrEngine;
@@ -162,12 +143,23 @@ export interface PageOcr {
     };
     warnings: string[];
 }
-export interface OcrReport {
+/** A page with what the scan reads on it, beside what the original says. */
+export type ReadPage<Page extends ReadablePage = ReadablePage> = Page & {
+    text: PageOcr;
+};
+export interface OcrReport<Page extends ReadablePage = ReadablePage> {
     /** Page scores weighted by each page's expected characters - a three-word page does not outvote a dense one. */
     score: number;
     /** Unweighted mean of page scores; the two disagreeing says the short pages read differently. */
     pageMean: number;
-    pages: PageOcr[];
+    /**
+     * The pages handed in, each carrying its reading.
+     *
+     * The pages come back rather than a bare list of results, so a later stage
+     * can take these straight and whatever the producer attached is still on
+     * them. `page.text` is this page's reading.
+     */
+    pages: Array<ReadPage<Page>>;
     engine: {
         name: string;
         version: string;

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

@@ -1,40 +1,4 @@
-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;
-}
+import type { GrayImage, ScanmateOrientedRect } from '@scanmate/ink';
 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;
@@ -53,7 +17,7 @@ export interface CellOptions {
  * @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;
+export declare function glyphCells(page: GrayImage, dpi: number, run: ScanmateOrientedRect, count: number, options?: CellOptions): ScanmateOrientedRect[] | null;
 /**
  * The box of each word of a run, in order, split at the run's own spaces.
  *
@@ -64,7 +28,7 @@ export declare function glyphCells(page: GrayImage, dpi: number, run: Box, count
  * @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;
+export declare function glyphWords(page: GrayImage, dpi: number, run: ScanmateOrientedRect, counts: readonly number[], options?: CellOptions): ScanmateOrientedRect[] | null;
 /**
  * Where every character of a run sits, or `null` where it could not be placed.
  *
@@ -82,5 +46,5 @@ export declare function glyphWords(page: GrayImage, dpi: number, run: Box, count
  * @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;
+export declare function placeGlyphs(page: GrayImage, dpi: number, run: ScanmateOrientedRect, text: string, options?: CellOptions): Array<ScanmateOrientedRect | null> | null;
 //# sourceMappingURL=glyph-cells.use-case.d.ts.map

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

@@ -1,5 +1,4 @@
-import type { GrayImage } from '@scanmate/ink';
-import type { Box } from './glyph-cells.use-case.js';
+import type { GrayImage, ScanmateOrientedRect, TextRun } from '@scanmate/ink';
 /**
  * What each character looks like in print, taken from the original itself.
  *
@@ -14,15 +13,10 @@ import type { Box } from './glyph-cells.use-case.js';
  * 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;
+export declare function templateKey(run: TextRun, character: string): string;
 /**
  * Collects a glyph image for every character the page prints and can place.
  *
@@ -31,10 +25,10 @@ export declare function templateKey(run: PrintedRun, character: string): string;
  * @param runs - Its text layer.
  * @returns Glyph images, by {@link templateKey}.
  */
-export declare function collectTemplates(page: GrayImage, dpi: number, runs: readonly PrintedRun[]): Templates;
+export declare function collectTemplates(page: GrayImage, dpi: number, runs: readonly TextRun[]): 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;
+export declare function cut(page: GrayImage, dpi: number, box: ScanmateOrientedRect, invert?: boolean): GrayImage | null;
 //# sourceMappingURL=glyph-templates.use-case.d.ts.map

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

@@ -1,7 +1,7 @@
 export { glyphCells, glyphWords, placeGlyphs } from './glyph-cells.use-case.js';
-export type { Box, CellOptions } from './glyph-cells.use-case.js';
+export type { 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 type { 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';

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

@@ -1,5 +1,5 @@
-import type { PrintedRun } from './glyph-templates.use-case.js';
 import type { PrintVerification } from './verify-print.use-case.js';
+import type { TextRun } from '@scanmate/ink';
 /**
  * Puts what the ink settled into what the scan was read as.
  *
@@ -15,5 +15,5 @@ import type { PrintVerification } from './verify-print.use-case.js';
  * @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;
+export declare function mergeVerifiedFigures(read: string, run: TextRun, verification: PrintVerification): string;
 //# sourceMappingURL=merge-reading.mapper.d.ts.map

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

@@ -1,5 +1,4 @@
-import type { GrayImage } from '@scanmate/ink';
-import type { Box } from './glyph-cells.use-case.js';
+import type { GrayImage, ScanmateOrientedRect } from '@scanmate/ink';
 /** 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';
 /**
@@ -7,5 +6,5 @@ export type PrintPolarity = 'dark-on-light' | 'light-on-dark';
  * 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;
+export declare function printPolarity(page: GrayImage, dpi: number, run: ScanmateOrientedRect): PrintPolarity;
 //# sourceMappingURL=print-polarity.policy.d.ts.map

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

@@ -1,5 +1,5 @@
-import type { GrayImage } from '@scanmate/ink';
-import type { PrintedRun, Templates } from './glyph-templates.use-case.js';
+import type { GrayImage, TextRun } from '@scanmate/ink';
+import type { 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.
@@ -118,5 +118,5 @@ export interface PrintVerification {
  * @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;
+export declare function verifyPrintedRun(original: GrayImage, scan: GrayImage, dpi: number, run: TextRun, 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.1.0",
+  "version": "0.2.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.1.0",
+    "@scanmate/ink": "^0.2.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.1.0",
-    "@scanmate/extract": "^0.1.0"
+    "@scanmate/align": "^0.2.0",
+    "@scanmate/extract": "^0.2.0"
   }
 }