document-ocr 0.0.0-stage → 3.1.3

package/python/core/mrz_parser.py

@@ -0,0 +1,336 @@
+"""
+MRZ (Machine Readable Zone) parser for TD3 passports (ICAO Doc 9303).
+
+Parses the two 44-character MRZ lines, extracts fields by position,
+and validates ICAO check digits.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Optional
+
+from .ocr_engine import TextRegion
+
+
+# ---------------------------------------------------------------------------
+# ICAO check digit
+# ---------------------------------------------------------------------------
+
+_WEIGHTS = [7, 3, 1]
+
+_CHAR_VALUES = {str(i): i for i in range(10)}
+_CHAR_VALUES.update({chr(c): c - 55 for c in range(65, 91)})  # A=10 .. Z=35
+_CHAR_VALUES["<"] = 0
+
+_DIGIT_CORRECTIONS = str.maketrans({
+    "O": "0", "o": "0",
+    "D": "0", "d": "0",
+    "Q": "0", "q": "0",
+    "I": "1", "i": "1",
+    "l": "1", "L": "1",
+    "Z": "2", "z": "2",
+    "A": "4", "a": "4",
+    "S": "5", "s": "5",
+    "G": "6", "g": "6",
+    "B": "8", "b": "8",
+})
+
+
+def _apply_digit_corrections(line2: str) -> str:
+    """Apply digit corrections to known digit-only positions in MRZ line 2.
+    Positions: [9] pn check, [13:19] DOB, [19] DOB check, [21:27] expiry,
+    [27] expiry check, [42] personal check, [43] overall check.
+    Does NOT touch [0:9] passport number, [10:13] nationality, [20] sex, [28:42] personal number."""
+    chars = list(line2)
+    digit_positions = [9, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 24, 25, 26, 27, 42, 43]
+    for pos in digit_positions:
+        if pos < len(chars):
+            chars[pos] = chars[pos].translate(_DIGIT_CORRECTIONS)
+    return "".join(chars)
+
+
+def icao_check_digit(data: str) -> int:
+    """Compute ICAO weighted checksum for a string of MRZ characters."""
+    total = 0
+    for i, ch in enumerate(data):
+        try:
+            val = _CHAR_VALUES[ch.upper()]
+        except KeyError:
+            raise ValueError(f"Invalid MRZ character: {ch!r}") from None
+        total += val * _WEIGHTS[i % 3]
+    return total % 10
+
+
+def verify_check_digit(data: str, expected: str) -> bool:
+    """Verify a single check digit field."""
+    if len(expected) != 1 or expected not in "0123456789":
+        return False
+    try:
+        return icao_check_digit(data) == int(expected)
+    except ValueError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Date parsing
+# ---------------------------------------------------------------------------
+
+def _parse_mrz_date(
+    yymmdd: str,
+    *,
+    is_expiry: bool = False,
+    reference_date: Optional[date] = None,
+) -> Optional[str]:
+    """Resolve an MRZ's two-digit year and validate the calendar date.
+
+    Birth dates use the most recent occurrence not after the reference date.
+    Expiry dates use the nearest century, supporting both expired documents and
+    future expiries. The MRZ alone cannot disambiguate dates a century apart.
+    """
+    if not re.fullmatch(r"[0-9]{6}", yymmdd):
+        return None
+    reference_date = reference_date or date.today()
+    yy, mm, dd = int(yymmdd[:2]), int(yymmdd[2:4]), int(yymmdd[4:6])
+    year = (reference_date.year // 100) * 100 + yy
+    if is_expiry:
+        if year - reference_date.year > 50:
+            year -= 100
+        elif reference_date.year - year > 50:
+            year += 100
+    elif (year, mm, dd) > (reference_date.year, reference_date.month, reference_date.day):
+        year -= 100
+    try:
+        return date(year, mm, dd).isoformat()
+    except ValueError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Result types
+# ---------------------------------------------------------------------------
+
+@dataclass
+class MRZField:
+    value: Optional[str]
+    raw: str
+    checksum_valid: Optional[bool] = None  # None if no checksum for this field
+
+
+@dataclass
+class MRZResult:
+    """Parsed MRZ result with all fields and validation info."""
+    document_type: MRZField
+    country_code: MRZField
+    surname: MRZField
+    given_names: MRZField
+    passport_number: MRZField
+    nationality: MRZField
+    date_of_birth: MRZField
+    sex: MRZField
+    expiry_date: MRZField
+    personal_number: MRZField
+    overall_checksum_valid: bool
+    raw_lines: tuple[str, str]
+    errors: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# MRZ line detection
+# ---------------------------------------------------------------------------
+
+_MRZ_PATTERN = re.compile(r"^[A-Z0-9<]{40,44}$")
+_MRZ_LINE1_PATTERN = re.compile(r"P[A-Z<][A-Z<]{3}[A-Z<]{35,39}")
+
+
+def _clean_mrz_text(raw: str) -> str:
+    """Clean OCR text for MRZ matching — fix common substitution errors."""
+    # Recognizers can emit compatibility glyphs such as Roman numeral I or
+    # full-width Latin letters. Unicode defines their ASCII equivalents;
+    # unlike guessing a country or name, this does not substitute characters
+    # based on the expected document content.
+    text = re.sub(r"\s+", "", unicodedata.normalize("NFKC", raw).upper())
+    # Common OCR substitutions for the '<' filler character
+    text = text.replace("«", "<").replace("‹", "<").replace(">", "<")
+    return text
+
+
+def _find_mrz_lines(regions: list[TextRegion]) -> Optional[tuple[str, str]]:
+    """Identify the two MRZ lines from OCR output."""
+    mrz_regions: list[tuple[int, str]] = []
+    for region in regions:
+        text = _clean_mrz_text(region.text)
+        if _MRZ_PATTERN.fullmatch(text):
+            y_pos = max(p[1] for p in region.bbox) if region.bbox else 0
+            mrz_regions.append((y_pos, text))
+
+    mrz_regions.sort(key=lambda x: x[0])
+    # Anchor the pair to a TD3 passport header. A footer or OCR duplicate below
+    # the MRZ must not displace the actual first line.
+    for index in range(len(mrz_regions) - 2, -1, -1):
+        line1 = mrz_regions[index][1]
+        line2 = mrz_regions[index + 1][1]
+        if _MRZ_LINE1_PATTERN.fullmatch(line1) and not _MRZ_LINE1_PATTERN.fullmatch(line2):
+            return (_pad_to_44(line1), _pad_to_44(line2))
+    # Re-read text can be mapped back to a sideways document in the source
+    # photograph. Use the header's local axes instead of global page Y there.
+    for header in regions:
+        first = _clean_mrz_text(header.text)
+        if not _MRZ_LINE1_PATTERN.fullmatch(first) or len(header.bbox) != 4:
+            continue
+        tl, tr, br, bl = header.bbox
+        ux, uy = tr[0] - tl[0], tr[1] - tl[1]
+        vx, vy = bl[0] - tl[0], bl[1] - tl[1]
+        width, height = (ux * ux + uy * uy) ** .5, (vx * vx + vy * vy) ** .5
+        if width < 100 or height < 5 or abs(uy) <= abs(ux):
+            continue
+        cx, cy = sum(p[0] for p in header.bbox) / 4, sum(p[1] for p in header.bbox) / 4
+        for row in regions:
+            second = _clean_mrz_text(row.text)
+            if row is header or not _MRZ_PATTERN.fullmatch(second) or _MRZ_LINE1_PATTERN.fullmatch(second) or len(row.bbox) != 4:
+                continue
+            dx, dy = sum(p[0] for p in row.bbox) / 4 - cx, sum(p[1] for p in row.bbox) / 4 - cy
+            across, below = abs((dx * ux + dy * uy) / width), (dx * vx + dy * vy) / height
+            if across < width * .15 and height * .5 < below < height * 4:
+                return (_pad_to_44(first), _pad_to_44(second))
+    return None
+
+
+def _pad_to_44(line: str) -> str:
+    """Pad MRZ line to 44 characters with '<' if shorter."""
+    return line.ljust(44, "<")[:44]
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+def _clean_name(raw: str) -> str:
+    """Replace MRZ filler '<' with spaces and clean up."""
+    return raw.replace("<", " ").strip()
+
+
+def parse_mrz(regions: list[TextRegion]) -> Optional[MRZResult]:
+    """
+    Parse MRZ from OCR text regions.
+
+    Returns None if MRZ lines cannot be identified.
+    """
+    lines = _find_mrz_lines(regions)
+    if lines is None:
+        return None
+
+    line1, line2 = lines
+    line2 = _apply_digit_corrections(line2)
+    errors: list[str] = []
+
+    # --- Line 1 ---
+    # Pos 0:     document type (1 char, usually 'P')
+    # Pos 1:     document type sub (1 char)
+    # Pos 2-4:   issuing country (3 chars)
+    # Pos 5-43:  name (surname << given names)
+
+    doc_type_raw = line1[0:2]
+    country_raw = line1[2:5]
+    name_raw = line1[5:44]
+
+    # Split name: surname and given names separated by "<<"
+    name_parts = name_raw.split("<<", 1)
+    surname_raw = name_parts[0] if name_parts else ""
+    given_raw = name_parts[1] if len(name_parts) > 1 else ""
+    # Within given names a single filler separates components. A double filler
+    # starts padding; OCR noise later in that padding is not an extra name.
+    given_value, _, padding = given_raw.partition("<<")
+    if padding.replace("<", ""):
+        errors.append("MRZ_NAME_PADDING_NOISE")
+
+    # --- Line 2 ---
+    # Pos 0-8:   passport number (9 chars)
+    # Pos 9:     check digit for passport number
+    # Pos 10-12: nationality (3 chars)
+    # Pos 13-18: date of birth YYMMDD (6 chars)
+    # Pos 19:    check digit for DOB
+    # Pos 20:    sex (M/F/<)
+    # Pos 21-26: expiry date YYMMDD (6 chars)
+    # Pos 27:    check digit for expiry
+    # Pos 28-41: personal number (14 chars)
+    # Pos 42:    check digit for personal number
+    # Pos 43:    overall check digit
+
+    pn_raw = line2[0:9]
+    pn_check = line2[9]
+    nationality_raw = line2[10:13]
+    dob_raw = line2[13:19]
+    dob_check = line2[19]
+    sex_raw = line2[20]
+    expiry_raw = line2[21:27]
+    expiry_check = line2[27]
+    personal_raw = line2[28:42]
+    personal_check = line2[42]
+    overall_check = line2[43]
+
+    # Validate check digits
+    pn_valid = verify_check_digit(pn_raw, pn_check)
+    dob_valid = verify_check_digit(dob_raw, dob_check)
+    expiry_valid = verify_check_digit(expiry_raw, expiry_check)
+    # ICAO Doc 9303-4 permits '<' instead of zero for unused optional data.
+    personal_valid = (
+        personal_raw == "<" * 14 and personal_check == "<"
+    ) or verify_check_digit(personal_raw, personal_check)
+
+    # Overall check digit: computed over passport_number + check + DOB + check + expiry + check + personal + check
+    composite = line2[0:10] + line2[13:20] + line2[21:43]
+    overall_valid = verify_check_digit(composite, overall_check)
+
+    if not pn_valid:
+        errors.append("PASSPORT_NUMBER_CHECKSUM_FAILED")
+    if not dob_valid:
+        errors.append("DOB_CHECKSUM_FAILED")
+    if not expiry_valid:
+        errors.append("EXPIRY_CHECKSUM_FAILED")
+    if not personal_valid:
+        errors.append("PERSONAL_NUMBER_CHECKSUM_FAILED")
+    if not overall_valid:
+        errors.append("OVERALL_CHECKSUM_FAILED")
+
+    # Parse sex
+    sex_value = None
+    if sex_raw in ("M", "F"):
+        sex_value = sex_raw
+    elif sex_raw == "<" or sex_raw == "X":
+        sex_value = "X"
+
+    return MRZResult(
+        document_type=MRZField(value=doc_type_raw.replace("<", "").strip() or "P", raw=doc_type_raw),
+        country_code=MRZField(value=country_raw.replace("<", ""), raw=country_raw),
+        surname=MRZField(value=_clean_name(surname_raw), raw=surname_raw),
+        given_names=MRZField(value=_clean_name(given_value), raw=given_raw),
+        passport_number=MRZField(
+            value=pn_raw.replace("<", "").strip(),
+            raw=pn_raw,
+            checksum_valid=pn_valid,
+        ),
+        nationality=MRZField(value=nationality_raw.replace("<", ""), raw=nationality_raw),
+        date_of_birth=MRZField(
+            value=_parse_mrz_date(dob_raw),
+            raw=dob_raw,
+            checksum_valid=dob_valid,
+        ),
+        sex=MRZField(value=sex_value, raw=sex_raw),
+        expiry_date=MRZField(
+            value=_parse_mrz_date(expiry_raw, is_expiry=True),
+            raw=expiry_raw,
+            checksum_valid=expiry_valid,
+        ),
+        personal_number=MRZField(
+            value=personal_raw.replace("<", "").strip() or None,
+            raw=personal_raw,
+            checksum_valid=personal_valid,
+        ),
+        overall_checksum_valid=overall_valid and pn_valid and dob_valid and expiry_valid and personal_valid,
+        raw_lines=(line1, line2),
+        errors=errors,
+    )

package/python/core/mrz_recovery.py

@@ -0,0 +1,193 @@
+"""Bounded, geometry-based re-reading of a damaged passport MRZ.
+
+Only a checksum-valid TD3 pair is admitted; identifiers are never invented.
+"""
+from __future__ import annotations
+
+import re
+
+import cv2
+import numpy as np
+
+from .mrz_parser import _clean_mrz_text, parse_mrz, verify_check_digit
+from .ocr_engine import TextRegion
+from .recovery_budget import recovery_allowed
+
+# A complete surname/given-name header with an observed padding terminator.
+_PADDED_HEADER = re.compile(r'P[A-Z<][A-Z<]{3}[A-Z]+(?:<[A-Z]+)*<<[A-Z]+(?:<[A-Z]+)*<{2,}')
+_ANCHOR = re.compile(r'[A-Z0-9<]{28,44}')
+_LINE_TWO = re.compile(r'[A-Z0-9<]{9}[0-9][A-Z<]{3}[0-9]{7}[MF<][0-9]{7}[A-Z0-9<]{16}')
+_LINE_TWO_PREFIX = re.compile(r'[A-Z0-9<]{9}[0-9][A-Z]{3}[0-9]{7}[MF<][0-9]{7}[A-Z0-9<]{0,15}')
+
+
+def _checked_line_two_prefix(text: str) -> bool:
+    """Locate a truncated row from observed fields, without filling its suffix."""
+    return bool(_LINE_TWO_PREFIX.fullmatch(text)
+                and verify_check_digit(text[:9], text[9])
+                and verify_check_digit(text[13:19], text[19])
+                and verify_check_digit(text[21:27], text[27]))
+
+
+def _anchors(regions: list[TextRegion]) -> list[TextRegion]:
+    result = []
+    for row in regions:
+        text = _clean_mrz_text(row.text)
+        if (len(row.bbox) == 4 and _ANCHOR.fullmatch(text)
+                and (text.count('<') >= 2 or _LINE_TWO.fullmatch(text) or _checked_line_two_prefix(text))
+                and (not text.startswith('P') or _LINE_TWO.fullmatch(text) or _checked_line_two_prefix(text))):
+            result.append(row)
+    return result
+
+
+def has_mrz_anchor(regions: list[TextRegion]) -> bool:
+    """True when the regions contain a row recovery could re-read as an MRZ."""
+    return bool(_anchors(regions))
+
+
+def _read_crop(image, src, width, height, reader) -> list[TextRegion]:
+    """Read a deskewed crop and map evidence back to page coordinates."""
+    dst = np.array([[0, 0], [width - 1, 0], [width - 1, height - 1], [0, height - 1]], np.float32)
+    transform = cv2.getPerspectiveTransform(np.asarray(src, np.float32), dst)
+    if abs(np.linalg.det(transform)) < 1e-12:
+        return []
+    crop = cv2.warpPerspective(image, transform, (width, height), borderValue=(255, 255, 255))
+    inverse = np.linalg.inv(transform)
+    recovered = []
+    for region in reader(crop):
+        text = _clean_mrz_text(region.text)
+        if 20 <= len(text) < 44 and _PADDED_HEADER.fullmatch(text):
+            # Only omitted trailing fillers can be recovered from this rule.
+            text = text.ljust(44, '<')
+        points = np.asarray(region.bbox, np.float32)
+        if points.shape != (4, 2) or not np.isfinite(points).all():
+            continue
+        points = cv2.perspectiveTransform(points[None], inverse)[0]
+        recovered.append(TextRegion(text, points.round().astype(int).tolist(), region.confidence))
+    return recovered
+
+
+def recover_passport_mrz(image, regions: list[TextRegion], ocr, recognize_line=None,
+                         band_ocr=None) -> list[TextRegion]:
+    """Re-read a damaged MRZ. ``band_ocr`` reads thin band crops (defaults to ``ocr``).
+
+    Every re-read is optional and starts only while the scan's recovery budget
+    remains (see recovery_budget); the input regions are returned otherwise.
+    """
+    band_ocr = band_ocr or ocr
+    existing = parse_mrz(regions)
+    if existing and existing.overall_checksum_valid and 'MRZ_NAME_PADDING_NOISE' not in existing.errors:
+        return regions
+    if existing and existing.overall_checksum_valid:
+        # Only name-padding cleanup remains. It reads filler more reliably at
+        # the default enlargement and runs on already-valid scans, so keep it.
+        band_ocr = ocr
+    long_rows = [r for r in regions if len(r.text) >= 8 and len(r.bbox) == 4]
+    vertical_rows = [r for r in long_rows if
+                     abs(r.bbox[1][1] - r.bbox[0][1]) > 2 * abs(r.bbox[1][0] - r.bbox[0][0])
+                     or (max(p[1] for p in r.bbox) - min(p[1] for p in r.bbox)) >
+                     2 * (max(p[0] for p in r.bbox) - min(p[0] for p in r.bbox))]
+    if len(vertical_rows) >= 4 and len(vertical_rows) / len(long_rows) >= .6:
+        # Sideways lines cannot reliably be recognized or paired in page-Y
+        # order. Try each quarter-turn, keeping original-page evidence boxes.
+        h, w = image.shape[:2]
+        corners = [(0, 0), (w - 1, 0), (w - 1, h - 1), (0, h - 1)]
+        for order in ((3, 0, 1, 2), (1, 2, 3, 0)):
+            if not recovery_allowed():
+                break
+            recovered = _read_crop(image, [corners[i] for i in order], h, w, ocr)
+            parsed = parse_mrz(recovered)
+            if parsed and parsed.overall_checksum_valid:
+                return recovered
+        return regions  # The two-read budget is exhausted.
+    anchors = _anchors(regions)
+    band_budget = 2
+    if not anchors and any(re.search(r'\bPASSPORT\b', r.text, re.I) for r in regions):
+        # A small passport in a large photo can lose its entire MRZ during
+        # detection downscaling. Focus on confident visible document text once.
+        body = [r for r in regions if len(r.text) >= 4 and r.confidence >= .85 and len(r.bbox) == 4]
+        if len(body) >= 5:
+            points = np.asarray([p for r in body for p in r.bbox], np.float32)
+            left, top = points.min(axis=0)
+            right, bottom = points.max(axis=0)
+            bw, bh = right - left, bottom - top
+            h, w = image.shape[:2]
+            x1, y1 = max(0, int(left - bw * .2)), max(0, int(top - bh * .15))
+            x2, y2 = min(w, int(right + bw * .2)), min(h, int(bottom + bh * .4))
+            if (bw >= 200 and bh >= 100 and 0 < (x2 - x1) * (y2 - y1) < w * h * .75
+                    and recovery_allowed()):
+                recovered = _read_crop(image, [(x1, y1), (x2, y1), (x2, y2), (x1, y2)],
+                                       x2 - x1, y2 - y1, ocr)
+                parsed = parse_mrz(recovered)
+                if parsed and parsed.overall_checksum_valid:
+                    return recovered
+                # Detection may reveal only the beginning of the bottom row.
+                # Reuse its original-page geometry for one final band read;
+                # never insert unobserved suffix characters or check digits.
+                anchors = _anchors(recovered)
+                band_budget -= 1
+    # At most two band reads, plus one recognition-only fallback per full anchor.
+    for anchor in sorted(anchors, key=lambda r: len(_clean_mrz_text(r.text)), reverse=True)[:band_budget]:
+        box = np.asarray(anchor.bbox, dtype=np.float32)
+        if box.shape != (4, 2) or not np.isfinite(box).all():
+            continue
+        tl, tr, br, bl = box
+        vertical = ((bl - tl) + (br - tr)) / 2
+        width, line_height = float(np.linalg.norm(tr - tl)), float(np.linalg.norm(vertical))
+        if width < 100 or line_height < 5 or width / line_height < 8:
+            continue
+        if not recovery_allowed():
+            break
+        # Include the line above and a little border. Deskew using detected text,
+        # which still works when a document occupies a small part of a photograph.
+        # A TD3 line has 44 fixed-width characters. A partial detection must not
+        # clip the unseen right-hand characters from the recovery crop.
+        anchor_text = _clean_mrz_text(anchor.text)
+        extension = (44 / len(anchor_text) - 1) * (tr - tl)
+        tr, br = tr + extension, br + extension
+        if _checked_line_two_prefix(anchor_text):
+            # A truncated detector box can end inside a character. Leave one
+            # character of pixels at either edge of the predicted full row.
+            margin = (tr - tl) / 44
+            tl, bl, tr, br = tl - margin, bl - margin, tr + margin, br + margin
+        full_width = float(np.linalg.norm(tr - tl))
+        w = min(1600, int(full_width))
+        h = max(20, int(line_height * 4 * w / full_width))
+        src = [tl - 2.5 * vertical, tr - 2.5 * vertical,
+               br + .5 * vertical, bl + .5 * vertical]
+        recovered = _read_crop(image, src, w, h, band_ocr)
+        # The original full-width line two can be better than the cropped reading.
+        # Evaluate complete re-read first, then each recovered header with its anchor.
+        candidates = [recovered] + [[r, anchor] for r in recovered
+                                    if _PADDED_HEADER.fullmatch(_clean_mrz_text(r.text))]
+        def candidate_reads():
+            yield from candidates
+            if (recognize_line is None or not _LINE_TWO.fullmatch(_clean_mrz_text(anchor.text))
+                    or not recovery_allowed()):
+                return
+            # A complete bottom line also localizes the name line immediately
+            # above it. Bypass detection when that line was missed in the band.
+            line_src = [tl - 1.1 * vertical, tr - 1.1 * vertical,
+                        tr + .1 * vertical, tl + .1 * vertical]
+            line_height_px = max(10, int(line_height * 1.2 * w / full_width))
+            header = _read_crop(image, line_src, w, line_height_px, recognize_line)
+            for row in header:
+                # Names have no check digit: require clean syntax, observed name
+                # termination, and high recognition confidence before admission.
+                if row.confidence >= .9 and _PADDED_HEADER.fullmatch(row.text):
+                    yield [row, anchor]
+
+        for candidate in candidate_reads():
+            parsed = parse_mrz(candidate)
+            if not parsed or not parsed.overall_checksum_valid:
+                continue
+            if existing and existing.overall_checksum_valid and 'MRZ_NAME_PADDING_NOISE' in parsed.errors:
+                continue
+            if existing and existing.passport_number.value != parsed.passport_number.value:
+                continue
+            # Preserve visual text and its coordinates; replace only MRZ-like rows.
+            visual = [r for r in regions if not (
+                _ANCHOR.fullmatch(_clean_mrz_text(r.text))
+                and ('<' in _clean_mrz_text(r.text) or _LINE_TWO.fullmatch(_clean_mrz_text(r.text))))]
+            mrz_rows = [r for r in candidate if _ANCHOR.fullmatch(_clean_mrz_text(r.text))]
+            return visual + mrz_rows
+    return regions