document-ocr 0.0.0-stage → 3.1.3

package/hosting/core/ocr_engine.py

@@ -0,0 +1,207 @@
+"""
+RapidOCR wrapper. Accepts a preprocessed image, returns detected text regions.
+
+Uses PP-OCRv5 models via ONNX Runtime — no PaddlePaddle dependency.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger("document-ocr.ocr_engine")
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TextRegion:
+    text: str
+    bbox: list[list[int]]  # [[x1,y1], [x2,y2], [x3,y3], [x4,y4]]
+    confidence: float
+
+
+class OCRModelInitError(RuntimeError):
+    """Raised when the RapidOCR models cannot be initialised.
+
+    Surfaces a clear, actionable error instead of letting the first request
+    hang until timeout when the model source (ModelScope) is unreachable or
+    the local model cache cannot be written (e.g. disk full / read-only FS).
+    """
+
+
+# ---------------------------------------------------------------------------
+# Singleton OCR instance
+# ---------------------------------------------------------------------------
+
+_lock = threading.Lock()
+_ocr_instances: dict[str, object] = {}
+
+
+# RapidOCR's default detector resize enlarges an input until its short side is
+# 736 px, which turns a thin MRZ band into a detector tensor larger than the
+# whole page. Bands still need some enlargement: on the public benchmark a
+# photographed MRZ band failed without it and at 400 px, and read correctly at
+# 480 px and above. 576 keeps a margin and is ~40% less detector work than 736.
+_BAND_DETECTOR_PARAMS = {"Det.limit_type": "min", "Det.limit_side_len": 576}
+
+
+def _get_ocr(lang: str = "en", *, band: bool = False):
+    """Get or create a cached RapidOCR instance.
+
+    ``band=True`` returns a separate instance tuned for thin, already-cropped
+    text bands (see ``_BAND_DETECTOR_PARAMS``); it shares model files, not state.
+
+    Raises:
+        OCRModelInitError: if RapidOCR model initialisation fails. A failed
+            instance is never cached, so a subsequent call can retry once the
+            underlying problem (network / disk) is resolved.
+    """
+    key = f"{lang}:band" if band else lang
+    if key in _ocr_instances:
+        return _ocr_instances[key]
+
+    try:
+        from rapidocr import LangRec, ModelType, OCRVersion, RapidOCR
+    except Exception as exc:  # pragma: no cover - import failure is environmental
+        logger.exception("Failed to import rapidocr")
+        raise OCRModelInitError(f"MODEL_INIT_FAILED: rapidocr import failed: {exc}") from exc
+
+    # Map string language codes to RapidOCR Enum values
+    _lang_map = {
+        "en": LangRec.EN,
+        "latin": LangRec.LATIN,
+        "ch": LangRec.CH,
+        "chinese_cht": LangRec.CHINESE_CHT,
+        "japan": LangRec.JAPAN,
+        "korean": LangRec.KOREAN,
+        "arabic": LangRec.ARABIC,
+        "cyrillic": LangRec.CYRILLIC,
+        "devanagari": LangRec.DEVANAGARI,
+        "ka": LangRec.KA,
+        "ta": LangRec.TA,
+        "te": LangRec.TE,
+    }
+
+    with _lock:
+        # Re-check under the lock — another thread may have built it.
+        if key in _ocr_instances:
+            return _ocr_instances[key]
+
+        rec_lang = _lang_map.get(lang, LangRec.EN)
+        try:
+            instance = RapidOCR(params={
+                "Global.use_cls": False,
+                "Det.model_type": ModelType.MOBILE,
+                "Det.ocr_version": OCRVersion.PPOCRV5,
+                "Rec.lang_type": rec_lang,
+                "Rec.model_type": ModelType.MOBILE,
+                "Rec.ocr_version": OCRVersion.PPOCRV5,
+                **(_BAND_DETECTOR_PARAMS if band else {}),
+            })
+        except Exception as exc:
+            # Do NOT cache — leave the slot empty so a later call can retry.
+            logger.exception("RapidOCR model initialisation failed (lang=%s)", key)
+            raise OCRModelInitError(
+                f"MODEL_INIT_FAILED: could not initialise OCR models for lang={key}: {exc}"
+            ) from exc
+
+        _ocr_instances[key] = instance
+
+    return _ocr_instances[key]
+
+
+# ---------------------------------------------------------------------------
+# Result parsing
+# ---------------------------------------------------------------------------
+
+def _parse_rapidocr_results(result) -> list[TextRegion]:
+    """Parse RapidOCR output into TextRegion list."""
+    regions: list[TextRegion] = []
+
+    if result.boxes is None or result.txts is None:
+        return regions
+
+    for box, txt, score in zip(result.boxes, result.txts, result.scores):
+        text = str(txt).strip()
+        if text:
+            bbox = [[int(pt[0]), int(pt[1])] for pt in box]
+            regions.append(TextRegion(text=text, bbox=bbox, confidence=float(score)))
+
+    return regions
+
+
+# ---------------------------------------------------------------------------
+# Script detection
+# ---------------------------------------------------------------------------
+
+def _is_likely_non_latin(regions: list[TextRegion]) -> bool:
+    """Heuristic: if > 40% of characters in detected text are non-ASCII, re-run
+    with multilingual model."""
+    all_text = "".join(r.text for r in regions)
+    if not all_text:
+        return False
+    non_ascii = sum(1 for c in all_text if ord(c) > 127)
+    return (non_ascii / len(all_text)) > 0.4
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def run_line_ocr(image: np.ndarray) -> list[TextRegion]:
+    """Recognize one already-localized Latin text line without running detection.
+
+    Calling the recognizer directly avoids changing the cached RapidOCR object's
+    persistent ``use_det`` flag, which would break subsequent full-page scans.
+    """
+    result = _get_ocr("en").recognize_txt([image])
+    if not result.txts or not result.scores or not result.txts[0].strip():
+        return []
+    height, width = image.shape[:2]
+    return [TextRegion(result.txts[0].strip(),
+                       [[0, 0], [width - 1, 0], [width - 1, height - 1], [0, height - 1]],
+                       float(result.scores[0]))]
+
+
+def run_band_ocr(image: np.ndarray) -> list[TextRegion]:
+    """Detect and recognize Latin text in a thin, already-cropped band.
+
+    Used for MRZ band re-reads, which the default reader enlarged to a detector
+    input several times the band's own size.
+    """
+    return _parse_rapidocr_results(_get_ocr("en", band=True)(image))
+
+
+def run_ocr(
+    image: np.ndarray,
+    *,
+    lang: Optional[str] = None,
+) -> list[TextRegion]:
+    """
+    Run OCR on a preprocessed image.
+
+    Args:
+        image: BGR numpy array (preprocessed).
+        lang: Force a language. If None, starts with 'en' and falls back to
+              'latin' if non-Latin script is detected.
+
+    Returns:
+        List of TextRegion with text, bounding box, and confidence.
+    """
+    use_lang = lang or "en"
+    ocr = _get_ocr(use_lang)
+
+    result = ocr(image)
+    regions = _parse_rapidocr_results(result)
+
+    # Auto-detect non-Latin and retry with multilingual
+    if lang is None and _is_likely_non_latin(regions):
+        return run_ocr(image, lang="latin")
+
+    return regions

package/hosting/core/page_classifier.py

@@ -0,0 +1,137 @@
+"""
+Fast passport page classification.
+
+Uses a lightweight OCR probe to distinguish passport biodata pages from
+supplementary/non-biodata pages before the heavier extraction pipeline runs.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .mrz_parser import _find_mrz_lines, parse_mrz
+from .ocr_engine import TextRegion
+
+_BIODATA_HINTS = [
+    "SURNAME",
+    "GIVEN NAME",
+    "PASSPORT NO",
+    "PASSPORT NUMBER",
+    "DATE OF BIRTH",
+    "NATIONALITY",
+    "PLACE OF BIRTH",
+    "DATE OF ISSUE",
+    "DATE OF EXPIRY",
+    "SEX",
+    "COUNTRY CODE",
+]
+
+_NON_BIODATA_HINTS = [
+    "NAME OF FATHER",
+    "LEGAL GUARDIAN",
+    "NAME OF MOTHER",
+    "NAME OF SPOUSE",
+    "ADDRESS",
+    "FILE NO",
+    "OLD PASSPORT",
+    "PLACE OF ISSUE",
+]
+
+
+@dataclass
+class PageClassification:
+    document_type: str
+    page_type: str
+    confidence: float
+    reasons: list[str] = field(default_factory=list)
+    probe_text: list[str] = field(default_factory=list)
+
+
+def classify_passport_page(regions: list[TextRegion]) -> PageClassification:
+    """Classify a page using a low-cost OCR probe."""
+    probe_text = [region.text.strip() for region in regions if region.text.strip()][:12]
+    normalised_regions = [_normalise_text(region.text) for region in regions if region.text.strip()]
+
+    has_mrz = _has_mrz_like_lines(regions)
+    biodata_matches = _count_matches(normalised_regions, _BIODATA_HINTS)
+    non_biodata_matches = _count_matches(normalised_regions, _NON_BIODATA_HINTS)
+
+    if has_mrz or biodata_matches >= 2:
+        confidence = 0.55 + (0.12 * min(biodata_matches, 3)) + (0.18 if has_mrz else 0.0)
+        reasons = ["MRZ_DETECTED"] if has_mrz else []
+        if biodata_matches:
+            reasons.append(f"BIODATA_HINTS_{biodata_matches}")
+        return PageClassification(
+            document_type="passport",
+            page_type="passport_biodata",
+            confidence=round(min(confidence, 0.99), 3),
+            reasons=reasons,
+            probe_text=probe_text,
+        )
+
+    if non_biodata_matches >= 2:
+        confidence = 0.62 + (0.1 * min(non_biodata_matches, 3))
+        return PageClassification(
+            document_type="passport",
+            page_type="passport_non_biodata",
+            confidence=round(min(confidence, 0.98), 3),
+            reasons=[f"NON_BIODATA_HINTS_{non_biodata_matches}"],
+            probe_text=probe_text,
+        )
+
+    if biodata_matches or non_biodata_matches:
+        return PageClassification(
+            document_type="passport",
+            page_type="unknown",
+            confidence=0.45,
+            reasons=["WEAK_PASSPORT_HINTS"],
+            probe_text=probe_text,
+        )
+
+    return PageClassification(
+        document_type="unknown",
+        page_type="unknown",
+        confidence=0.2,
+        reasons=["NO_PASSPORT_HINTS"],
+        probe_text=probe_text,
+    )
+
+
+def _count_matches(normalised_regions: list[str], hints: list[str]) -> int:
+    matched_hints: set[str] = set()
+    for hint in hints:
+        hint_text = _normalise_text(hint)
+        padded_hint = f" {hint_text} "
+        for region_text in normalised_regions:
+            if padded_hint in f" {region_text} ":
+                matched_hints.add(hint_text)
+                break
+    return len(matched_hints)
+
+
+def _normalise_text(text: str) -> str:
+    text = text.upper()
+    text = re.sub(r"[^A-Z0-9]+", " ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _has_mrz_like_lines(regions: list[TextRegion]) -> bool:
+    if not regions:
+        return False
+
+    page_bottom = max((max(point[1] for point in region.bbox) for region in regions if region.bbox), default=0)
+    bottom_threshold = page_bottom * 0.6
+    bottom_regions = [
+        region for region in regions
+        if region.bbox and max(point[1] for point in region.bbox) >= bottom_threshold
+    ]
+    # Optional data may occupy all of line two: it need not contain fillers.
+    # Require a paired TD3 header instead of counting arbitrary long strings.
+    if _find_mrz_lines(bottom_regions) is not None:
+        return True
+    # A passport may sit high in a larger photograph, with background text
+    # below it. Strong MRZ evidence should not depend on its position in that
+    # photograph. Keep checksum validation for this location-independent path.
+    mrz = parse_mrz(regions)
+    return bool(mrz and mrz.overall_checksum_valid)

package/hosting/core/pan_extractor.py

@@ -0,0 +1,183 @@
+"""
+Extractor for Indian PAN (Permanent Account Number) cards.
+
+PAN card fields: PAN number, holder name, father's name, date of birth.
+Layout has shifted across generations (old NSDL card, e-PAN, QR PAN), but the
+labels ("Name", "Father's Name", "Date of Birth") and the PAN format are stable,
+so extraction is label- and format-driven rather than position-driven.
+
+Robustness goals (see tests):
+  * The PAN number is recognised by *shape* (and preferably holder-type
+    validity), never confused with a date or another KYC identifier.
+  * ``name`` must never collapse into ``father_name`` — the "Name" label is a
+    substring of "Father's Name". We rely on ``find_visual_field``'s
+    exact-match priority and additionally de-duplicate the two values.
+  * Both the old NSDL "value below the label" layout and the newer e-PAN
+    "Label : value on the same row" layout are handled.
+  * Bilingual Hindi/English noise rows and missing labels are tolerated.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .ocr_engine import TextRegion
+from .validator import find_label_value, find_visual_field
+from .validators import is_valid_pan, normalize_pan
+
+# A printed PAN-card date: DD/MM/YYYY or DD-MM-YYYY (also tolerates "." and a
+# 2-digit year). The PAN itself never contains these separators, so a date can
+# never be mistaken for a PAN and vice-versa.
+_DATE_RE = re.compile(r"\b(\d{1,2}[/.\-]\d{1,2}[/.\-]\d{2,4})\b")
+
+# Label vocabularies. ``find_visual_field`` normalises OCR noise (case,
+# punctuation, "&" -> "AND") and favours exact phrase matches, so we list the
+# most specific spellings first.
+_NAME_LABELS = [
+    "NAME",
+    "NAME OF THE CARDHOLDER",
+    "CARDHOLDER NAME",
+    "CARD HOLDER NAME",
+]
+_FATHER_LABELS = [
+    "FATHER S NAME",
+    "FATHERS NAME",
+    "FATHER NAME",
+    "NAME OF FATHER",
+    "PARENT S NAME",
+    "PARENTS NAME",
+    "NAME OF PARENT",
+]
+_DOB_LABELS = [
+    "DATE OF BIRTH",
+    "DATE OF BIRTH INCORPORATION",
+    "DATE OF BIRTH OR INCORPORATION",
+    "DOB",
+]
+
+
+@dataclass
+class PanFields:
+    pan_number: Optional[str] = None
+    name: Optional[str] = None
+    father_name: Optional[str] = None
+    date_of_birth: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# PAN number
+# ---------------------------------------------------------------------------
+
+def _find_pan_number(regions: list[TextRegion]) -> Optional[str]:
+    """Locate the PAN by shape, preferring a holder-type-valid token.
+
+    Strategy, best-first:
+      1. A region adjacent to a "Permanent Account Number" / "PAN" label whose
+         text yields a *valid* PAN (correct 4th holder-type character).
+      2. Any region yielding a *valid* PAN.
+      3. Any region yielding a merely PAN-*shaped* token (tolerates OCR noise
+         in the holder-type position).
+
+    ``normalize_pan`` uses ``re.search`` over the alnum-compacted text, so dates
+    (which carry separators) and other KYC ids (e.g. a 15-char DL number) can
+    never be sliced into a false PAN.
+    """
+    labelled = find_label_value(
+        regions, ["PERMANENT ACCOUNT NUMBER", "PERMANENT ACCOUNT NUMBER CARD", "PAN"]
+    )
+    if labelled and is_valid_pan(labelled):
+        pan = normalize_pan(labelled)
+        if pan:
+            return pan
+
+    shaped_fallback: Optional[str] = None
+    for region in regions:
+        pan = normalize_pan(region.text)
+        if pan is None:
+            continue
+        if is_valid_pan(region.text):
+            return pan
+        if shaped_fallback is None:
+            shaped_fallback = pan
+    return shaped_fallback
+
+
+# ---------------------------------------------------------------------------
+# Date of birth
+# ---------------------------------------------------------------------------
+
+def _find_date(regions: list[TextRegion]) -> Optional[str]:
+    """Prefer a date adjacent to a DOB label; fall back to the first date.
+
+    DOB is left as the printed string (DD/MM/YYYY or DD-MM-YYYY) — see the
+    module/report notes: no ISO normalisation, to keep downstream values and
+    the TypeScript types unchanged.
+    """
+    labelled = find_label_value(regions, _DOB_LABELS)
+    if labelled:
+        m = _DATE_RE.search(labelled)
+        if m:
+            return m.group(1)
+
+    for region in regions:
+        m = _DATE_RE.search(region.text)
+        if m:
+            return m.group(1)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Name / father's name
+# ---------------------------------------------------------------------------
+
+def _clean_value(text: Optional[str]) -> Optional[str]:
+    """Strip leftover label punctuation/whitespace from a resolved value."""
+    if text is None:
+        return None
+    # Drop a leading "value-side" colon that occasionally rides along when the
+    # label and value were merged or mis-split by OCR (e.g. ": ROHIT SHARMA").
+    cleaned = text.strip().lstrip(":").strip()
+    return cleaned or None
+
+
+def _resolve_names(regions: list[TextRegion]) -> tuple[Optional[str], Optional[str]]:
+    """Resolve (name, father_name) ensuring ``name`` never collapses into it.
+
+    The "Name" label is a substring of "Father's Name", so a naive lookup can
+    bind ``name`` to the father's value when the dedicated "Name" label is
+    absent or mis-OCR'd. We therefore:
+      * locate the father's-name label region first and exclude it (and its
+        resolved value) when resolving the plain "Name" label, and
+      * if both labels resolve to the *same* value, treat the plain-name lookup
+        as a false positive and drop it.
+    """
+    father_value = _clean_value(find_label_value(regions, _FATHER_LABELS))
+
+    name_value = _clean_value(find_label_value(regions, _NAME_LABELS))
+
+    # Guard against the substring collapse: if the "Name" lookup latched onto
+    # the father's-name label/value, discard it rather than duplicate.
+    if name_value is not None and name_value == father_value:
+        # Make sure we did not simply read the same label region. Re-resolve the
+        # plain-name label and confirm it is a distinct region from the father
+        # label before trusting the duplicate; otherwise drop the name.
+        name_label = find_visual_field(regions, _NAME_LABELS)
+        father_label = find_visual_field(regions, _FATHER_LABELS)
+        if name_label is None or name_label is father_label:
+            name_value = None
+
+    return name_value, father_value
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def extract_pan(regions: list[TextRegion]) -> PanFields:
+    fields = PanFields()
+    fields.pan_number = _find_pan_number(regions)
+    fields.name, fields.father_name = _resolve_names(regions)
+    fields.date_of_birth = _find_date(regions)
+    return fields