#!/usr/bin/env python3 """Run the catalog's downloaded ONNX files locally, without network requests. Python 3.12; install local-requirements.txt first. Download model-manifest.json beside this file and put the selected ONNX files in --weights-dir. Pre/postprocessing adapted from Apache-2.0 DocsaidLab/DocAligner and MRZScanner; source commits and licenses are listed in local-NOTICE.txt. """ from __future__ import annotations import argparse import hashlib import json from pathlib import Path from typing import Any import cv2 import numpy as np import onnxruntime as ort from PIL import Image, ImageOps cv2.setNumThreads(1) def read_image(path: Path) -> np.ndarray: """Read a still image, apply EXIF, composite alpha on white, limit long side.""" if path.stat().st_size > 10 * 1024 * 1024: raise ValueError("Image exceeds 10 MiB") with Image.open(path) as source: if source.format not in {"JPEG", "PNG", "WEBP"} or getattr(source, "n_frames", 1) != 1: raise ValueError("Use a still JPEG, PNG or WebP") if source.width * source.height > 40_000_000: raise ValueError("Image exceeds 40 megapixels") pixels = ImageOps.exif_transpose(source).convert("RGBA") image = Image.new("RGBA", pixels.size, "white") image.alpha_composite(pixels) image = image.convert("RGB") image.thumbnail((1600, 1600), Image.Resampling.LANCZOS) return np.ascontiguousarray(np.asarray(image)[:, :, ::-1]) # Models use BGR. def tensor(image: np.ndarray, size: tuple[int, int]) -> np.ndarray: resized = cv2.resize(image, (size[1], size[0]), interpolation=cv2.INTER_LINEAR) return np.ascontiguousarray(resized.transpose(2, 0, 1)[None], dtype=np.float32) / 255.0 def square_pad(image: np.ndarray) -> tuple[np.ndarray, np.ndarray]: h, w = image.shape[:2] vertical, horizontal = max(0, (w - h) // 2), max(0, (h - w) // 2) # Matches the published models, including odd-size padding. return cv2.copyMakeBorder(image, vertical, vertical, horizontal, horizontal, cv2.BORDER_CONSTANT, value=(0, 0, 0)), np.float32([horizontal, vertical]) def largest_contour(mask: np.ndarray) -> np.ndarray | None: _, binary = cv2.threshold(mask, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU) contours, _ = cv2.findContours(binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE) valid = [contour for contour in contours if len(contour) > 2 and cv2.contourArea(contour) > 0] return max(valid, key=cv2.contourArea) if valid else None def ordered_rectangle(points: np.ndarray) -> np.ndarray: left_to_right = points[np.argsort(points[:, 0])] left = left_to_right[:2][np.argsort(left_to_right[:2, 1])] right = left_to_right[2:][np.argsort(left_to_right[2:, 1])] return np.float32([left[0], right[0], right[1], left[1]]) def crop_mrz(image: np.ndarray, points: np.ndarray) -> np.ndarray: rectangle = cv2.minAreaRect(points) width, height = int(max(rectangle[1])), int(min(rectangle[1])) if min(width, height) < 2 or max(width, height) > 4096 or width * height > 4_000_000: raise ValueError("Detected MRZ region is invalid") source = ordered_rectangle(points) target = np.float32([[0, 0], [width, 0], [width, height], [0, height]]) matrix = cv2.getPerspectiveTransform(source, target) if abs(float(np.linalg.det(matrix))) < 1e-10: raise ValueError("Detected MRZ region is degenerate") return cv2.warpPerspective(image, matrix, (width, height)) def decode(logits: np.ndarray, spotting: bool) -> list[str]: chars = ["", ""] + ([] if spotting else [""]) + list("ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789<") + (["&"] if spotting else []) output = [] for raw in logits.argmax(-1).reshape(-1): index = int(raw) if index == 1: break if index >= len(chars): raise ValueError("Unexpected recognition vocabulary") output.append(chars[index]) return "".join(output).split("&" if spotting else "") def postprocess(lines: list[str]) -> tuple[list[str], bool]: """Published format-based substitutions; no check-digit verification.""" digits = str.maketrans(dict(zip("OQUDIZASB", "000012458", strict=True))) letters = str.maketrans(dict(zip("012458", "OIZASB", strict=True))) sex = str.maketrans({"P": "F", "N": "M"}) result = list(lines) if len(lines) == 3 and all(len(line) == 30 for line in lines): a, b, _ = lines result[0] = a[:2] + a[2:5].translate(letters) + a[5:14] + a[14].translate(digits) + a[15:] result[1] = b[:7].translate(digits) + b[7].translate(sex) + b[8:15].translate(digits) + b[15:18].translate(letters) + b[18:] elif len(lines) == 2 and len(lines[0]) == len(lines[1]) and len(lines[0]) in (36, 44): b = lines[1] result[1] = b[:9] + b[9].translate(digits) + b[10:13].translate(letters) + b[13:20].translate(digits) + b[20].translate(sex) + b[21:28].translate(digits) + b[28:] else: return result, False return result, True class LocalModel: def __init__(self, release_id: str, weights: Path, manifest: Path) -> None: data = json.loads(manifest.read_text(encoding="utf-8")) self.release = next((row for row in data["releases"] if row["id"] == release_id), None) if self.release is None: raise ValueError("Choose a release ID from model-manifest.json") self.sessions: dict[str, ort.InferenceSession] = {} settings = ort.SessionOptions() settings.intra_op_num_threads = 1 settings.inter_op_num_threads = 1 settings.execution_mode = ort.ExecutionMode.ORT_SEQUENTIAL for artifact_id in self.release["artifact_ids"]: artifact = next(row for row in data["artifacts"] if row["id"] == artifact_id) file = weights / artifact["filename"] if not file.is_file(): file = weights / artifact["path"] if not file.is_file() or hashlib.sha256(file.read_bytes()).hexdigest() != artifact["sha256"]: raise ValueError(f"Missing file or SHA-256 mismatch: {artifact['filename']}") self.sessions[artifact["kind"]] = ort.InferenceSession(str(file), sess_options=settings, providers=["CPUExecutionProvider"]) def run(self, kind: str, image: np.ndarray, size: tuple[int, int]) -> dict[str, np.ndarray]: session = self.sessions[kind] outputs = session.run(None, {session.get_inputs()[0].name: tensor(image, size)}) return dict(zip((value.name for value in session.get_outputs()), outputs, strict=True)) def __call__(self, image: np.ndarray, *, do_postprocess: bool = False) -> dict[str, Any]: h, w = image.shape[:2] result: dict[str, Any] = {"model_version": self.release["id"], "image_width": w, "image_height": h} if self.release["product"] == "docaligner": kind = next(iter(self.sessions)) outputs = self.run(kind, image, (256, 256)) points = [] if "heatmap" in outputs: for heatmap in outputs["heatmap"][0][:4]: plane = cv2.resize(heatmap, (w, h), interpolation=cv2.INTER_LINEAR) plane[plane < .3] = 0 contour = largest_contour(np.uint8(plane * 255)) if contour is not None: moments = cv2.moments(contour) points.append([moments["m10"] / (moments["m00"] + 1e-5), moments["m01"] / (moments["m00"] + 1e-5)]) elif float(outputs["has_obj"].reshape(-1)[0]) > .5: points = (outputs["points"].reshape(4, 2) * [w, h]).tolist() result.update(polygon=points, detected=len(points) == 4) return result padded, shift = square_pad(image) if self.release["configuration"]["model_type"] == "spotting": outputs = self.run("spotting", padded, (512, 512)) lines = decode(next(iter(outputs.values())), True) result["mrz_polygon"] = None else: outputs = self.run("det", padded, (256, 256)) heatmap = np.squeeze(next(iter(outputs.values()))) mask = cv2.resize(np.uint8(heatmap * 255), (padded.shape[1], padded.shape[0]), interpolation=cv2.INTER_LINEAR) contour = largest_contour(mask) if contour is None: return {**result, "mrz_polygon": [], "mrz_texts": [], "format_valid": False, "error": "mrz_not_detected"} points = cv2.boxPoints(cv2.minAreaRect(contour)).round(4) - shift outputs = self.run("rec", crop_mrz(image, points), (64, 640)) lines = decode(next(iter(outputs.values())), False) result["mrz_polygon"] = ordered_rectangle(points).tolist() processed, valid = postprocess(lines) result.update(mrz_texts=processed if do_postprocess else lines, format_valid=valid, postprocess_enabled=do_postprocess, check_digits_verified=False) return result def save_result(folder: Path, image: np.ndarray, result: dict[str, Any]) -> None: folder.mkdir(mode=0o700, parents=True, exist_ok=False) (folder / "result.json").write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8") canvas = image.copy() points = result.get("polygon") or result.get("mrz_polygon") if points and len(points) == 4: cv2.polylines(canvas, [np.rint(points).astype(np.int32)], True, (0, 140, 255), 3) if not cv2.imwrite(str(folder / "overlay.png"), canvas): raise ValueError("Unable to save overlay") def main() -> None: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--release", required=True) parser.add_argument("--weights-dir", type=Path, required=True) parser.add_argument("--manifest", type=Path, default=Path(__file__).with_name("model-manifest.json")) parser.add_argument("--image", type=Path, required=True) parser.add_argument("--output", type=Path, required=True, help="New local output directory") parser.add_argument("--postprocess", action="store_true") args = parser.parse_args() try: if args.output.exists(): raise ValueError("Output directory already exists; choose a new name") image = read_image(args.image) model = LocalModel(args.release, args.weights_dir, args.manifest) result = model(image, do_postprocess=args.postprocess) save_result(args.output, image, result) print("Saved result.json and overlay.png locally. Inspect the image and returned fields before use.") except (ValueError, OSError, ort.capi.onnxruntime_pybind11_state.Fail) as error: parser.exit(1, f"Local inference failed: {error}\n") if __name__ == "__main__": main()