@scanmate/ocr 0.4.0 → 0.5.0

package/README.md

@@ -26,7 +26,7 @@ const report = await ocrPages(await alignPages(pages))
 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].text.printChecks // { checked, different }: figures matched against the original's glyphs
+report.pages[0].text.printChecks // { checked, different, skipped }: figures matched against the original's glyphs
 report.score                     // document score, weighted by characters
 report.pages[0].text.metrics     // levenshtein, jaccard, dice, cosine, CER, WER, word recall, ...
 report.pages[0].text.original.text   // the original's text
@@ -41,6 +41,7 @@ report.pages[0].aligned.raster   // the page itself comes back too
 - **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).
 - **Figures are matched, not only read.** Every printed figure is checked glyph by glyph against the original's own ink and against the other digits the page prints, at the scan's own sharpness. That settles what no reading of a coarse scan can: whether this is still the digit that was printed. On real returned scans it verified 35 of 40 printed figures at 125 dpi with no false calls, and read a digit replaced by another of the same run for what it is.
+- **It says why it abstained.** `printChecks.skipped` counts each reason - `no-figure`, `unplaceable`, `few-rivals`, `too-coarse`, `undecided` - because "checked and agreed" and "never looked at" are otherwise the same silence, and telling them apart by inference is slow and can come out wrong.
 - **It abstains rather than confirm.** A page that prints too few digits to offer a full set of rivals, a run too small to segment, a cell too soft to call: each is left to the reading, and the answer is applied only to the cells it actually decided. Confirming a digit that had in fact been altered would be worse than saying nothing, so every threshold is set to fail that way.
 - **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.
 

package/dist/index.esm.js

@@ -923,8 +923,38 @@ const MAX_PRINTED_SCORE = 0.85;
 const MATCH_HEIGHT = 16;
 /** The template is slid this far, in match pixels, to absorb a cell landing half a pixel out. */
 const SHIFT = 1;
-/** How much the print may be softened by to meet the scan, in match pixels. */
-const SOFTENING = [0, 0.5, 1, 1.5, 2];
+/**
+ * The scan is sharpened to meet the print, rather than the print softened to
+ * meet the scan, and that direction is the whole of it.
+ *
+ * Softening the template was the obvious way round and it is wrong: the blur
+ * lands on the printed glyph and on all nine rivals alike, so above about one
+ * match pixel a `3` and an `8` become the same blob and every rival ties the
+ * truth. Measured on a returned order confirmation, the totals on its shaded
+ * bar fitted a softening of 1.5 and scored 0.937 against the digit actually
+ * printed and 0.928 against the best rival - a margin of 0.006 where 0.12 is
+ * needed, so not one of 109 cells could be decided. The same collapse hits
+ * ordinary black-on-white text on a 93 dpi scan, which is how we know it is
+ * the softening and not the shaded bar.
+ *
+ * Sharpening the scan puts back what the scanner took out and leaves the
+ * template's own detail intact, so what survives is what distinguishes one
+ * digit from another. On the same document that took light-on-dark cells from
+ * 0 decided to 12, and dark-on-light from 316 to 343, with no false call.
+ *
+ * `RECOVERY` is how far, in match pixels; `SHARPENING` is how hard.
+ */
+const RECOVERY = [0, 0.5, 1, 1.5, 2];
+/**
+ * A verdict has to hold at every one of these, or the cell is left undecided.
+ *
+ * Not a search for the amount that gives an answer - that is how a sweep turns
+ * into a way of manufacturing one. Sharpening can create a stroke that was
+ * never scanned, and a fabricated stroke favours whichever rival it happens to
+ * resemble, so a reading that moves as the amount moves is an artefact of the
+ * sharpening and is discarded.
+ */
+const SHARPENING = [1, 1.5, 2];
 /**
  * Checks the figures of one run against the original's print.
  *
@@ -934,7 +964,7 @@ const SOFTENING = [0, 0.5, 1, 1.5, 2];
  * @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.
+ * @returns What the ink says, or why it would not say.
  */
 function verifyPrintedRun(original, scan, dpi, run, templates, options = {}) {
   const {
@@ -949,69 +979,99 @@ function verifyPrintedRun(original, scan, dpi, run, templates, options = {}) {
   } = options;
   const printed = [...run.text].filter(character => character.trim() !== '');
   const wanted = scope === 'text' ? textCells(printed, characters) : figureCells(printed, minDigits);
-  if (wanted.size === 0) return null;
+  if (wanted.size === 0) return {
+    verified: false,
+    because: 'no-figure'
+  };
   // A total on a shaded bar is printed light on dark; turned round, it is a figure like any other.
   const lightOnDark = printPolarity(original, dpi, run) === 'light-on-dark';
   const cells = placeGlyphs(original, dpi, run, run.text, {
     lightOnDark
   });
-  if (cells === null) return null;
+  if (cells === null) return {
+    verified: false,
+    because: 'unplaceable'
+  };
   // Rivals: every character the page prints in this face and size that a figure could use.
   const rivals = [...characters].filter(character => templates.has(templateKey(run, character)));
-  if (rivals.length < minRivals) return null;
-  // How soft this scan's print is, measured where the answer is known: each cell
-  // against the very glyph the original prints there.
-  const pairs = [...wanted].flatMap(index => {
-    const cell = cells[index];
-    return cell === null ? [] : [{
-      glyph: cut(scan, dpi, cell, lightOnDark),
-      printed: cut(original, dpi, cell, lightOnDark)
-    }];
-  }).filter(pair => pair.glyph !== null && pair.printed !== null);
-  const softening = softeningFor(pairs);
-  const reading = [...printed];
-  const scored = [];
-  let confidence = 1;
-  let checked = 0;
+  if (rivals.length < minRivals) return {
+    verified: false,
+    because: 'few-rivals'
+  };
+  // The cell exactly: a margin would bring in the neighbouring glyphs, which
+  // both crops share, and shared ink correlates whatever the character is.
+  const crops = new Map();
+  let coarse = false;
   for (const index of wanted) {
-    // The cell exactly: a margin would bring in the neighbouring glyphs, which
-    // both crops share, and shared ink correlates whatever the character is.
     const cell = cells[index];
     if (cell === null) continue;
     const glyph = cut(scan, dpi, cell, lightOnDark);
     // The original's own ink here: the same glyph, at the same size, in the same place.
     const asPrinted = cut(original, dpi, cell, lightOnDark);
     if (glyph === null || asPrinted === null) continue;
-    const printedScore = correlate(glyph, asPrinted, softening);
-    const others = rivals.filter(character => character !== printed[index]).map(character => ({
-      character,
-      score: bestMatch(glyph, templates.get(templateKey(run, character)) ?? [], softening)
-    })).toSorted((a, b) => b.score - a.score);
-    const rival = others[0];
-    if (rival === undefined) continue;
-    // Undecided unless one of the two wins clearly, and a change has to look like
-    // the character it is being read as, not merely less like the printed one.
-    const changed = rival.score >= printedScore + minMargin && rival.score >= minScore && printedScore <= maxPrinted;
-    const unchanged = printedScore >= rival.score + minMargin && printedScore >= minPrinted;
+    // Never invent resolution. Matching happens at MATCH_HEIGHT, so a shorter
+    // cell is scaled up and the detail that decides between two digits is
+    // interpolated rather than scanned - and an invented stroke favours
+    // whichever rival it resembles. The one false call this check produced on
+    // a 93 dpi scan came from cells of fourteen pixels.
+    if (glyph.height < MATCH_HEIGHT) {
+      coarse = true;
+      continue;
+    }
+    crops.set(index, {
+      glyph,
+      printed: asPrinted
+    });
+  }
+  if (crops.size === 0) return {
+    verified: false,
+    because: coarse ? 'too-coarse' : 'unplaceable'
+  };
+  // How far this scan's print has to be sharpened, measured where the answer is
+  // known: each cell against the very glyph the original prints there.
+  const pairs = [...crops.values()];
+  const recoveries = SHARPENING.map(amount => recoveryFor(pairs, amount));
+  const limits = {
+    minMargin,
+    minScore,
+    maxPrinted,
+    minPrinted
+  };
+  const reading = [...printed];
+  const scored = [];
+  let confidence = 1;
+  let checked = 0;
+  for (const [index, crop] of crops) {
+    const passes = recoveries.map(recovery => judgeCell(crop, printed[index], rivals, run, templates, recovery, limits));
+    const first = passes[0];
+    if (first === undefined) continue;
+    // Undecided unless every pass reads it the same way: a verdict that changes
+    // as the sharpening changes is the sharpening talking, not the ink.
+    const settled = first.read !== null && passes.every(pass => pass.read === first.read);
     scored.push({
       at: index,
       printed: printed[index],
-      printedScore,
-      rival: rival.character,
-      rivalScore: rival.score,
-      read: changed ? rival.character : unchanged ? printed[index] : null
+      printedScore: first.printedScore,
+      rival: first.rival,
+      rivalScore: first.rivalScore,
+      read: settled ? first.read : null
     });
-    if (!changed && !unchanged) continue;
+    if (!settled || first.read === null) continue;
     checked++;
-    if (changed) reading[index] = rival.character;
-    confidence = Math.min(confidence, Math.abs(printedScore - rival.score));
+    reading[index] = first.read;
+    // The narrowest margin any pass decided by, so confidence is the weakest link.
+    confidence = Math.min(confidence, ...passes.map(pass => Math.abs(pass.printedScore - pass.rivalScore)));
   }
   // Nothing decided is not an answer: say nothing rather than guess a digit.
-  if (checked === 0) return null;
+  if (checked === 0) return {
+    verified: false,
+    because: 'undecided'
+  };
   // Put the spaces back, so the reading reads like the run it is about.
   let cell = 0;
   const text = [...run.text].map(character => character.trim() === '' ? character : reading[cell++]).join('');
   return {
+    verified: true,
     reading: text,
     agrees: text === run.text,
     checked,
@@ -1019,6 +1079,31 @@ function verifyPrintedRun(original, scan, dpi, run, templates, options = {}) {
     cells: scored
   };
 }
+/** What one pass of the sharpening sweep makes of a single cell. */
+function judgeCell(crop, printed, rivals, run, templates, recovery, limits) {
+  const printedScore = correlate(crop.glyph, crop.printed, recovery);
+  const others = rivals.filter(character => character !== printed).map(character => ({
+    character,
+    score: bestMatch(crop.glyph, templates.get(templateKey(run, character)) ?? [], recovery)
+  })).toSorted((a, b) => b.score - a.score);
+  const rival = others[0];
+  if (rival === undefined) return {
+    read: null,
+    printedScore,
+    rival: '',
+    rivalScore: -1
+  };
+  // A change has to look like the character it is being read as, not merely
+  // less like the printed one.
+  const changed = rival.score >= printedScore + limits.minMargin && rival.score >= limits.minScore && printedScore <= limits.maxPrinted;
+  const unchanged = printedScore >= rival.score + limits.minMargin && printedScore >= limits.minPrinted;
+  return {
+    read: changed ? rival.character : unchanged ? printed : null,
+    printedScore,
+    rival: rival.character,
+    rivalScore: rival.score
+  };
+}
 /**
  * The digits of every figure of at least `minDigits` digits.
  *
@@ -1047,38 +1132,62 @@ function figureCells(printed, minDigits) {
   return wanted;
 }
 /** How soft the print has to be drawn to sit best on the scan's own glyphs. */
-function softeningFor(pairs) {
+function recoveryFor(pairs, amount) {
   let best = {
-    softening: 0,
+    recovery: {
+      sigma: 0,
+      amount
+    },
     score: -Infinity
   };
-  for (const softening of SOFTENING) {
-    const score = pairs.reduce((sum, pair) => sum + correlate(pair.glyph, pair.printed, softening), 0);
+  for (const sigma of RECOVERY) {
+    const recovery = {
+      sigma,
+      amount
+    };
+    const score = pairs.reduce((sum, pair) => sum + correlate(pair.glyph, pair.printed, recovery), 0);
     if (score > best.score) best = {
-      softening,
+      recovery,
       score
     };
   }
-  return best.softening;
+  return best.recovery;
 }
 /** The best correlation between one glyph and a character's templates. */
-function bestMatch(glyph, templates, softening) {
+function bestMatch(glyph, templates, recovery) {
   let best = -1;
-  for (const template of templates) best = Math.max(best, correlate(glyph, template, softening));
+  for (const template of templates) best = Math.max(best, correlate(glyph, template, recovery));
   return best;
 }
+/** An unsharp mask: what the scanner blurred away, added back. */
+function sharpen(image, {
+  sigma,
+  amount
+}) {
+  if (sigma <= 0 || amount <= 0) return image;
+  const blurred = soften(image, sigma);
+  const data = new Float32Array(image.data.length);
+  for (let i = 0; i < data.length; i++) data[i] = image.data[i] + amount * (image.data[i] - blurred.data[i]);
+  return {
+    width: image.width,
+    height: image.height,
+    data
+  };
+}
 /**
  * How alike two glyphs are, each scaled to the same small box, and the template
  * slid a pixel each way to allow for a cell that landed a fraction out.
  *
  * Correlation, rather than a difference of pixels, because a scan is darker or
- * lighter than the print it came from and that must not decide anything.
+ * lighter than the print it came from and that must not decide anything. The
+ * scan's glyph is sharpened; the template is left as it was printed. See
+ * {@link RECOVERY} for why that direction and not the other.
  */
-function correlate(glyph, template, softening = 0) {
+function correlate(glyph, template, recovery) {
   const height = MATCH_HEIGHT;
   const width = Math.max(2, Math.round(height * ((glyph.width / glyph.height + template.width / template.height) / 2)));
-  const a = resizeGray(glyph, width, height);
-  const b = soften(resizeGray(template, width, height), softening);
+  const a = sharpen(resizeGray(glyph, width, height), recovery);
+  const b = resizeGray(template, width, height);
   let best = -1;
   for (let dy = -SHIFT; dy <= SHIFT; dy++) for (let dx = -SHIFT; dx <= SHIFT; dx++) best = Math.max(best, pearson(a, b, dx, dy));
   return best;
@@ -1625,7 +1734,14 @@ async function readPage(page, engine, options, templates) {
   // reading of a returned scan can: whether this is still the digit that was printed.
   const printChecks = {
     checked: 0,
-    different: 0
+    different: 0,
+    skipped: {
+      'no-figure': 0,
+      'unplaceable': 0,
+      'few-rivals': 0,
+      'too-coarse': 0,
+      'undecided': 0
+    }
   };
   const seenChanged = new Set();
   if (printCheck !== false && useLayer) {
@@ -1635,7 +1751,10 @@ async function readPage(page, engine, options, templates) {
     }));
     for (const [r, run] of printed.entries()) {
       const verified = verifyPrintedRun(originalGray, scanGray, originalDpi, run, templates, printCheck);
-      if (verified === null) continue;
+      if (!verified.verified) {
+        printChecks.skipped[verified.because]++;
+        continue;
+      }
       printChecks.checked++;
       if (!verified.agrees) {
         printChecks.different++;

package/dist/src/index.d.ts

@@ -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 { collectInto, collectTemplates, FIGURE_CHARACTERS, glyphCells, glyphWords, placeGlyphs, printPolarity, templateKey, TEXT_CHARACTERS, verifyPrintedRun } from './print-verification/index.js';
-export type { CellOptions, PrintPolarity, PrintVerification, TemplateStore, Templates, VerifyOptions } from './print-verification/index.js';
+export type { CellOptions, PrintAbstention, PrintCheck, PrintPolarity, PrintVerification, TemplateStore, 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/ocr-report.contract.d.ts

@@ -1,6 +1,6 @@
 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 { PrintAbstention, 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';
@@ -136,10 +136,16 @@ export interface PageOcr {
         attempted: number;
         cleared: number;
     };
-    /** Printed figures matched against the original's own glyphs, and how many read as something else. */
+    /**
+     * Printed figures matched against the original's own glyphs: how many were
+     * decided, how many read as something else, and why the rest were not looked
+     * at. Without `skipped`, "checked and agreed" and "never checked" are the
+     * same silence from outside.
+     */
     printChecks: {
         checked: number;
         different: number;
+        skipped: Record<PrintAbstention, number>;
     };
     warnings: string[];
 }

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

@@ -6,5 +6,6 @@ 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 { PrintAbstention, PrintCheck } 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/verify-print.use-case.d.ts

@@ -95,6 +95,29 @@ export interface CellVerification {
     /** What this cell was taken to be, or `null` when it was too close to call. */
     read: string | null;
 }
+/**
+ * Why a run was not checked.
+ *
+ * Reported rather than folded into a bare `null`, because "checked and agreed"
+ * and "never looked at" are the same silence from outside, and telling them
+ * apart by inference costs a consumer days and can still come out wrong.
+ *
+ * - `no-figure` - the run holds no group of digits long enough to be a figure.
+ * - `unplaceable` - the glyphs could not be cut apart.
+ * - `few-rivals` - the document prints too little of this face to rule other
+ *   characters out.
+ * - `too-coarse` - the scan resolves the cell below the height it is matched
+ *   at, so a verdict would rest on detail it never captured.
+ * - `undecided` - measured, and nothing won by enough to say.
+ */
+export type PrintAbstention = 'no-figure' | 'unplaceable' | 'few-rivals' | 'too-coarse' | 'undecided';
+/** What the ink said, or why it would not say. */
+export type PrintCheck = ({
+    verified: true;
+} & PrintVerification) | {
+    verified: false;
+    because: PrintAbstention;
+};
 export interface PrintVerification {
     /** The run as its ink reads, printed characters kept where nothing was checked. */
     reading: string;
@@ -116,7 +139,7 @@ export interface PrintVerification {
  * @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.
+ * @returns What the ink says, or why it would not say.
  */
-export declare function verifyPrintedRun(original: GrayImage, scan: GrayImage, dpi: number, run: TextRun, templates: Templates, options?: VerifyOptions): PrintVerification | null;
+export declare function verifyPrintedRun(original: GrayImage, scan: GrayImage, dpi: number, run: TextRun, templates: Templates, options?: VerifyOptions): PrintCheck;
 //# sourceMappingURL=verify-print.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/ocr",
-  "version": "0.4.0",
+  "version": "0.5.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.4.0",
+    "@scanmate/ink": "^0.5.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.4.0",
-    "@scanmate/extract": "^0.4.0"
+    "@scanmate/align": "^0.5.0",
+    "@scanmate/extract": "^0.5.0"
   }
 }