indra-ocr 0.3.0__py3-none-any.whl

indra_ocr/__init__.py

@@ -0,0 +1,49 @@
+"""Indra OCR: fast CPU OCR (line detection, CTC recognition, reading order, markdown)."""
+
+from .document import Converter
+from .models import model_dir
+from .parallel import convert_many, usable_cores
+from .pipeline import InputError, Line, OrtOCR, Page, load_pages
+
+__all__ = [
+    "Converter",
+    "InputError",
+    "Line",
+    "OrtOCR",
+    "Page",
+    "convert_many",
+    "usable_cores",
+    "load_pages",
+    "load",
+    "model_dir",
+]
+__version__ = "0.3.0"
+
+
+def load(
+    path=None,
+    threads: int = 4,
+    dpi: float = 200.0,
+    mode: str = "auto",
+    pdf_order: bool = True,
+    image_ocr: bool = True,
+    providers: list | None = None,
+    furniture: bool = False,
+    math: bool = False,
+) -> Converter:
+    """A ready Converter (see ``Converter`` for the options).  mode="ocr" never
+    reads the PDF text layer.  furniture: keep page headers and footers in the
+    markdown.  math: write math as LaTeX (slower on math pages; off by default)."""
+    return Converter(
+        OrtOCR(
+            model_dir(path, math=math),
+            threads=threads,
+            providers=providers,
+            furniture=furniture,
+            math=math,
+        ),
+        dpi=dpi,
+        mode=mode,
+        pdf_order=pdf_order,
+        image_ocr=image_ocr,
+    )

indra_ocr/__main__.py

@@ -0,0 +1,4 @@
+from indra_ocr.cli import main
+
+if __name__ == "__main__":
+    main()

indra_ocr/cli.py

@@ -0,0 +1,161 @@
+"""Command line: PDFs or images in, markdown (or text, or JSON lines) out.
+
+indra-ocr paper.pdf                    # markdown to stdout
+indra-ocr *.pdf --out results/         # one .md per input
+indra-ocr scan.png --format json       # lines with boxes, confidences, timings
+
+Pages run in parallel on all the cores the process may use (--cores to limit).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from . import InputError
+from .parallel import convert_many, usable_cores
+
+
+def add_source_args(ap: argparse.ArgumentParser) -> None:
+    """Options that choose between the PDF text layer and OCR."""
+    g = ap.add_argument_group("text layer or OCR (PDFs)")
+    g.add_argument(
+        "--mode",
+        choices=["auto", "ocr", "text"],
+        default="auto",
+        help="auto: text layer where it passes the checks, OCR elsewhere (default); "
+        "ocr: never read the text layer; text: use the text layer even when the "
+        "checks fail",
+    )
+    g.add_argument(
+        "--model-order",
+        action="store_true",
+        help="order text-layer lines with the order model, not the PDF content order",
+    )
+    g.add_argument(
+        "--no-image-ocr",
+        action="store_true",
+        help="on text-layer pages, do not OCR text inside images",
+    )
+
+
+def source_options(a) -> dict:
+    return {
+        "mode": a.mode,
+        "pdf_order": not a.model_order,
+        "image_ocr": not a.no_image_ocr,
+    }
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="indra-ocr",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    ap.add_argument("inputs", nargs="+", type=Path)
+    ap.add_argument(
+        "--out", type=Path, default=None, help="write one file per input here"
+    )
+    ap.add_argument("--format", choices=["md", "text", "json"], default="md")
+    add_source_args(ap)
+    ap.add_argument("--model-dir", type=Path, default=None)
+    ap.add_argument(
+        "--cores",
+        "--threads",
+        dest="cores",
+        type=int,
+        default=0,
+        help=f"cores to use (default: all this process may run on, here {usable_cores()})",
+    )
+    ap.add_argument("--dpi", type=float, default=200.0)
+    ap.add_argument("--max-pages", type=int, default=0)
+    ap.add_argument("--password", default=None, help="password of encrypted PDFs")
+    ap.add_argument(
+        "--math",
+        action="store_true",
+        help="write math as LaTeX ($...$); slower on pages with math (off by default)",
+    )
+    ap.add_argument(
+        "--keep-furniture",
+        action="store_true",
+        help="keep page headers and footers (page numbers, running titles) in the markdown",
+    )
+    ap.add_argument(
+        "--timings", action="store_true", help="print per-page timings to stderr"
+    )
+    a = ap.parse_args(argv)
+    if a.out:
+        a.out.mkdir(parents=True, exist_ok=True)
+    ext = {"md": ".md", "text": ".txt", "json": ".jsonl"}[a.format]
+    failed, names = 0, set()
+    results = convert_many(
+        a.inputs,
+        cores=a.cores,
+        max_pages=a.max_pages,
+        password=a.password,
+        path=a.model_dir,
+        dpi=a.dpi,
+        furniture=a.keep_furniture,
+        math=a.math,
+        **source_options(a),
+    )
+    for path, result in results:
+        path = Path(path)
+        chunks = []
+        if isinstance(result, InputError):
+            print(f"indra-ocr: {result}", file=sys.stderr)
+            failed += 1
+            continue
+        for i, page in result:
+            if page.source == "error":
+                print(f"indra-ocr: {path} page {i + 1}: {page.note}", file=sys.stderr)
+            if a.format == "json":
+                chunks.append(
+                    json.dumps(
+                        {
+                            "file": str(path),
+                            "page": i,
+                            "source": page.source,
+                            "rotation": page.rotation,
+                            "skew": page.skew,
+                            "note": page.note,
+                            "lines": [asdict(ln) for ln in page.lines],
+                            "markdown": page.markdown,
+                            "blocks": page.blocks,
+                            "timings": page.timings,
+                        },
+                        ensure_ascii=False,
+                    )
+                )
+            elif a.format == "md":
+                chunks.append(page.markdown if page.markdown is not None else page.text)
+            else:
+                chunks.append(page.text)
+            if a.timings:
+                t = page.timings
+                print(
+                    f"{path} page {i + 1}: {page.source}, {t.get('total_ms', 0):.0f} ms {page.note}",
+                    file=sys.stderr,
+                )
+        sep = "\n" if a.format == "json" else "\n\n"
+        body = sep.join(chunks) + "\n"
+        if a.out:
+            name, k = path.stem, 1
+            while name in names:  # two inputs with one name: keep both outputs
+                k += 1
+                name = f"{path.stem}_{k}"
+            names.add(name)
+            (a.out / (name + ext)).write_text(body, encoding="utf-8")
+        else:
+            sys.stdout.write(body)
+    if failed:
+        print(f"indra-ocr: {failed} of {len(a.inputs)} inputs failed", file=sys.stderr)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

indra_ocr/det_post.py

@@ -0,0 +1,155 @@
+"""Torch-free pre- and post-processing for LineNet (shared by training and inference).
+
+Inference with ONNX Runtime needs only numpy and cv2, so these functions live
+apart from the PyTorch model in det_model.py, which re-exports them.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+# Target geometry, shared by training (encode) and inference (decode).
+CORE_FRAC = 0.4  # core band height as a fraction of the line ink height
+CORE_X_SHRINK = 0.15  # the core is shorter than the line by this fraction of its height, at each end
+OUT_STRIDE = 2
+INPUT_MULTIPLE = 32  # H and W must divide by this
+
+
+# ---------------------------------------------------------------------------
+# Input preprocessing (shared by training and inference)
+# ---------------------------------------------------------------------------
+
+
+def page_to_input(gray: np.ndarray, long_side: int) -> tuple[np.ndarray, float]:
+    """Resize a uint8 grayscale page so its long side is ``long_side`` and pad
+    to a multiple of 32 with white.  Returns (float32 [H, W] ink map, scale)."""
+    import cv2
+
+    h, w = gray.shape
+    scale = long_side / max(h, w)
+    nh, nw = max(1, round(h * scale)), max(1, round(w * scale))
+    if (nh, nw) != (h, w):
+        interp = cv2.INTER_AREA if scale < 1 else cv2.INTER_LINEAR
+        gray = cv2.resize(gray, (nw, nh), interpolation=interp)
+    ph = math.ceil(nh / INPUT_MULTIPLE) * INPUT_MULTIPLE
+    pw = math.ceil(nw / INPUT_MULTIPLE) * INPUT_MULTIPLE
+    out = np.zeros((ph, pw), np.float32)  # ink map: 0 = white
+    out[:nh, :nw] = 1.0 - gray.astype(np.float32) / 255.0
+    return out, scale
+
+
+# ---------------------------------------------------------------------------
+# Targets
+# ---------------------------------------------------------------------------
+
+
+def encode_targets(
+    boxes: np.ndarray,
+    in_hw: tuple[int, int],
+    valid_hw: tuple[int, int],
+    ignore: np.ndarray | None = None,
+):
+    """Build training targets at 1/2 resolution.
+
+    boxes:   [N, 4] line ink boxes in input pixels (x0, y0, x1, y1)
+    in_hw:   padded input size; valid_hw: size of the real page inside it
+    ignore:  [M, 4] regions with no loss, in input pixels
+
+    Returns core [h, w] float32, dist [2, h, w] float32, weight [h, w] float32
+    (0 on padding and ignore regions), and reg_mask [h, w] bool (core pixels).
+    """
+    s = OUT_STRIDE
+    h, w = in_hw[0] // s, in_hw[1] // s
+    core = np.zeros((h, w), np.float32)
+    dist = np.zeros((2, h, w), np.float32)
+    weight = np.zeros((h, w), np.float32)
+    weight[: math.ceil(valid_hw[0] / s), : math.ceil(valid_hw[1] / s)] = 1.0
+    if ignore is not None:
+        for x0, y0, x1, y1 in ignore:
+            weight[
+                max(0, int(y0 // s)) : max(0, math.ceil(y1 / s)),
+                max(0, int(x0 // s)) : max(0, math.ceil(x1 / s)),
+            ] = 0.0
+    # Larger lines first, so a small line drawn later keeps its own band.
+    order = np.argsort(-(boxes[:, 3] - boxes[:, 1])) if len(boxes) else []
+    ys = (np.arange(h, dtype=np.float32) + 0.5) * s  # pixel centres in input px
+    for i in order:
+        x0, y0, x1, y1 = boxes[i]
+        lh = y1 - y0
+        if lh < 2 or x1 - x0 < 2:
+            continue
+        cy = 0.5 * (y0 + y1)
+        half = 0.5 * CORE_FRAC * lh
+        r0 = max(0, int(math.floor((cy - half) / s)))
+        r1 = min(h, max(r0 + 1, int(math.ceil((cy + half) / s))))
+        sx = min(CORE_X_SHRINK * lh, 0.25 * (x1 - x0))
+        c0 = max(0, int(math.floor((x0 + sx) / s)))
+        c1 = min(w, max(c0 + 1, int(math.ceil((x1 - sx) / s))))
+        if r0 >= h or c0 >= w:
+            continue
+        core[r0:r1, c0:c1] = 1.0
+        dist[0, r0:r1, c0:c1] = (ys[r0:r1] - y0)[:, None]
+        dist[1, r0:r1, c0:c1] = (y1 - ys[r0:r1])[:, None]
+        # A line inside an ignore region is still a positive.
+        weight[r0:r1, c0:c1] = np.maximum(weight[r0:r1, c0:c1], 1.0)
+    return core, dist, weight, core > 0.5
+
+
+# ---------------------------------------------------------------------------
+# Decoding
+# ---------------------------------------------------------------------------
+
+
+def decode(
+    out: np.ndarray,
+    thresh: float = 0.5,
+    min_area: int = 2,
+    grow_y: float = 0.0,
+    grow_x: float = 0.0,
+) -> np.ndarray:
+    """Decode one page.  out: [3, h, w] (core logit, top dist, bottom dist).
+
+    ``grow_y`` / ``grow_x`` widen every box by that fraction of its height
+    (each side), to absorb the +-1 px error of the 1/2-resolution output.
+
+    Returns [N, 5] boxes in input pixels: x0, y0, x1, y1, score."""
+    import cv2
+
+    prob = 1.0 / (1.0 + np.exp(-out[0]))
+    mask = (prob > thresh).astype(np.uint8)
+    n, lab, stats, _ = cv2.connectedComponentsWithStats(mask, connectivity=4)
+    if n <= 1:
+        return np.zeros((0, 5), np.float32)
+    s = OUT_STRIDE
+    flat = lab.ravel()
+    keep = flat > 0
+    idx = flat[keep]
+    ys = (np.indices(lab.shape)[0].ravel()[keep].astype(np.float32) + 0.5) * s
+    top = ys - out[1].ravel()[keep]
+    bot = ys + out[2].ravel()[keep]
+    sc = prob.ravel()[keep]
+    cnt = np.bincount(idx, minlength=n).astype(np.float32)
+    # Mean is a robust enough summary here and is far cheaper than a median.
+    y0 = np.bincount(idx, weights=top, minlength=n) / np.maximum(cnt, 1)
+    y1 = np.bincount(idx, weights=bot, minlength=n) / np.maximum(cnt, 1)
+    score = np.bincount(idx, weights=sc, minlength=n) / np.maximum(cnt, 1)
+    boxes = []
+    for i in range(1, n):
+        if stats[i, cv2.CC_STAT_AREA] < min_area:
+            continue
+        lh = max(1.0, y1[i] - y0[i])
+        ex = min(CORE_X_SHRINK * lh, 0.5 * lh)
+        x0 = stats[i, cv2.CC_STAT_LEFT] * s - ex
+        x1 = (stats[i, cv2.CC_STAT_LEFT] + stats[i, cv2.CC_STAT_WIDTH]) * s + ex
+        boxes.append(
+            (
+                x0 - grow_x * lh,
+                y0[i] - grow_y * lh,
+                x1 + grow_x * lh,
+                y1[i] + grow_y * lh,
+                score[i],
+            )
+        )
+    return np.asarray(boxes, np.float32).reshape(-1, 5)

indra_ocr/document.py

@@ -0,0 +1,291 @@
+"""Whole documents: the PDF text layer where it can be trusted, OCR elsewhere.
+
+For each PDF page (``mode="auto"``):
+
+1. Read the text layer with pdfium and check it (``textlayer.read_text_layer``).  A page
+   without a sound layer (a scan, an OCR layer, a broken font map) goes to OCR.
+2. The detector finds the visual lines, as in OCR.  Each text-layer character
+   goes to the detected line that contains its center.  Inside a line, the
+   characters of each text-layer run (pdfium's segment between line breaks) keep the PDF order
+   and spaces, and runs are ordered by x, right to left in a right-to-left line.  So inline math, sub- and
+   superscripts and footnote marks land in their line, and a run across two
+   table cells splits between them.  A detected line with no text (text inside
+   an image) is OCR'd when the recognizer reads the page's script.
+3. The rest is the OCR path: lines split at wide gaps, reading order, layout
+   classes and markdown.  The PDF content order is kept when it is coherent
+   (few upward jumps that are not column changes, and the order model agrees
+   with at least 85% of consecutive pairs).
+
+``mode="ocr"`` never reads the text layer; ``mode="text"`` uses it even when
+the checks fail (and OCR only on pages with no text at all).
+"""
+
+from __future__ import annotations
+
+import time
+import unicodedata
+from pathlib import Path
+
+import numpy as np
+
+from .pipeline import InputError, OrtOCR, Page, is_pdf, read_images
+from .textlayer import BROKEN_FONT_MAP, read_text_layer
+
+CHECK_DPI = 72.0  # resolution of the render for the text-layer ink checks
+MAX_PAGE_PIXELS = 100e6  # a page larger than this at the set dpi renders at a lower dpi (large scans reach ~65 MP)
+
+READABLE_MIN = 0.9  # share of the layer's letters the recognizer must know
+
+
+def readable(ocr: OrtOCR, runs: list) -> bool:
+    """Whether the recognizer can read the script of these text-layer runs."""
+    letters = [c for r in runs for c in r.text if c.isalpha()]
+    if not letters:
+        return True
+    cjk = ocr.vocab_cjk.index if ocr.vocab_cjk is not None else {}
+    known = sum(c in ocr.vocab.index or c in cjk for c in letters)
+    return known >= READABLE_MIN * len(letters)
+
+
+def right_to_left(tokens: list) -> bool:
+    """Unicode bidi base direction: most strong characters are right-to-left."""
+    rtl = ltr = 0
+    for t in tokens:
+        b = unicodedata.bidirectional(t[0]) if len(t[0]) == 1 else ""
+        rtl += b in ("R", "AL")
+        ltr += b == "L"
+    return rtl > ltr
+
+
+def _render(page, scale: float) -> np.ndarray:
+    arr = page.render(scale=scale, grayscale=True).to_numpy()
+    return np.ascontiguousarray(arr[..., 0] if arr.ndim == 3 else arr)
+
+
+def assign_runs(runs: list, boxes: np.ndarray, k: float) -> tuple[list[list], int]:
+    """Tokens (char, x, content index) per detected line.
+
+    A run is one text-layer line piece (``textlayer.TextLine``), in content
+    order.  Each character goes to the smallest detected box that contains its
+    center (a space follows the character before it), so a run that spans two
+    table cells splits between them.  Inside a detected line, each run's part
+    keeps the PDF character order, and the parts are ordered by x.  ``boxes``
+    are pixels, ``k`` pixels per point.  Returns (tokens per detected line,
+    characters outside every box)."""
+    parts: list[dict] = [{} for _ in range(len(boxes))]  # line -> run idx -> tokens
+    lost = 0
+    if not len(boxes):
+        return [], sum(not c.isspace() for r in runs for c, _ in r.chars)
+    area = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1])
+    for idx, run in enumerate(runs):
+        j = None
+        for c, b in run.chars:
+            if not c.isspace():
+                cx, cy = (b[0] + b[2]) / 2 * k, (b[1] + b[3]) / 2 * k
+                inside = (
+                    (boxes[:, 0] <= cx)
+                    & (cx <= boxes[:, 2])
+                    & (boxes[:, 1] <= cy)
+                    & (cy <= boxes[:, 3])
+                )
+                if not inside.any():
+                    lost += 1
+                    j = None
+                    continue
+                j = int(np.flatnonzero(inside)[np.argmin(area[inside])])
+                parts[j].setdefault(idx, []).append((c, cx, idx))
+            elif j is not None:
+                prev = parts[j][idx][-1]
+                parts[j][idx].append((c, prev[1], idx))
+    toks: list[list] = []
+    for line in parts:
+        tk: list = []
+        rtl = right_to_left([t for part in line.values() for t in part])
+        order = (
+            sorted(line, key=lambda i: -max(t[1] for t in line[i]))
+            if rtl
+            else sorted(line, key=lambda i: min(t[1] for t in line[i]))
+        )
+        for idx in order:
+            if tk:
+                tk.append((" ", tk[-1][1], idx))  # parts of different runs
+            tk += line[idx]
+        toks.append(tk)
+    return toks, lost
+
+
+class Converter:
+    def __init__(
+        self,
+        ocr: OrtOCR,
+        dpi: float = 200.0,
+        mode: str = "auto",
+        pdf_order: bool = True,
+        image_ocr: bool = True,
+    ):
+        """mode: auto (text layer where sound, OCR elsewhere), ocr (always OCR,
+        never read the text layer), text (text layer even when the checks fail).
+        pdf_order: keep the PDF content order when it is coherent (False: the
+        order model always orders the lines).  image_ocr: OCR detected lines that
+        hold no text-layer characters (False: drop them)."""
+        if mode not in ("auto", "ocr", "text"):
+            raise ValueError(f"mode must be auto, ocr or text, not {mode!r}")
+        self.ocr, self.dpi, self.mode = ocr, dpi, mode
+        self.pdf_order, self.image_ocr = pdf_order, image_ocr
+
+    def page_scale(self, page) -> float:
+        """Pixels per point for this page: the set dpi, lowered for pages so
+        large that the render would pass MAX_PAGE_PIXELS (posters, plans)."""
+        w, h = page.get_size()
+        k = self.dpi / 72.0
+        return min(k, (MAX_PAGE_PIXELS / max(w * h, 1.0)) ** 0.5)
+
+    def pdf_page(self, pdf_path: str, doc, index: int) -> Page:
+        page = doc[index]
+        t: dict = {}
+        note = "mode=ocr"
+        if self.mode != "ocr":
+            t0 = time.perf_counter()
+            s = CHECK_DPI / 72.0
+            tl = read_text_layer(page, _render(page, s), s)
+            t["text_ms"] = 1000 * (time.perf_counter() - t0)
+            # A layer the recognizer cannot read beats OCR, unless its codes are junk.
+            unreadable = tl.reason != BROKEN_FONT_MAP and not readable(
+                self.ocr, tl.lines
+            )
+            if tl.lines and (tl.trusted or self.mode == "text" or unreadable):
+                return self._text_page(page, tl, t)
+            note = tl.reason
+            # A layer with a broken font map still places its glyphs: when most
+            # run upright, the page is upright (orient.onnx is not asked).
+            st = tl.stats
+            turn = not (
+                tl.reason == BROKEN_FONT_MAP and st["rotated"] < 0.5 * st["chars"]
+            )
+        else:
+            turn = True
+        t0 = time.perf_counter()
+        gray = _render(page, self.page_scale(page))
+        t["render_ms"] = 1000 * (time.perf_counter() - t0)
+        out = self.ocr(gray, turn)
+        out.timings = {**t, **out.timings}
+        out.timings["total_ms"] = sum(
+            v for k, v in out.timings.items() if k != "total_ms"
+        )
+        out.note = f"{note}; {out.note}"
+        return out
+
+    def _text_page(self, page, tl, t: dict) -> Page:
+        k = self.page_scale(page)
+        t0 = time.perf_counter()
+        gray = _render(page, k)
+        t["render_ms"] = 1000 * (time.perf_counter() - t0)
+        t0 = time.perf_counter()
+        boxes = self.ocr.detect(gray)
+        t["det_ms"] = 1000 * (time.perf_counter() - t0)
+        toks, lost = assign_runs(tl.lines, boxes[:, :4], k)
+        rec: list = [None] * len(boxes)
+        empty = []
+        for i, tk in enumerate(toks):
+            text = self.ocr._decode(tk) if tk else ""
+            if text:
+                rec[i] = (text, 1.0, tk)
+            else:
+                empty.append(i)
+        source = "text"
+        if empty and self.image_ocr and readable(self.ocr, tl.lines):
+            t0 = time.perf_counter()
+            for i, r in zip(empty, self.ocr.recognize(gray, boxes[empty])):
+                if r[0].strip():
+                    rec[i] = r
+                    source = "hybrid"
+            t["rec_ms"] = 1000 * (time.perf_counter() - t0)
+        if getattr(self.ocr, "math", None) is not None:
+            t0 = time.perf_counter()
+            self._read_math(gray, boxes, rec)
+            t["math_ms"] = 1000 * (time.perf_counter() - t0)
+        keep = [i for i, r in enumerate(rec) if r is not None]
+        out = self.ocr.assemble(
+            (gray.shape[1], gray.shape[0]),
+            boxes[keep].reshape(-1, boxes.shape[1]),
+            [rec[i] for i in keep],
+            t,
+            content_order=self.pdf_order,
+        )
+        out.source = source
+        out.note += f"; {lost} chars outside detected lines" if lost else ""
+        return out
+
+    def _read_math(self, gray, boxes, rec: list) -> None:
+        """Text-layer lines that hold math (the classifier, on their crops) are read
+        by MathRec instead: the layer has the symbols but not the LaTeX.  The line
+        keeps its place in the PDF content order (its first character's index)."""
+        from .line_mask import crop_lines
+
+        idx = [
+            i
+            for i, r in enumerate(rec)
+            if r is not None
+            and r[2]
+            and isinstance(r[2][0][0], str)
+            and len(r[2][0]) > 2
+        ]
+        if not idx:
+            return
+        crops = crop_lines(gray, boxes[idx, :4], self.ocr.height, None)
+        math = [i for i, f in zip(idx, self.ocr.math.flags(crops)) if f]
+        if not math:
+            return
+        from .math import MATH_MIN_CONF
+
+        for i, (text, conf) in zip(math, self.ocr.math.read(gray, boxes[math])):
+            # A reading without math, or not confident, leaves the layer's text.
+            if "$" in text and conf >= MATH_MIN_CONF:
+                first = min(tk[2] for tk in rec[i][2])
+                xc = float(boxes[i, 0] + boxes[i, 2]) / 2
+                rec[i] = (text, 1.0, [(text, xc, first)])
+
+    def convert(
+        self, path: str | Path, max_pages: int = 0, password: str | None = None
+    ):
+        """Yield (page index, Page) for a PDF or an image file (the file's bytes
+        decide which).  A page that fails yields an empty Page whose ``source``
+        is "error" and whose ``note`` says why; a file that cannot be opened
+        raises InputError."""
+        path = Path(path)
+        if not path.is_file():
+            raise InputError(f"{path}: no such file")
+        if not is_pdf(path):
+            for i, gray in enumerate(read_images(path)[: max_pages or None]):
+                yield i, self._safe(lambda: self.ocr(gray))
+            return
+        import pypdfium2 as pdfium
+
+        try:
+            doc = pdfium.PdfDocument(str(path), password=password)
+        except pdfium.PdfiumError as e:
+            locked = "password" in str(e).lower()
+            raise InputError(
+                f"{path}: password-protected PDF (pass password=, or --password)"
+                if locked
+                else f"{path}: cannot open the PDF ({e})"
+            ) from e
+        try:
+            n = len(doc) if not max_pages else min(len(doc), max_pages)
+            for i in range(n):
+                yield i, self._safe(lambda: self.pdf_page(str(path), doc, i))
+        finally:
+            doc.close()
+
+    @staticmethod
+    def _safe(read) -> Page:
+        try:
+            return read()
+        except Exception as e:  # noqa: BLE001  (one bad page must not end the document)
+            return Page(
+                [],
+                {"total_ms": 0.0},
+                markdown="",
+                source="error",
+                note=f"{type(e).__name__}: {e}",
+            )