@scanmate/ocr 0.0.2 → 0.0.4

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 import { distance } from 'fastest-levenshtein';
-import { isRaster, encodeImage, resampleRaster, createRaster } from '@scanmate/ink';
+import { resizeGray, isRaster, encodeImage, resampleRaster, createRaster, toGrayscale } from '@scanmate/ink';
 import { mkdir, copyFile, stat } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
@@ -326,7 +326,12 @@ function judgeRun(expected, found, options) {
     agrees: true
   };
 }
-function judgeRuns(references, claims, options) {
+/**
+ * @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.
+ */
+function judgeRuns(references, claims, options, verified = new Set()) {
   const differences = [];
   const expectedParts = [];
   const alignedParts = [];
@@ -343,6 +348,7 @@ function judgeRuns(references, claims, options) {
       found: verdict.kind === 'missing' ? null : found,
       similarity: verdict.similarity,
       reason: verdict.reason,
+      verified: verified.has(r),
       ...box(ref)
     });
   }
@@ -356,6 +362,7 @@ function judgeRuns(references, claims, options) {
       found,
       similarity: 0,
       reason: 'text',
+      verified: false,
       ...union(group)
     });
   }
@@ -433,6 +440,670 @@ function union(texts) {
   };
 }
 
+/**
+ * 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.
+ *
+ * Measured against the run's own background rather than against white, because
+ * the paper under a run is whatever the page puts there: white, the grey of a
+ * shaded row, or the colour of a total bar.
+ */
+const CONTRAST = 0.19;
+/** Columns are grown by this, in pixels, before grouping, so a dotted stem stays one glyph. */
+const JOIN = 0;
+/**
+ * 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.
+ */
+function glyphCells(page, dpi, run, count, options = {}) {
+  const profile = profileOf(page, dpi, run, count, options);
+  if (profile === null) return null;
+  const groups = fitGroups(profile.inked, options.join ?? JOIN, count);
+  return groups === null ? null : groups.map(group => boxOf(run, profile, group));
+}
+/**
+ * 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.
+ */
+function glyphWords(page, dpi, run, counts, options = {}) {
+  const total = counts.reduce((sum, count) => sum + count, 0);
+  const profile = profileOf(page, dpi, run, total, options);
+  if (profile === null) return null;
+  if (counts.length === 1) return [{
+    ...run
+  }];
+  // The widest gaps are the spaces: as many cuts as the run has spaces.
+  const groups = groupsOf(profile.inked, options.join ?? JOIN);
+  if (groups.length < counts.length) return null;
+  const gaps = groups.slice(1).map((group, index) => ({
+    at: index + 1,
+    gap: group.start - groups[index].end
+  })).toSorted((a, b) => b.gap - a.gap).slice(0, counts.length - 1).map(gap => gap.at).toSorted((a, b) => a - b);
+  const words = [];
+  let from = 0;
+  for (const cut of [...gaps, groups.length]) {
+    const first = groups[from];
+    const last = groups[cut - 1];
+    if (first === undefined || last === undefined) return null;
+    // A word holding fewer groups than it has characters has glyphs that run
+    // together, and nothing inside it can be placed - but that is that word's
+    // problem. Its box is still returned, and it is the caller who finds the
+    // letters unplaceable, one word at a time.
+    words.push(boxOf(run, profile, {
+      start: first.start,
+      end: last.end
+    }));
+    from = cut;
+  }
+  return words;
+}
+/**
+ * How much ink stands in each step along the run, in the run's own direction.
+ *
+ * @returns The profile and the frame to read boxes back out of, or `null` when
+ *   the run is turned by something other than a quarter turn, or is too small.
+ */
+function profileOf(page, dpi, run, count, options) {
+  const {
+    contrast = CONTRAST,
+    lightOnDark = false
+  } = options;
+  if (count <= 0) return null;
+  const turn = Math.round(((run.angle ?? 0) % 360 + 360) % 360 / 90) % 4;
+  if (Math.abs(((run.angle ?? 0) % 360 + 360) % 360 - turn * 90) > 1) return null;
+  const along = turn % 2 === 0 ? 'x' : 'y';
+  // A quarter turn one way advances up the page, the other way down.
+  const reverse = turn === 2 || turn === 3;
+  const s = dpi / 72;
+  const left = Math.max(0, Math.floor(run.x * s));
+  const right = Math.min(page.width, Math.ceil((run.x + run.width) * s));
+  const top = Math.max(0, Math.floor(run.y * s));
+  const bottom = Math.min(page.height, Math.ceil((run.y + run.height) * s));
+  const steps = along === 'x' ? right - left : bottom - top;
+  const across = along === 'x' ? bottom - top : right - left;
+  if (steps < count || across < 2) return null;
+  // The paper this run is printed on: most of its box is background. How far the
+  // glyphs stand from it is the run's own contrast, and half of that separates
+  // ink from paper - on white or on the colour of a total bar alike.
+  const values = [];
+  for (let y = top; y < bottom; y++) for (let x = left; x < right; x++) values.push(page.data[y * page.width + x]);
+  const sorted = values.toSorted((a, b) => a - b);
+  const paper = sorted[Math.floor(sorted.length / 2)];
+  const darkest = sorted[Math.floor(sorted.length * (lightOnDark ? 0.98 : 0.02))];
+  const threshold = Math.max(contrast, Math.abs(darkest - paper) / 2);
+  const inked = [];
+  for (let step = 0; step < steps; step++) {
+    let dark = 0;
+    for (let other = 0; other < across; other++) {
+      const x = left + (along === 'x' ? step : other);
+      const y = top + (along === 'x' ? other : step);
+      const difference = lightOnDark ? page.data[y * page.width + x] - paper : paper - page.data[y * page.width + x];
+      if (difference > threshold) dark++;
+    }
+    inked.push(dark > 0);
+  }
+  return {
+    inked: reverse ? inked.toReversed() : inked,
+    along,
+    reverse,
+    left,
+    top,
+    right,
+    bottom,
+    s
+  };
+}
+/** A span of the profile, back in page points. */
+function boxOf(run, profile, group) {
+  const steps = profile.along === 'x' ? profile.right - profile.left : profile.bottom - profile.top;
+  const start = profile.reverse ? steps - 1 - group.end : group.start;
+  const end = profile.reverse ? steps - 1 - group.start : group.end;
+  return profile.along === 'x' ? {
+    x: (profile.left + start) / profile.s,
+    y: run.y,
+    width: (end - start + 1) / profile.s,
+    height: run.height,
+    angle: run.angle
+  } : {
+    x: run.x,
+    y: (profile.top + start) / profile.s,
+    width: run.width,
+    height: (end - start + 1) / profile.s,
+    angle: run.angle
+  };
+}
+/** The groups of inked steps, closed up until there are exactly `count` of them. */
+function fitGroups(inked, join, count) {
+  let groups = groupsOf(inked, join);
+  // Characters printed in two parts - an i, a colon, a percent sign - read as
+  // more groups than there are characters; the narrowest gaps close first.
+  while (groups.length > count) {
+    const gaps = groups.slice(1).map((group, i) => ({
+      at: i + 1,
+      gap: group.start - groups[i].end
+    }));
+    const narrowest = gaps.toSorted((a, b) => a.gap - b.gap)[0];
+    if (narrowest === undefined) break;
+    groups = [...groups.slice(0, narrowest.at - 1), {
+      start: groups[narrowest.at - 1].start,
+      end: groups[narrowest.at].end
+    }, ...groups.slice(narrowest.at + 1)];
+  }
+  return groups.length === count ? groups : null;
+}
+/** Runs of inked columns, separated by more than `join` empty ones. */
+function groupsOf(inked, join) {
+  const groups = [];
+  let start = -1;
+  let last = -1;
+  for (const [x, dark] of inked.entries()) {
+    if (!dark) continue;
+    if (start === -1) start = x;else if (x - last - 1 > join) {
+      groups.push({
+        start,
+        end: last
+      });
+      start = x;
+    }
+    last = x;
+  }
+  if (start !== -1) groups.push({
+    start,
+    end: last
+  });
+  return groups;
+}
+/**
+ * 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.
+ */
+function placeGlyphs(page, dpi, run, text, options = {}) {
+  const characters = [...text].filter(character => character.trim() !== '');
+  const whole = glyphCells(page, dpi, run, characters.length, options);
+  if (whole !== null) return whole;
+  const words = text.split(/\s+/).filter(word => word !== '');
+  if (words.length < 2) return null;
+  const boxes = glyphWords(page, dpi, run, words.map(word => [...word].length), options);
+  if (boxes === null) return null;
+  const cells = [];
+  for (const [index, word] of words.entries()) {
+    const letters = [...word].length;
+    const placed = glyphCells(page, dpi, {
+      ...boxes[index],
+      angle: run.angle
+    }, letters, options);
+    for (let letter = 0; letter < letters; letter++) cells.push(placed === null ? null : placed[letter]);
+  }
+  return cells.length === characters.length ? cells : null;
+}
+
+/**
+ * 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.
+ */
+function printPolarity(page, dpi, run) {
+  const s = dpi / 72;
+  const left = Math.max(0, Math.floor(run.x * s));
+  const top = Math.max(0, Math.floor(run.y * s));
+  const right = Math.min(page.width, Math.ceil((run.x + run.width) * s));
+  const bottom = Math.min(page.height, Math.ceil((run.y + run.height) * s));
+  const values = [];
+  for (let y = top; y < bottom; y++) for (let x = left; x < right; x++) values.push(page.data[y * page.width + x]);
+  if (values.length === 0) return 'dark-on-light';
+  const background = values.toSorted((a, b) => a - b)[Math.floor(values.length / 2)];
+  const glyphs = values.filter(v => Math.abs(v - background) > 0.19);
+  if (glyphs.length === 0) return 'dark-on-light';
+  return glyphs.reduce((a, b) => a + b, 0) / glyphs.length > background ? 'light-on-dark' : 'dark-on-light';
+}
+
+/** Most glyphs kept per character - more is slower and adds nothing. */
+const PER_CHARACTER = 4;
+/** The key a run's glyphs are filed under. */
+function templateKey(run, character) {
+  // The turn belongs in the key: a glyph printed up the margin and the same
+  // glyph printed across the page are different pictures, and matching one
+  // against the other would compare a letter with its own rotation.
+  const turn = (Math.round((run.angle ?? 0) / 90) % 4 + 4) % 4;
+  return `${run.fontName ?? ''}|${Math.round((run.fontSize ?? run.height) * 2) / 2}|${turn}|${character}`;
+}
+/**
+ * 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}.
+ */
+function collectTemplates(page, dpi, runs) {
+  const templates = new Map();
+  for (const run of runs) {
+    const characters = [...run.text].filter(character => character.trim() !== '');
+    const lightOnDark = printPolarity(page, dpi, run) === 'light-on-dark';
+    const cells = placeGlyphs(page, dpi, run, run.text, {
+      lightOnDark
+    });
+    if (cells === null) continue;
+    for (const [index, character] of characters.entries()) {
+      const cell = cells[index];
+      if (cell !== null) keep(templates, templateKey(run, character), cut(page, dpi, cell, lightOnDark));
+    }
+  }
+  return templates;
+}
+/** Files one glyph under its key, up to the few that are worth keeping. */
+function keep(templates, key, glyph) {
+  if (glyph === null) return;
+  const kept = templates.get(key) ?? [];
+  if (kept.length >= PER_CHARACTER) return;
+  kept.push(glyph);
+  templates.set(key, kept);
+}
+/**
+ * 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.
+ */
+function cut(page, dpi, box, invert = false) {
+  const s = dpi / 72;
+  const left = Math.max(0, Math.floor(box.x * s));
+  const top = Math.max(0, Math.floor(box.y * s));
+  const right = Math.min(page.width, Math.ceil((box.x + box.width) * s));
+  const bottom = Math.min(page.height, Math.ceil((box.y + box.height) * s));
+  const width = right - left;
+  const height = bottom - top;
+  if (width < 1 || height < 1) return null;
+  const data = new Float32Array(width * height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const value = page.data[(top + y) * page.width + left + x];
+    data[y * width + x] = invert ? 1 - value : value;
+  }
+  return {
+    width,
+    height,
+    data
+  };
+}
+
+/**
+ * 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.
+ */
+function mergeVerifiedFigures(read, run, verification) {
+  const decided = verification.cells.filter(cell => cell.read !== null);
+  if (decided.length === 0) return read;
+  // Nothing was read here at all, yet the ink shows the glyphs: the ink is the better witness.
+  if (read.trim() === '') return verification.reading;
+  // `at` counts the run's printed characters, spaces aside, so the reading has to
+  // line up the same way before a position in one means anything in the other.
+  const places = [...read].map((character, index) => ({
+    character,
+    index
+  })).filter(entry => entry.character.trim() !== '');
+  const changed = decided.some(cell => cell.read !== cell.printed);
+  if (places.length !== [...run.text].filter(character => character.trim() !== '').length) return changed ? verification.reading : read;
+  const merged = [...read];
+  for (const cell of decided) if (cell.read !== null) merged[places[cell.at].index] = cell.read;
+  return merged.join('');
+}
+
+/**
+ * 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. */
+const FIGURE_CHARACTERS$1 = '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.
+ */
+const TEXT_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/**
+ * How much better the winner must correlate than the runner-up for the cell to
+ * be decided either way.
+ *
+ * Measured on real returned scans, matching every printed digit of pages 1 and
+ * 2 against the ten the page prints: on a genuine scan the printed glyph wins
+ * by 0.13 or more at 125 dpi, and where a badly scanned digit loses at 90 dpi
+ * it loses by 0.03 or less. A digit replaced by another - the same ink, a few
+ * points along - was won by its rival by 0.17.
+ */
+const MIN_MARGIN = 0.12;
+/** A rival has to match this well before it can overturn what the original prints. */
+const MIN_SCORE = 0.5;
+/**
+ * ...and the printed glyph has to match at least this well before the ink can be
+ * called unchanged. A digit that genuinely changed may still beat the rivals the
+ * page happens to print, and confirming it on that basis would be the one error
+ * this check must never make.
+ */
+const MIN_PRINTED_SCORE = 0.7;
+/**
+ * Distinct characters the page must print in this face and size before a run is
+ * checked at all. Fewer than this and the character actually on the scan may
+ * have no template to win with, which turns a change into a confirmation.
+ *
+ * Eight of the ten digits for a figure. For text the alphabet is far larger and
+ * no page prints all of it, so the bar is what a page of ordinary prose prints
+ * comfortably and a lone heading in a display face does not.
+ */
+const MIN_RIVALS = 8;
+const MIN_TEXT_RIVALS = 24;
+/** ...and the printed glyph has to match no better than this: a near-perfect match is not a forgery. */
+const MAX_PRINTED_SCORE = 0.85;
+/**
+ * Each cell is matched at this height, in pixels: the shape of a digit survives,
+ * the scanner's grain does not.
+ */
+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];
+/**
+ * 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.
+ */
+function verifyPrintedRun(original, scan, dpi, run, templates, options = {}) {
+  const {
+    scope = 'figures',
+    minMargin = MIN_MARGIN,
+    minScore = MIN_SCORE,
+    maxPrinted = MAX_PRINTED_SCORE,
+    minPrinted = MIN_PRINTED_SCORE,
+    minRivals = scope === 'text' ? MIN_TEXT_RIVALS : MIN_RIVALS,
+    minDigits = 2,
+    characters = scope === 'text' ? TEXT_CHARACTERS : FIGURE_CHARACTERS$1
+  } = 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;
+  // 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;
+  // 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;
+  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;
+    scored.push({
+      at: index,
+      printed: printed[index],
+      printedScore,
+      rival: rival.character,
+      rivalScore: rival.score,
+      read: changed ? rival.character : unchanged ? printed[index] : null
+    });
+    if (!changed && !unchanged) continue;
+    checked++;
+    if (changed) reading[index] = rival.character;
+    confidence = Math.min(confidence, Math.abs(printedScore - rival.score));
+  }
+  // Nothing decided is not an answer: say nothing rather than guess a digit.
+  if (checked === 0) return null;
+  // 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 {
+    reading: text,
+    agrees: text === run.text,
+    checked,
+    confidence,
+    cells: scored
+  };
+}
+/**
+ * The digits of every figure of at least `minDigits` digits.
+ *
+ * Only digits: a full stop read as a comma is how a figure is written, not what
+ * it says, and at the size these are printed the two are a pixel apart.
+ */
+/** Every cell the character set covers: under `'text'`, the letters and digits of the run. */
+function textCells(printed, characters) {
+  const wanted = new Set();
+  for (const [index, character] of printed.entries()) if (characters.includes(character)) wanted.add(index);
+  return wanted;
+}
+function figureCells(printed, minDigits) {
+  const wanted = new Set();
+  let group = [];
+  const close = () => {
+    if (group.length >= minDigits) for (const index of group) wanted.add(index);
+    group = [];
+  };
+  for (const [index, character] of printed.entries()) {
+    if (/\d/.test(character)) group.push(index);
+    // A separator inside a figure carries on the group; anything else ends it.
+    else if (!/[.,\-/\s]/.test(character) || group.length === 0) close();
+  }
+  close();
+  return wanted;
+}
+/** How soft the print has to be drawn to sit best on the scan's own glyphs. */
+function softeningFor(pairs) {
+  let best = {
+    softening: 0,
+    score: -Infinity
+  };
+  for (const softening of SOFTENING) {
+    const score = pairs.reduce((sum, pair) => sum + correlate(pair.glyph, pair.printed, softening), 0);
+    if (score > best.score) best = {
+      softening,
+      score
+    };
+  }
+  return best.softening;
+}
+/** The best correlation between one glyph and a character's templates. */
+function bestMatch(glyph, templates, softening) {
+  let best = -1;
+  for (const template of templates) best = Math.max(best, correlate(glyph, template, softening));
+  return best;
+}
+/**
+ * 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.
+ */
+function correlate(glyph, template, softening = 0) {
+  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);
+  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;
+}
+/** A Gaussian blur of `sigma` match pixels, which is how print looks once it has been scanned. */
+function soften(image, sigma) {
+  if (sigma <= 0) return image;
+  const radius = Math.max(1, Math.ceil(sigma * 2));
+  const kernel = [];
+  for (let i = -radius; i <= radius; i++) kernel.push(Math.exp(-(i * i) / (2 * sigma * sigma)));
+  const total = kernel.reduce((a, b) => a + b, 0);
+  const weights = kernel.map(value => value / total);
+  const {
+    width,
+    height
+  } = image;
+  const horizontal = new Float32Array(width * height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    let sum = 0;
+    for (const [k, weight] of weights.entries()) {
+      const sx = Math.min(width - 1, Math.max(0, x + k - radius));
+      sum += image.data[y * width + sx] * weight;
+    }
+    horizontal[y * width + x] = sum;
+  }
+  const data = new Float32Array(width * height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    let sum = 0;
+    for (const [k, weight] of weights.entries()) {
+      const sy = Math.min(height - 1, Math.max(0, y + k - radius));
+      sum += horizontal[sy * width + x] * weight;
+    }
+    data[y * width + x] = sum;
+  }
+  return {
+    width,
+    height,
+    data
+  };
+}
+/** Pearson correlation of two images of one size, the second shifted by `dx`, `dy`. */
+function pearson(a, b, dx, dy) {
+  let count = 0;
+  let sumA = 0;
+  let sumB = 0;
+  for (let y = Math.max(0, -dy); y < Math.min(a.height, a.height - dy); y++) for (let x = Math.max(0, -dx); x < Math.min(a.width, a.width - dx); x++) {
+    sumA += a.data[y * a.width + x];
+    sumB += b.data[(y + dy) * b.width + x + dx];
+    count++;
+  }
+  if (count === 0) return 0;
+  const meanA = sumA / count;
+  const meanB = sumB / count;
+  let covariance = 0;
+  let varianceA = 0;
+  let varianceB = 0;
+  for (let y = Math.max(0, -dy); y < Math.min(a.height, a.height - dy); y++) for (let x = Math.max(0, -dx); x < Math.min(a.width, a.width - dx); x++) {
+    const da = a.data[y * a.width + x] - meanA;
+    const db = b.data[(y + dy) * b.width + x + dx] - meanB;
+    covariance += da * db;
+    varianceA += da * da;
+    varianceB += db * db;
+  }
+  const spread = Math.sqrt(varianceA * varianceB);
+  return spread === 0 ? 0 : covariance / spread;
+}
+
 const DEFAULT_TESSERACT_OPTIONS = {
   languages: ['eng'],
   model: 'best',
@@ -611,12 +1282,51 @@ const DEFAULT_RECHECK_PASSES = [{
 const FIGURE_CHARACTERS = '0123456789.,:/%()+-';
 /** White kept around a crop, in pixels: tesseract reads poorly off the edge of an image. */
 const MARGIN = 12;
-async function recheckRun(engine, image, run, options) {
+/**
+ * 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.
+ */
+async function readRun(engine, image, run, options, polarity) {
+  const {
+    passes = DEFAULT_RECHECK_PASSES
+  } = options;
+  const crop = cropRun(image.raster, image.dpi, run, polarity);
+  if (crop === null) return [];
+  const characters = FIGURE.test(run.text.trim()) ? FIGURE_CHARACTERS : undefined;
+  const readings = [];
+  for (const pass of passes) {
+    const scale = Math.max(1, pass.dpi / image.dpi);
+    const enlarged = scale === 1 ? crop : await resampleRaster(crop, Math.round(crop.width * scale), Math.round(crop.height * scale));
+    const prepared = frame(polarity === 'light-on-dark' || pass.stretch === true ? stretch(enlarged) : enlarged);
+    const read = await engine.recognise(prepared, {
+      layout: pass.layout,
+      characters
+    });
+    readings.push(read.lines.map(line => line.text).join(' ').trim());
+  }
+  return readings;
+}
+async function recheckRun(engine, image, run, options, polarity) {
   const {
     passes = DEFAULT_RECHECK_PASSES,
     agree = 2
   } = options;
-  const crop = cropRun(image.raster, image.dpi, run);
+  const crop = cropRun(image.raster, image.dpi, run, polarity);
   if (crop === null) return {
     cleared: false,
     reading: null,
@@ -632,7 +1342,8 @@ async function recheckRun(engine, image, run, options) {
     tried++;
     const scale = Math.max(1, pass.dpi / image.dpi);
     const enlarged = scale === 1 ? crop : await resampleRaster(crop, Math.round(crop.width * scale), Math.round(crop.height * scale));
-    const prepared = frame(pass.stretch === true ? stretch(enlarged) : enlarged);
+    // Inverted text keeps the bar's grey behind it; only a stretch makes that paper white.
+    const prepared = frame(polarity === 'light-on-dark' || pass.stretch === true ? stretch(enlarged) : enlarged);
     const read = await engine.recognise(prepared, {
       layout: pass.layout,
       characters
@@ -658,9 +1369,10 @@ async function recheckRun(engine, image, run, options) {
 }
 /**
  * The run's box on the image, grown by a quarter of its height (at least 2 pt)
- * so the glyphs are whole; light text on a dark bar is turned dark on light.
+ * so the glyphs are whole; light text on a dark bar is turned dark on light -
+ * as the original prints it when that is known, else when the crop is dark.
  */
-function cropRun(raster, dpi, run) {
+function cropRun(raster, dpi, run, polarity) {
   const s = dpi / 72;
   const pad = Math.max(2, run.height * 0.25);
   const left = Math.max(0, Math.floor((run.x - pad) * s));
@@ -672,7 +1384,8 @@ function cropRun(raster, dpi, run) {
   for (let y = top; y < bottom; y++) out.data.set(raster.data.subarray((y * raster.width + left) * 4, (y * raster.width + right) * 4), (y - top) * out.width * 4);
   let sum = 0;
   for (let i = 0; i < out.data.length; i += 4) sum += luminance(out.data, i);
-  if (sum / (out.width * out.height) < 110) for (let i = 0; i < out.data.length; i += 4) for (let c = 0; c < 3; c++) out.data[i + c] = 255 - out.data[i + c];
+  const invert = polarity === undefined ? sum / (out.width * out.height) < 110 : polarity === 'light-on-dark';
+  if (invert) for (let i = 0; i < out.data.length; i += 4) for (let c = 0; c < 3; c++) out.data[i + c] = 255 - out.data[i + c];
   return out;
 }
 /** Linear stretch so the darkest 2% become black and the lightest 2% white. */
@@ -771,7 +1484,8 @@ async function readPage(page, engine, options) {
     scoreMetric = 'levenshteinSimilarity',
     matchThreshold = 0.8,
     minWordConfidence = 60,
-    recheck = {}
+    recheck = {},
+    printCheck = {}
   } = options;
   const warnings = [];
   // The scan: its enhanced image as it is, or the aligned scan made fine enough to read.
@@ -824,6 +1538,7 @@ async function readPage(page, engine, options) {
   // image - belong to the original even though its text layer lacks them.
   // Writing over printed matter is for @scanmate/diff to see, not this.
   const originalDpi = page.original.dpi ?? assumeDpi;
+  const originalGray = toGrayscale(page.original.raster);
   claims.added = claims.added.map(group => group.filter(word => !printedUnder(page.original.raster, originalDpi, word))).filter(group => group.length > 0);
   const rechecks = {
     attempted: 0,
@@ -837,12 +1552,36 @@ async function readPage(page, engine, options) {
     const second = await recheckRun(engine, scanImage, run, {
       ...rules,
       ...recheck
-    });
+    }, printPolarity(originalGray, originalDpi, run));
     if (second.reading === null) continue;
     claims.found[r] = second.reading;
     rechecks.cleared++;
   }
-  const match = judgeRuns(references, claims, rules);
+  // Figures are matched against the original's own glyphs, which settles what no
+  // reading of a returned scan can: whether this is still the digit that was printed.
+  const printChecks = {
+    checked: 0,
+    different: 0
+  };
+  const seenChanged = new Set();
+  if (printCheck !== false && useLayer) {
+    const scanGray = toGrayscale(page.aligned.raster);
+    const printed = items.map(item => ({
+      ...item
+    }));
+    const templates = collectTemplates(originalGray, originalDpi, printed);
+    for (const [r, run] of printed.entries()) {
+      const verified = verifyPrintedRun(originalGray, scanGray, originalDpi, run, templates, printCheck);
+      if (verified === null) continue;
+      printChecks.checked++;
+      if (!verified.agrees) {
+        printChecks.different++;
+        seenChanged.add(r);
+      }
+      claims.found[r] = mergeVerifiedFigures(claims.found[r], run, verified);
+    }
+  }
+  const match = judgeRuns(references, claims, rules, seenChanged);
   const runs = references.map((run, r) => ({
     text: run.text,
     found: claims.found[r],
@@ -865,6 +1604,7 @@ async function readPage(page, engine, options) {
     metrics,
     differences: match.differences,
     rechecks,
+    printChecks,
     warnings
   };
 }
@@ -943,5 +1683,5 @@ function mean(values) {
   return values.length === 0 ? 0 : values.reduce((a, b) => a + b, 0) / values.length;
 }
 
-export { DEFAULT_NORMALISE, DEFAULT_RECHECK_PASSES, DEFAULT_TESSERACT_OPTIONS, claimWords, compareTexts, cosine, createTesseractEngine, diacriticsMap, dice, foldConfusables, foldDiacritics, jaccard, jaroWinkler, judgeRun, judgeRuns, levenshtein, levenshteinSimilarity, matchWords, normaliseText, ocrPages, recheckRun, tokenise, wordDistance, wordRecall };
+export { DEFAULT_NORMALISE, DEFAULT_RECHECK_PASSES, DEFAULT_TESSERACT_OPTIONS, FIGURE_CHARACTERS$1 as FIGURE_CHARACTERS, TEXT_CHARACTERS, claimWords, collectTemplates, compareTexts, cosine, createTesseractEngine, diacriticsMap, dice, foldConfusables, foldDiacritics, glyphCells, glyphWords, jaccard, jaroWinkler, judgeRun, judgeRuns, levenshtein, levenshteinSimilarity, matchWords, normaliseText, ocrPages, placeGlyphs, printPolarity, readRun, recheckRun, templateKey, tokenise, verifyPrintedRun, wordDistance, wordRecall };
 //# sourceMappingURL=index.esm.js.map