@trustchex/react-native-sdk 1.472.0 → 1.475.1

package/src/Shared/Libs/mrzFrameAggregator.ts

@@ -0,0 +1,370 @@
+import mrzUtils from './mrz.utils';
+import type { MRZValidationResult } from './mrz.utils';
+
+/**
+ * Multi-frame MRZ aggregator: per-character voting across video frames.
+ *
+ * A single OCR frame of a glossy ID card is noisy — different frames misread
+ * different characters (B↔8, S↔5, O↔0, <↔K, dropped/inserted digits). Instead of
+ * trusting one frame (or requiring N identical frames, which a single misread
+ * resets), this accumulates a per-position character vote across frames and reads
+ * out the majority consensus. Frames vote in proportion to a quality weight, so a
+ * sharper/closer frame counts more than a blurry one.
+ *
+ * This is a JS-only, ROVER-inspired post-OCR fusion (Recognizer Output Voting
+ * Error Reduction): each frame is first normalised into fixed-width MRZ lines via
+ * the existing reconstruction, lines are aligned by index and column, votes are
+ * tallied per (line, column), and the winning character per cell forms the
+ * consensus MRZ — which is then validated with check digits. Research shows
+ * post-OCR result integration beats single-frame OCR and image super-resolution
+ * for MRZ in a video stream.
+ *
+ * Why per-character voting over "N identical reads": a frame that misreads ONE
+ * character still contributes correct votes for the other 89 positions, so the
+ * consensus converges far faster and is robust to sporadic OCR errors.
+ */
+
+/** Fixed line geometry per ICAO 9303 format. */
+const FORMAT_GEOMETRY: Record<string, { lines: number; width: number }> = {
+  TD1: { lines: 3, width: 30 },
+  TD2: { lines: 2, width: 36 },
+  TD3: { lines: 2, width: 44 },
+};
+
+const MRZ_CHAR = /^[A-Z0-9<]$/;
+
+export interface MRZFrameInput {
+  /** Raw OCR text for this frame (assembled MRZ blocks, newline-separated). */
+  text: string;
+  /**
+   * Optional per-frame quality weight (higher = sharper/closer). Defaults to 1.
+   * A caller can pass e.g. a sharpness/focus estimate or the MRZ block's pixel
+   * height so crisper frames dominate the vote, per the research finding that
+   * focus-weighted voting beats unweighted.
+   */
+  weight?: number;
+}
+
+export interface MRZConsensus {
+  /** Best consensus MRZ (newline-joined fixed-width lines), or null if none yet. */
+  mrz: string | null;
+  /** Validation of the current consensus (valid only when check digits pass). */
+  validation: MRZValidationResult | null;
+  /** Number of frames that contributed a usable line-set so far. */
+  frames: number;
+  /**
+   * True when the consensus is valid AND stable — it has not changed across the
+   * last `stabilityTarget` contributing frames. Callers should advance only then.
+   */
+  stable: boolean;
+}
+
+export interface MRZFrameAggregatorOptions {
+  /**
+   * How many consecutive contributing frames the valid consensus must remain
+   * unchanged before it is considered stable. Default 2.
+   */
+  stabilityTarget?: number;
+  /** Drop the running tallies after this many frames to bound memory. Default 60. */
+  maxFrames?: number;
+}
+
+interface CellVotes {
+  // char -> accumulated weight
+  [ch: string]: number;
+}
+
+/**
+ * Reconstructs fixed-width MRZ candidate line-sets for a frame's raw OCR text.
+ * Reuses the same reconstruction the single-frame validator uses, so the
+ * aggregator sees the SAME normalised lines (filler/doc-code fixes applied),
+ * just fused across frames. Returns the best (longest, most filled) candidate.
+ */
+/** Does this exact line-set already match a known fixed-width MRZ format? */
+const exactFormatLines = (lines: string[]): string[] | null => {
+  for (const g of Object.values(FORMAT_GEOMETRY)) {
+    if (lines.length === g.lines && lines.every((l) => l.length === g.width)) {
+      return lines;
+    }
+  }
+  return null;
+};
+
+const linesForFrame = (text: string): string[] | null => {
+  // Fast path: if the raw OCR already splits into clean fixed-width MRZ lines of
+  // a known format, use them directly. Reconstruction is tuned for noisy TD1 and
+  // can mis-shape an already-clean TD2/TD3 (e.g. force a 2×44 passport into a
+  // 3×30 layout), so prefer the as-is lines when they're exact.
+  const rawLines = text
+    .split('\n')
+    .map((l) =>
+      l
+        .trim()
+        .replace(/[^A-Z0-9<]/gi, '')
+        .toUpperCase()
+    )
+    .filter(Boolean);
+  const exact = exactFormatLines(rawLines);
+  if (exact) return exact;
+
+  const candidates = mrzUtils.reconstructMRZCandidates(text);
+  if (!candidates.length) {
+    // Fall back to the lightweight fixMRZ split for already-clean text.
+    const fixed = mrzUtils
+      .fixMRZ(text)
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+    return fixed.length >= 2 ? fixed : null;
+  }
+  // Pick the best candidate and coerce it to an exact format geometry so it can
+  // be voted. A frame whose reconstruction is ALMOST a format (right line count,
+  // lines within a few chars of the width) still carries useful per-character
+  // votes — pad/truncate each line to the format width rather than discarding the
+  // whole frame. This keeps the vote accumulating every frame during continuous
+  // scanning instead of stalling on the occasional perfectly-shaped frame.
+  let best: string[] | null = null;
+  let bestScore = -1;
+  for (const cand of candidates) {
+    const geom = Object.values(FORMAT_GEOMETRY).find(
+      (g) => g.lines === cand.length
+    );
+    if (!geom) continue;
+    // Reject if any line is wildly off the expected width (likely not the band).
+    if (cand.some((l) => Math.abs(l.length - geom.width) > 6)) continue;
+    const coerced = cand.map((l) =>
+      l.length >= geom.width
+        ? l.slice(0, geom.width)
+        : l.padEnd(geom.width, '<')
+    );
+    const isExactWidth = cand.every((l) => l.length === geom.width);
+    const filled = coerced.join('').replace(/</g, '').length;
+    // Exact-shaped frames score a little higher, but near-shaped still qualify.
+    const score = (isExactWidth ? 10000 : 0) + filled;
+    if (score > bestScore) {
+      bestScore = score;
+      best = coerced;
+    }
+  }
+  return best;
+};
+
+/**
+ * Stateful aggregator. Feed it one frame's OCR text at a time via `addFrame`;
+ * after each it returns the current per-character-voted consensus and whether it
+ * is valid + stable. Reset between documents with `reset`.
+ */
+export class MRZFrameAggregator {
+  private readonly stabilityTarget: number;
+  private readonly maxFrames: number;
+  // format -> per-line, per-column vote tallies
+  private tallies: Record<string, CellVotes[][]> = {};
+  private frameCount = 0;
+  private lastConsensusMrz: string | null = null;
+  private stableStreak = 0;
+  // Consecutive frames whose identifying region disagrees with the consensus.
+  private mismatchStreak = 0;
+
+  constructor(options: MRZFrameAggregatorOptions = {}) {
+    this.stabilityTarget = Math.max(1, options.stabilityTarget ?? 2);
+    this.maxFrames = Math.max(1, options.maxFrames ?? 60);
+  }
+
+  reset(): void {
+    this.tallies = {};
+    this.frameCount = 0;
+    this.lastConsensusMrz = null;
+    this.stableStreak = 0;
+    this.mismatchStreak = 0;
+  }
+
+  /**
+   * Returns true when the incoming frame's identifying region (the line-1 data
+   * span that holds the document number) has disagreed with the current
+   * consensus for enough consecutive frames to conclude a NEW document is in
+   * view — so the caller should drop the stale votes. A few disagreeing frames
+   * are tolerated as OCR noise; a sustained disagreement is a document swap.
+   */
+  private detectDocumentChange(format: string, lines: string[]): boolean {
+    const tally = this.tallies[format];
+    if (!tally || this.frameCount < 3) {
+      this.mismatchStreak = 0;
+      return false;
+    }
+    // Compare the document-number-bearing region of line 1 (positions 5..14 in
+    // TD1; positions 0..9 in TD2/TD3) against the current per-cell winners.
+    const [start, end] = format === 'TD1' ? [5, 14] : [0, 9];
+    const consensusL1 = this.consensusLines(format)[format === 'TD1' ? 0 : 1];
+    const frameL1 = lines[format === 'TD1' ? 0 : 1] ?? '';
+    let diffs = 0;
+    let compared = 0;
+    for (let i = start; i < end; i++) {
+      const a = consensusL1[i];
+      const b = frameL1[i];
+      if (a === '<' || b === '<' || b === undefined) continue; // skip fillers/gaps
+      compared++;
+      if (a !== b) diffs++;
+    }
+    // Majority of the doc-number characters differ → this frame is a different doc.
+    const isMismatch = compared >= 4 && diffs >= Math.ceil(compared / 2);
+    this.mismatchStreak = isMismatch ? this.mismatchStreak + 1 : 0;
+    return this.mismatchStreak >= 3;
+  }
+
+  /** Frames contributed so far. */
+  get frames(): number {
+    return this.frameCount;
+  }
+
+  private ensureTally(format: string): CellVotes[][] {
+    if (!this.tallies[format]) {
+      const geom = FORMAT_GEOMETRY[format];
+      this.tallies[format] = Array.from({ length: geom.lines }, () =>
+        Array.from({ length: geom.width }, () => ({}) as CellVotes)
+      );
+    }
+    return this.tallies[format];
+  }
+
+  /**
+   * Ingest one frame and return the current consensus. The frame's lines are
+   * voted into the tally for whichever format they match; the consensus is then
+   * read out per format and validated, and the best valid (or best-effort)
+   * consensus is returned.
+   */
+  addFrame(input: MRZFrameInput): MRZConsensus {
+    const weight = input.weight && input.weight > 0 ? input.weight : 1;
+    const lines = linesForFrame(input.text);
+
+    if (lines) {
+      // Determine the format this frame's lines fit (by line count + width).
+      const format = Object.keys(FORMAT_GEOMETRY).find((f) => {
+        const g = FORMAT_GEOMETRY[f];
+        return (
+          lines.length === g.lines && lines.every((l) => l.length === g.width)
+        );
+      });
+      if (format) {
+        // Auto-reset when a DIFFERENT document is shown: if this frame's
+        // identifying region (line 1 data, where the doc number lives) disagrees
+        // strongly with the accumulated consensus for several consecutive frames,
+        // the votes are stale — clear them so the new document can converge
+        // instead of staying "stable" on the previous one.
+        if (this.detectDocumentChange(format, lines)) {
+          this.reset();
+        }
+        const tally = this.ensureTally(format);
+        for (let li = 0; li < lines.length; li++) {
+          const line = lines[li];
+          for (let ci = 0; ci < line.length; ci++) {
+            const ch = line[ci];
+            if (!MRZ_CHAR.test(ch)) continue;
+            const cell = tally[li][ci];
+            cell[ch] = (cell[ch] ?? 0) + weight;
+          }
+        }
+        this.frameCount++;
+        if (this.frameCount > this.maxFrames) this.decay();
+      }
+    }
+
+    return this.currentConsensus();
+  }
+
+  /** Halve all tallies to bound memory while preserving relative vote ratios. */
+  private decay(): void {
+    for (const format of Object.keys(this.tallies)) {
+      for (const lineCells of this.tallies[format]) {
+        for (const cell of lineCells) {
+          for (const ch of Object.keys(cell)) {
+            cell[ch] /= 2;
+          }
+        }
+      }
+    }
+    this.frameCount = Math.ceil(this.frameCount / 2);
+  }
+
+  /** Read out the winning character per cell for a format. */
+  private consensusLines(format: string): string[] {
+    const geom = FORMAT_GEOMETRY[format];
+    const tally = this.tallies[format];
+    const lines: string[] = [];
+    for (let li = 0; li < geom.lines; li++) {
+      let line = '';
+      for (let ci = 0; ci < geom.width; ci++) {
+        const cell = tally[li][ci];
+        let bestCh = '<';
+        let bestW = -1;
+        for (const ch of Object.keys(cell)) {
+          // Tie-break deterministically: higher weight wins; on a tie a non-filler
+          // beats a filler (fillers are the "no information" default), else lexical.
+          const w = cell[ch];
+          if (
+            w > bestW ||
+            (w === bestW && bestCh === '<' && ch !== '<') ||
+            (w === bestW && bestCh !== '<' && ch !== '<' && ch < bestCh)
+          ) {
+            bestW = w;
+            bestCh = ch;
+          }
+        }
+        line += bestW < 0 ? '<' : bestCh;
+      }
+      lines.push(line);
+    }
+    return lines;
+  }
+
+  /** Best consensus across all formats seen, validated with check digits. */
+  currentConsensus(): MRZConsensus {
+    const formats = Object.keys(this.tallies);
+    if (!formats.length) {
+      return {
+        mrz: null,
+        validation: null,
+        frames: this.frameCount,
+        stable: false,
+      };
+    }
+
+    let bestMrz: string | null = null;
+    let bestValidation: MRZValidationResult | null = null;
+    let bestValid = false;
+
+    for (const format of formats) {
+      const lines = this.consensusLines(format);
+      const mrz = lines.join('\n');
+      const validation = mrzUtils.validateMRZWithCorrections(mrz);
+      // Prefer a valid consensus; among valid, prefer the one the validator could
+      // fully correct (it sets correctedMrz). Among invalid, keep the first.
+      if (validation.valid && !bestValid) {
+        bestValid = true;
+        bestMrz = validation.correctedMrz ?? mrz;
+        bestValidation = validation;
+      } else if (!bestValid && bestMrz === null) {
+        bestMrz = mrz;
+        bestValidation = validation;
+      }
+    }
+
+    // Stability: the (valid) consensus must be unchanged across consecutive
+    // contributing frames. Track the streak on the corrected/consensus string.
+    const stableKey = bestValid ? bestMrz : null;
+    if (stableKey && stableKey === this.lastConsensusMrz) {
+      this.stableStreak++;
+    } else {
+      this.stableStreak = stableKey ? 1 : 0;
+    }
+    this.lastConsensusMrz = stableKey;
+
+    return {
+      mrz: bestMrz,
+      validation: bestValidation,
+      frames: this.frameCount,
+      stable: bestValid && this.stableStreak >= this.stabilityTarget,
+    };
+  }
+}
+
+export default MRZFrameAggregator;

package/src/Shared/Libs/mrzOcrIntegration.ts

@@ -0,0 +1,175 @@
+import { NativeModules } from 'react-native';
+import mrzUtils from './mrz.utils';
+import type { MRZValidationResult } from './mrz.utils';
+
+/**
+ * On-device MRZ ↔ OCR integration test harness.
+ *
+ * Runs the REAL ML Kit v2 text recognizer (via the native `MLKitModule`) on a
+ * still test image, assembles the recognized text exactly like the camera path
+ * does, feeds it through `validateMRZWithCorrections`, and reports whether the
+ * OCR-misread MRZ was corrected to a check-digit-valid result.
+ *
+ * This must run on a device/emulator (ML Kit is native) — it is not a jest test.
+ * Feed it the synthetic MRZ images under
+ * `src/Screens/Debug/__fixtures__/mrz-images/` (generated by
+ * `scripts/gen-mrz-test-images.py`), e.g. read with react-native-fs and pass the
+ * base64 to `runMrzOcrSuite`. The check-digit-driven correction in
+ * `mrz.utils.ts` is what these images exercise end-to-end against real OCR.
+ *
+ * ML Kit Text Recognition v2:
+ * https://developers.google.com/ml-kit/vision/text-recognition/v2
+ */
+
+interface NativeTextBlock {
+  text?: string;
+  boundingBox?: { left: number; top: number; right: number; bottom: number };
+}
+
+interface MLKitNativeModule {
+  recognizeText: (base64Image: string) => Promise<NativeTextBlock[]>;
+}
+
+const MLKit = (NativeModules as { MLKitModule?: MLKitNativeModule })
+  .MLKitModule;
+
+/** A single image-based test case. */
+export interface MrzOcrTestCase {
+  /** Human label, e.g. "TD1 specimen — straight-on". */
+  name: string;
+  /** Base64-encoded JPEG/PNG of the (synthetic) MRZ document. */
+  base64: string;
+  /**
+   * Optional expectations. When omitted, the test passes if the MRZ validates.
+   * Provide these for stronger assertions against the known synthetic values.
+   */
+  expect?: {
+    valid?: boolean; // default true
+    documentNumber?: string;
+    birthDate?: string;
+    expirationDate?: string;
+  };
+}
+
+export interface MrzOcrTestResult {
+  name: string;
+  passed: boolean;
+  /** Raw text ML Kit produced (joined blocks). Useful for debugging failures. */
+  rawOcr: string;
+  /** Validation result after correction. */
+  validation: MRZValidationResult;
+  /** Why it failed (empty when passed). */
+  reason?: string;
+  /** Time spent in OCR + correction, ms. */
+  durationMs: number;
+}
+
+/** Assemble the OCR blocks into newline-separated text, mirroring the camera path. */
+export const assembleOcrText = (blocks: NativeTextBlock[]): string =>
+  blocks
+    .map((b) => (b.text ?? '').trim())
+    .filter((t) => t.length > 0)
+    .join('\n');
+
+/**
+ * Runs one image through real ML Kit OCR + MRZ correction and checks expectations.
+ */
+export const runMrzOcrCase = async (
+  testCase: MrzOcrTestCase,
+  now: () => number = Date.now
+): Promise<MrzOcrTestResult> => {
+  const start = now();
+
+  if (!MLKit?.recognizeText) {
+    return {
+      name: testCase.name,
+      passed: false,
+      rawOcr: '',
+      validation: { valid: false, format: 'UNKNOWN', error: 'native module' },
+      reason:
+        'MLKitModule.recognizeText is unavailable (native module not linked)',
+      durationMs: now() - start,
+    };
+  }
+
+  let blocks: NativeTextBlock[] = [];
+  try {
+    blocks = await MLKit.recognizeText(testCase.base64);
+  } catch (err) {
+    return {
+      name: testCase.name,
+      passed: false,
+      rawOcr: '',
+      validation: { valid: false, format: 'UNKNOWN', error: 'ocr error' },
+      reason: `OCR threw: ${err instanceof Error ? err.message : String(err)}`,
+      durationMs: now() - start,
+    };
+  }
+
+  const rawOcr = assembleOcrText(blocks);
+  const validation = mrzUtils.validateMRZWithCorrections(rawOcr);
+
+  const exp = testCase.expect ?? {};
+  const wantValid = exp.valid ?? true;
+  const checks: string[] = [];
+
+  if (validation.valid !== wantValid) {
+    checks.push(`valid=${validation.valid}, expected ${wantValid}`);
+  }
+  if (wantValid && validation.valid) {
+    if (
+      exp.documentNumber &&
+      validation.fields?.documentNumber !== exp.documentNumber
+    ) {
+      checks.push(
+        `documentNumber=${validation.fields?.documentNumber}, expected ${exp.documentNumber}`
+      );
+    }
+    if (exp.birthDate && validation.fields?.birthDate !== exp.birthDate) {
+      checks.push(
+        `birthDate=${validation.fields?.birthDate}, expected ${exp.birthDate}`
+      );
+    }
+    if (
+      exp.expirationDate &&
+      validation.fields?.expirationDate !== exp.expirationDate
+    ) {
+      checks.push(
+        `expirationDate=${validation.fields?.expirationDate}, expected ${exp.expirationDate}`
+      );
+    }
+  }
+
+  return {
+    name: testCase.name,
+    passed: checks.length === 0,
+    rawOcr,
+    validation,
+    reason: checks.join('; '),
+    durationMs: now() - start,
+  };
+};
+
+export interface MrzOcrSuiteResult {
+  total: number;
+  passed: number;
+  failed: number;
+  results: MrzOcrTestResult[];
+}
+
+/** Runs every case sequentially and aggregates pass/fail. */
+export const runMrzOcrSuite = async (
+  cases: MrzOcrTestCase[]
+): Promise<MrzOcrSuiteResult> => {
+  const results: MrzOcrTestResult[] = [];
+  for (const c of cases) {
+    results.push(await runMrzOcrCase(c));
+  }
+  const passed = results.filter((r) => r.passed).length;
+  return {
+    total: results.length,
+    passed,
+    failed: results.length - passed,
+    results,
+  };
+};

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated. Do not edit manually.
 // Version is synced from package.json during build.
-export const SDK_VERSION = '1.472.0';
+export const SDK_VERSION = '1.475.1';