Tuning Tesseract OCR for Government Form Layouts #

import cv2
import numpy as np
import pytesseract
import logging
import hashlib
import json
from dataclasses import dataclass, asdict
from pathlib import Path

# Structured JSON audit logging: one append-only line per page, reconstructable
# during a FOIA challenge per 5 U.S.C. § 552(a)(6)(A)(i) (20-business-day window).
logging.basicConfig(level=logging.INFO, format="%(message)s",
                    handlers=[logging.FileHandler("ocr_audit.log"), logging.StreamHandler()])
log = logging.getLogger("tesseract_tuning")


@dataclass(frozen=True)
class FormProfile:
    """Per-template recognition settings — tuned data, not hard-coded constants."""
    name: str
    psm: int                 # 6 = uniform block (dense fields); 11 = sparse (checkboxes)
    whitelist: str           # restrict glyphs to suppress noise; never strip legitimate chars
    min_linesize: int = 8    # ignore micro-stamps and security seals as text

    def config(self) -> str:
        return (f"--oem 3 --psm {self.psm} "
                f"-c preserve_interword_spaces=1 "
                f"-c textord_min_linesize={self.min_linesize} "
                f"-c tessedit_char_whitelist={self.whitelist}")


def _sha256(path: Path) -> str:
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(8192), b""):
            h.update(chunk)
    return h.hexdigest()


def normalize_gov_form(path: Path, target_dpi: int = 300) -> np.ndarray:
    """Deterministic normalization for legacy agency scans."""
    img = cv2.imread(str(path), cv2.IMREAD_GRAYSCALE)
    if img is None:
        raise ValueError(f"Undecodable scan: {path}")  # 1. fail closed, never silently skip

    # 2. DPI-aware upscale: Tesseract segmentation degrades sharply below 250 DPI.
    scale = max(1.0, target_dpi / 200)
    if scale > 1.0:
        img = cv2.resize(img, None, fx=scale, fy=scale, interpolation=cv2.INTER_LANCZOS4)

    # 3. Deskew on text foreground (Otsu + invert) for rotated agency letterheads.
    _, bin_inv = cv2.threshold(img, 0, 255, cv2.THRESH_BINARY_INV | cv2.THRESH_OTSU)
    coords = np.column_stack(np.where(bin_inv > 0))
    if coords.size == 0:
        raise ValueError(f"Blank page, no foreground pixels: {path}")
    angle = cv2.minAreaRect(coords)[-1]
    angle = -(90 + angle) if angle < -45 else -angle
    h, w = img.shape[:2]
    rot = cv2.getRotationMatrix2D((w // 2, h // 2), angle, 1.0)
    img = cv2.warpAffine(img, rot, (w, h), flags=cv2.INTER_CUBIC,
                         borderMode=cv2.BORDER_REPLICATE)

    # 4. Adaptive threshold for faded thermal prints, carbon copies, low-contrast stamps.
    thresh = cv2.adaptiveThreshold(img, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
                                   cv2.THRESH_BINARY, 15, 8)

    # 5. Strip table grid lines that fracture character segmentation on form fields.
    kh = cv2.getStructuringElement(cv2.MORPH_RECT, (40, 1))
    kv = cv2.getStructuringElement(cv2.MORPH_RECT, (1, 40))
    grid = cv2.add(cv2.morphologyEx(thresh, cv2.MORPH_OPEN, kh),
                   cv2.morphologyEx(thresh, cv2.MORPH_OPEN, kv))
    cleaned = cv2.bitwise_and(thresh, thresh, mask=cv2.bitwise_not(grid))

    # 6. Denoise security watermarks (low-frequency) while preserving fine print.
    return cv2.fastNlMeansDenoising(cleaned, h=10, templateWindowSize=7, searchWindowSize=21)


def recognize(path: Path, profile: FormProfile, conf_floor: float = 65.0) -> dict:
    """Normalize, OCR with the form profile, and emit an auditable record."""
    img = normalize_gov_form(path)
    text = pytesseract.image_to_string(img, config=profile.config()).strip()

    # 7. Per-word confidence drives review routing, not a single aggregate score.
    data = pytesseract.image_to_data(img, config=profile.config(),
                                     output_type=pytesseract.Output.DICT)
    confs = [int(c) for c in data["conf"] if c != "-1"]
    mean_conf = round(sum(confs) / len(confs), 1) if confs else 0.0

    record = {
        "source": path.name,
        "source_sha256": _sha256(path),          # 8. bind output to exact source bytes
        "text_sha256": hashlib.sha256(text.encode()).hexdigest(),
        "profile": profile.name,
        "psm": profile.psm,
        "mean_confidence": mean_conf,
        "routed_to_review": mean_conf < conf_floor,  # 9. doubtful pages go to humans
        "chars": len(text),
    }
    log.info(json.dumps(record))                 # 10. one append-only audit line
    return {**record, "text": text}


PROFILES = {
    "tax_schedule": FormProfile("tax_schedule", psm=6,
        whitelist="0123456789.,-$%() ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"),
    "permit_form": FormProfile("permit_form", psm=11,
        whitelist="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789.,-:/#() "),
}

if __name__ == "__main__":
    out = recognize(Path("scans/form_0001.png"), PROFILES["tax_schedule"])
    print(f"{out['source']}: conf={out['mean_confidence']} review={out['routed_to_review']}")

form_0001.png: conf=92.4 review=False
{"source": "form_0001.png", "source_sha256": "9f2c…", "text_sha256": "4ab1…",
 "profile": "tax_schedule", "psm": 6, "mean_confidence": 92.4,
 "routed_to_review": false, "chars": 1842}

a = recognize(Path("scans/form_0001.png"), PROFILES["tax_schedule"])
b = recognize(Path("scans/form_0001.png"), PROFILES["tax_schedule"])
assert a["text_sha256"] == b["text_sha256"], "Non-deterministic OCR output"