paddleocr-hebrew 0.1.0__py3-none-any.whl

paddleocr_hebrew/__init__.py

@@ -0,0 +1,18 @@
+"""Hebrew OCR — PaddleOCR-based Hebrew recognizers + a runnable page pipeline.
+
+Public API:
+    from paddleocr_hebrew import HebrewOCR
+    ocr = HebrewOCR(models_dir="hebrew-ocr-models")   # a downloaded HF snapshot
+    result = ocr.read("page.png")                      # {lines, words, meta}
+"""
+from .pipeline import HebrewOCR, render_page
+from .plan_e_rec import PlanECascade
+from .heb_postprocess import (
+    post_process, fix_geresh_yod_text, fix_geresh_yod_token, reading_order,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "HebrewOCR", "render_page", "PlanECascade",
+    "post_process", "fix_geresh_yod_text", "fix_geresh_yod_token", "reading_order",
+]

paddleocr_hebrew/detect.py

@@ -0,0 +1,107 @@
+"""DBNet text detector (word-level or line-level) — ONNX inference.
+
+Carved from the production pipeline. Runs a mobile PPLCNetV3 DBNet ONNX, decodes
+the probability map into boxes via contour-finding + unclip. The SAME code drives
+both the word detector (word-level boxes) and the line detector; passing
+dilate_w/dilate_h > 0 bridges inter-word gaps so words on a baseline merge into a
+line blob (line-mode). The flagship pipeline uses word-level (dilate off).
+"""
+import cv2
+import numpy as np
+import pyclipper
+
+
+def _resize_for_det(img_bgr, max_side=960):
+    h, w = img_bgr.shape[:2]
+    s = max(h, w)
+    if s > max_side:
+        scale = max_side / s
+        img_r = cv2.resize(img_bgr, (int(w * scale), int(h * scale)))
+    else:
+        scale = 1.0
+        img_r = img_bgr
+    h, w = img_r.shape[:2]
+    nh = ((h + 31) // 32) * 32
+    nw = ((w + 31) // 32) * 32
+    pad = np.zeros((nh, nw, 3), dtype=np.uint8)
+    pad[:h, :w] = img_r
+    return pad, scale, h, w
+
+
+def _normalize_for_det(img_bgr):
+    img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB).astype(np.float32) / 255.0
+    mean = np.array([0.485, 0.456, 0.406])
+    std = np.array([0.229, 0.224, 0.225])
+    img_rgb = (img_rgb - mean) / std
+    return img_rgb.transpose(2, 0, 1)[None].astype(np.float32)
+
+
+def _polygon_area_perimeter(pts):
+    """Shoelace area + perimeter (no shapely dependency)."""
+    pts = np.asarray(pts, dtype=np.float32).reshape(-1, 2)
+    n = len(pts)
+    if n < 3:
+        return 0.0, 0.0
+    area = perim = 0.0
+    for i in range(n):
+        j = (i + 1) % n
+        area += pts[i, 0] * pts[j, 1] - pts[j, 0] * pts[i, 1]
+        perim += float(np.linalg.norm(pts[j] - pts[i]))
+    return abs(area) / 2.0, perim
+
+
+def _unclip_contour(cnt, ratio=1.3):
+    pts = cnt[:, 0]
+    area, perim = _polygon_area_perimeter(pts)
+    if area < 1:
+        return None
+    distance = area * ratio / max(perim, 1e-6)
+    pco = pyclipper.PyclipperOffset()
+    pco.AddPath(pts.tolist(), pyclipper.JT_ROUND, pyclipper.ET_CLOSEDPOLYGON)
+    expanded = pco.Execute(distance)
+    if not expanded:
+        return None
+    return np.array(expanded[0])
+
+
+def detect_words(img_bgr, det_sess, det_inp, thresh=0.40, unclip_ratio=1.3,
+                 min_area=3, min_wh=6, max_side=960, dilate_w=0, dilate_h=0):
+    """Return a list of (x1, y1, x2, y2) boxes in original image coordinates.
+
+    dilate_w/dilate_h > 0 -> line-mode (merge words on a baseline into a line).
+    """
+    pad, scale, valid_h, valid_w = _resize_for_det(img_bgr, max_side)
+    arr = _normalize_for_det(pad)
+    out = det_sess.run(None, {det_inp: arr})[0]
+    prob = out[0, 0, :valid_h, :valid_w]
+    mask = (prob > thresh).astype(np.uint8) * 255
+
+    if dilate_w > 0 or dilate_h > 0:
+        k = cv2.getStructuringElement(cv2.MORPH_RECT, (max(1, dilate_w), max(1, dilate_h)))
+        mask = cv2.dilate(mask, k, iterations=1)
+
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+    bboxes = []
+    for cnt in contours:
+        if cv2.contourArea(cnt) < min_area:
+            continue
+        unclipped = _unclip_contour(cnt, unclip_ratio)
+        if unclipped is None:
+            continue
+        x, y, w, h = cv2.boundingRect(unclipped)
+        if w < min_wh or h < min_wh:
+            continue
+        bboxes.append((int(x / scale), int(y / scale),
+                       int((x + w) / scale), int((y + h) / scale)))
+    return bboxes
+
+
+def crop_bbox(img_bgr, bbox, pad=0):
+    """Crop (x1,y1,x2,y2) from a BGR image, clamped to bounds, optional pad px."""
+    H, W = img_bgr.shape[:2]
+    x1, y1, x2, y2 = bbox
+    x1 = max(0, x1 - pad); y1 = max(0, y1 - pad)
+    x2 = min(W, x2 + pad); y2 = min(H, y2 + pad)
+    if x2 <= x1 or y2 <= y1:
+        return None
+    return img_bgr[y1:y2, x1:x2]

paddleocr_hebrew/heb_postprocess.py

@@ -0,0 +1,292 @@
+"""Hebrew OCR output post-processors.
+
+Consumer-side normalizations to apply to recognized text before display or
+downstream use (they do not change the model):
+
+  - normalize_quote_styles / normalize_gershayim: canonicalize apostrophe/quote
+    forms to ASCII ' and " (e.g. two adjacent apostrophes between Hebrew letters
+    -> a single gershayim ").
+  - fix_geresh_yod_*: repair the SVTRv2 residual defect where the ~1px abbreviation
+    marks geresh ' / gershayim " are read as a yod (yod resembles a thin mark),
+    e.g. עמ'->עמי, ס"ק->סיק. Conservative by design (over-correcting a real yod is
+    worse than a missed mark): a whole-token whitelist of yod-forms that are NOT
+    valid Hebrew words, plus numeric-gated page/section refs.
+  - reading_order: sort a word list into BiDi-friendly reading order (row cluster
+    + per-row RTL/LTR direction).
+
+NB Hebrew text must be stored/scored in LOGICAL order. Apply python-bidi
+get_display() only at the final rendering step (GUI/PDF), never before.
+"""
+import re
+
+HEB = r"֐-׿"
+
+
+def normalize_gershayim(s):
+    """Two adjacent ASCII apostrophes between Hebrew letters -> a single ASCII
+    double-quote (canonical gershayim). 'ס''מ' -> 'ס"מ'."""
+    s = re.sub(rf"([{HEB}])''([{HEB}])", r'\1"\2', s)
+    s = re.sub(rf"([{HEB}])''(?=[\s\W]|$)", r'\1"', s)
+    return s
+
+
+def normalize_quote_styles(s):
+    """Map curly quotes / Hebrew presentation quotes to canonical ASCII."""
+    s = s.replace("״", '"')   # U+05F4 Hebrew gershayim -> "
+    s = s.replace("׳", "'")   # U+05F3 Hebrew geresh -> '
+    s = s.replace("“", '"').replace("”", '"')
+    s = s.replace("‘", "'").replace("’", "'")
+    return s
+
+
+def post_process(s):
+    """Apply all canonical quote/gershayim post-processors to OCR output."""
+    s = normalize_quote_styles(s)
+    s = normalize_gershayim(s)
+    return s
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Geresh/gershayim <- yod repair (SVTRv2 residual defect)
+# ──────────────────────────────────────────────────────────────────────────
+_HEBSET = "֐-׿"
+
+# yod-form -> correct mark-form. Every KEY is a non-word (verified), so an exact
+# standalone-token match is safe. Values use canonical ASCII ' and ".
+GERESH_YOD_TOKENS = {
+    "עויד": "עו\"ד",    # lawyer  (עו"ד)
+    "פרופי": "פרופ'",   # professor (פרופ')
+    "וכוי": "וכו'",      # etc. (וכו')
+    "וגוי": "וגו'",      # and so forth (וגו')
+    "בגיץ": "בג\"ץ",    # High Court of Justice (בג"ץ)
+    "דויח": "דו\"ח",    # report (דו"ח)
+    "צהיל": "צה\"ל",    # IDF (צה"ל)
+    "ארהיב": "ארה\"ב",  # USA (ארה"ב)
+}
+
+_GY_TOKEN_RE = re.compile(
+    rf"(?<![{_HEBSET}])(" + "|".join(re.escape(k) for k in GERESH_YOD_TOKENS) + rf")(?![{_HEBSET}])"
+)
+
+# numeric-gated page/section references (yod-form IS a real word -> require a following number)
+_GY_PAGEREF = [
+    (re.compile(rf"(?<![{_HEBSET}])עמי(?=\s+\d)"), "עמ'"),   # page:  עמ' 131
+    (re.compile(rf"(?<![{_HEBSET}])מסי(?=\s+\d)"), "מס'"),   # number: מס' 5
+    (re.compile(rf"(?<![{_HEBSET}])סיק(?=\s+\d)"), "ס\"ק"),  # sub-section: ס"ק 3
+]
+
+
+def fix_geresh_yod_token(s):
+    """Whole-token geresh/gershayim<-yod repair (whitelist only; safe on isolated words)."""
+    if not s:
+        return s
+    return _GY_TOKEN_RE.sub(lambda m: GERESH_YOD_TOKENS[m.group(1)], s)
+
+
+def fix_geresh_yod_text(s):
+    """Full geresh/gershayim<-yod repair for TEXT with token order: whitelist tokens
+    PLUS numeric-gated page/section refs (עמ'/מס'/ס"ק NN). Use on joined line text."""
+    if not s:
+        return s
+    s = fix_geresh_yod_token(s)
+    for rx, rep in _GY_PAGEREF:
+        s = rx.sub(rep, s)
+    return s
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Reading-order assembly (operates on lists of {bbox, text, ...} dicts)
+# ──────────────────────────────────────────────────────────────────────────
+
+def _row_direction(row_words):
+    """Paragraph-level direction for a row by counting strong chars (default RTL)."""
+    rtl, ltr = 0, 0
+    for w in row_words:
+        for c in w.get("text", ""):
+            if 0x0590 <= ord(c) <= 0x05FF or 0x0600 <= ord(c) <= 0x077F:
+                rtl += 1
+            elif c.isalpha() and ord(c) < 0x0590:
+                ltr += 1
+    if rtl > ltr:
+        return "rtl"
+    if ltr > rtl:
+        return "ltr"
+    return "rtl"  # default to RTL for Hebrew documents
+
+
+def cluster_rows(words, row_tolerance=0.5):
+    """Group words into rows by y-center (row_tolerance x median word height).
+
+    Returns a list of rows, each a list of word dicts, top-to-bottom.
+    """
+    if not words:
+        return []
+    heights = sorted([w["bbox"][3] - w["bbox"][1] for w in words])
+    median_h = heights[len(heights) // 2] if heights else 30
+    tol = max(median_h * row_tolerance, 5)
+
+    indexed = [((w["bbox"][1] + w["bbox"][3]) / 2, w) for w in words]
+    indexed.sort(key=lambda x: x[0])
+    rows = []
+    current = [indexed[0]]
+    cur_y = indexed[0][0]
+    for y, w in indexed[1:]:
+        if abs(y - cur_y) <= tol:
+            current.append((y, w))
+            cur_y = sum(t[0] for t in current) / len(current)
+        else:
+            rows.append(current)
+            current = [(y, w)]
+            cur_y = y
+    rows.append(current)
+    return [[t[1] for t in row] for row in rows]
+
+
+def _word_script(text):
+    """'R' for a word with any Hebrew/Arabic letter (prefixed tokens such as ו-Twitter or ה-CEO are
+    Hebrew words), 'L' for a word with Latin letters only, 'N' for numbers and punctuation."""
+    if any(0x0590 <= ord(c) <= 0x05FF or 0x0600 <= ord(c) <= 0x077F for c in text):
+        return "R"
+    if any(c.isalpha() and ord(c) < 0x0590 for c in text):
+        return "L"
+    return "N"
+
+
+def _is_number(text):
+    return any(c.isdigit() for c in text) and not any(c.isalpha() for c in text)
+
+
+# Numbers next to an embedded run are ambiguous on the page ("Windows 11" and "50 USD" look alike).
+EDGE_NUMBERS_JOIN_RUN = False
+
+
+def _restore_runs(visual_words, direction):
+    """Put each embedded run of the other script back in its own order.
+
+    `visual_words` are in visual order for `direction` (rightmost first for "rtl"). A run starts and
+    ends on a word of the other script; numbers and punctuation between its words belong to it;
+    punctuation at its edges stays with the surrounding text, and numbers there join it only when
+    EDGE_NUMBERS_JOIN_RUN is set.
+    """
+    base, other = ("R", "L") if direction == "rtl" else ("L", "R")
+    out, seg = [], []
+
+    def flush():
+        idx = [i for i, (_, s) in enumerate(seg) if s == other]
+        if idx:
+            a, b = idx[0], idx[-1]
+            if EDGE_NUMBERS_JOIN_RUN:
+                while a > 0 and _is_number(seg[a - 1][0].get("text", "")):
+                    a -= 1
+                while b < len(seg) - 1 and _is_number(seg[b + 1][0].get("text", "")):
+                    b += 1
+            out.extend(w for w, _ in seg[:a])
+            out.extend(w for w, _ in reversed(seg[a:b + 1]))
+            out.extend(w for w, _ in seg[b + 1:])
+        else:
+            out.extend(w for w, _ in seg)
+        seg.clear()
+
+    for w in visual_words:
+        s = _word_script(w.get("text", ""))
+        if s == base:
+            flush()
+            out.append(w)
+        else:
+            seg.append((w, s))
+    flush()
+    return out
+
+
+def order_row(row_words, direction=None):
+    """Order one row's words in logical (reading) order.
+
+    direction=None decides from the row: any Hebrew word makes it right to left (rightmost word first),
+    Latin without Hebrew makes it left to right, and a row of numbers only stays right to left as in a
+    Hebrew document. One guard: a row that starts and ends with Latin-only words and has at least
+    3x more Latin than Hebrew letters stays left to right (an English line where one short word was
+    misread as Hebrew, e.g. "in" read as "מו"). Inside the row, each embedded run of the other script
+    keeps its own order, so an English phrase in a Hebrew line reads "אוניברסיטת חיפה University of
+    Haifa", not reversed. Pass "ltr"/"rtl" to force the paragraph direction (see row_directions).
+    """
+    cx = lambda w: (w["bbox"][0] + w["bbox"][2]) / 2  # noqa: E731
+    if direction is None:
+        scripts = [_word_script(w.get("text", "")) for w in sorted(row_words, key=cx)]
+        if "R" in scripts:
+            strong = [s for s in scripts if s != "N"]
+            heb = sum(1 for w in row_words for c in w.get("text", "")
+                      if 0x0590 <= ord(c) <= 0x05FF or 0x0600 <= ord(c) <= 0x077F)
+            lat = sum(1 for w in row_words for c in w.get("text", "") if c.isalpha() and ord(c) < 0x0590)
+            english_line = strong[0] == "L" and strong[-1] == "L" and lat >= 3 * heb
+            direction = "ltr" if english_line else "rtl"
+        else:
+            direction = "ltr" if "L" in scripts else "rtl"
+    visual = sorted(row_words, key=(lambda w: -cx(w)) if direction == "rtl" else cx)
+    return _restore_runs(visual, direction)
+
+
+def row_directions(rows, window=2, latin_ratio=4.0, min_rows=3):
+    """Paragraph direction per row (rows as returned by cluster_rows), or None to let order_row decide.
+
+    Safeguard for English text that quotes Hebrew: a row with Hebrew in it is "ltr" when the row and its
+    neighbours (window rows above and below) hold at least `min_rows` rows with letters and
+    `latin_ratio` times more Latin than Hebrew letters. Every other row gets None.
+    """
+    counts = []
+    for row in rows:
+        h = l = 0
+        for w in row:
+            for c in w.get("text", ""):
+                if 0x0590 <= ord(c) <= 0x05FF or 0x0600 <= ord(c) <= 0x077F:
+                    h += 1
+                elif c.isalpha() and ord(c) < 0x0590:
+                    l += 1
+        counts.append((h, l))
+    out = []
+    for i, (h_i, _) in enumerate(counts):
+        near = counts[max(0, i - window): i + window + 1]
+        h = sum(c[0] for c in near)
+        l = sum(c[1] for c in near)
+        lettered = sum(1 for c in near if c[0] or c[1])
+        out.append("ltr" if h_i and lettered >= min_rows and l >= latin_ratio * h else None)
+    return out
+
+
+def reading_order(words, row_tolerance=0.5):
+    """Sort words into a flat BiDi-friendly reading order (rows top-to-bottom,
+    each row in logical order; see order_row)."""
+    rows = cluster_rows(words, row_tolerance)
+    out = []
+    for row, direction in zip(rows, row_directions(rows)):
+        out.extend(order_row(row, direction))
+    return out
+
+
+if __name__ == "__main__":
+    tests = [
+        ("ס''מ", "ס\"מ"), ("ס\"מ", "ס\"מ"), ("בע''מ", "בע\"מ"),
+        ("פרופ'", "פרופ'"), ("הבורסה”", "הבורסה\""),
+    ]
+    for inp, expected in tests:
+        got = post_process(inp)
+        ok = "OK " if got == expected else "XX "
+        print(f"  {ok} {inp!r:14s} -> {got!r:14s} (want {expected!r})")
+    # word order: (word, x1, x2) as the boxes sit on the page -> expected logical text
+    order_tests = [
+        ([("University", 400, 580), ("of Haifa", 600, 780), ("2024", 800, 880), ("חיפה", 900, 980),
+          ("אוניברסיטת", 1000, 1100)], ["אוניברסיטת חיפה 2024 University of Haifa",
+                                        "אוניברסיטת חיפה University of Haifa 2024"]),
+        ([("היום", 0, 120), ("הודיעה", 150, 280), ("Microsoft", 300, 440), ("Corporation", 460, 600)],
+         ["Microsoft Corporation הודיעה היום"]),
+        ([("ו-Twitter", 0, 140), ("Facebook", 160, 300), ("הודיעו", 320, 450)], ["הודיעו Facebook ו-Twitter"]),
+        ([("החדשות", 0, 120), ("–", 130, 150), ("mako", 160, 240)], ["mako – החדשות"]),
+        ([("אורתופדיה", 150, 380), ("7.1.4", 400, 480)], ["7.1.4 אורתופדיה"]),
+        ([("Total", 0, 80), ("due", 90, 140)], ["Total due"]),
+        ([("from", 0, 60), ("his", 70, 110), ("post", 120, 170), ("מו", 180, 200), ("accordance", 210, 330),
+          ("with", 340, 390)], ["from his post מו accordance with"]),
+    ]
+    for ws, expected in order_tests:
+        row = [{"bbox": [x1, 100, x2, 130], "text": t} for t, x1, x2 in ws]
+        got = " ".join(w["text"] for w in order_row(row))
+        want = expected[1] if EDGE_NUMBERS_JOIN_RUN and len(expected) > 1 else expected[0]
+        print(f"  {'OK ' if got == want else 'XX '} {got}   (want {want})")

paddleocr_hebrew/pipeline.py

@@ -0,0 +1,166 @@
+"""Hebrew OCR pipeline — word-DET + SVTRv2 Plan-E cascade (the flagship page path).
+
+image/PDF -> word detector (mobile DBNet) -> crops -> Plan-E cascade recognizer
+(SVTRv2 CTC fast path + script-gated NRTR fallback) -> reading-order assembly ->
+Hebrew post-processing (gershayim canon + geresh<-yod repair).
+
+This is the page pipeline the benchmark uses: word-level detection + single-pass
+recognition (the recognizer reads each word crop once; no sliding window). On the
+71-page GCV-anchored eval it scores 7.56% page-CER, ahead of a Hebrew-finetuned
+line detector (10.36%) and Tesseract (14.20%).
+
+Output is a dict of recognized LINES (logical Unicode order — apply python-bidi
+get_display() only when rendering) plus the underlying word boxes.
+
+    from paddleocr_hebrew import HebrewOCR
+    ocr = HebrewOCR(models_dir="hebrew-ocr-models")   # a downloaded HF snapshot
+    result = ocr.read("page.png")
+    for line in result["lines"]:
+        print(line["text"])
+"""
+import os
+
+import cv2
+import numpy as np
+
+from .detect import crop_bbox, detect_words
+from .heb_postprocess import cluster_rows, fix_geresh_yod_text, order_row, row_directions, post_process
+from .plan_e_rec import PlanECascade
+
+
+def render_page(path, dpi=150, page=1):
+    """Load an image, or render one PDF page, to a BGR numpy array."""
+    ext = os.path.splitext(path)[1].lower()
+    if ext == ".pdf":
+        # pypdfium2 (Apache-2.0 / BSD-3-Clause), not PyMuPDF (AGPL), so the package stays
+        # usable wherever Apache-2.0 is
+        import pypdfium2 as pdfium
+        pdf = pdfium.PdfDocument(path)
+        try:
+            if not 1 <= page <= len(pdf):
+                raise RuntimeError(f"{path} has {len(pdf)} pages; page {page} requested")
+            pil = pdf[page - 1].render(scale=dpi / 72).to_pil().convert("RGB")
+        finally:
+            pdf.close()
+        return cv2.cvtColor(np.asarray(pil), cv2.COLOR_RGB2BGR)
+    if ext in (".jpg", ".jpeg", ".png", ".tif", ".tiff", ".bmp"):
+        img = cv2.imread(path)
+        if img is None:
+            raise RuntimeError(f"Cannot open image: {path}")
+        return img
+    raise RuntimeError(f"Unsupported input: {path}")
+
+
+class HebrewOCR:
+    """End-to-end Hebrew page OCR: DBNet detector + Plan-E cascade recognizer.
+
+    Two pipelines, same code + same recognizer, only the detector differs:
+
+      HebrewOCR.word(models_dir)   # DEFAULT, flagship. Word-level detection.
+                                   # Faster AND more accurate at page level
+                                   # (7.56% page-CER, 4.95 s/page on Jetson).
+      HebrewOCR.line(models_dir)   # Line-level detection. Slower + a bit less
+                                   # accurate on clean pages (10.36%, 6.33 s), but
+                                   # WINS on degraded scans / dense hard layouts
+                                   # where word detection over-fragments.
+
+    Or construct directly and pass your own `det` ONNX + thresholds.
+    """
+
+    @classmethod
+    def word(cls, models_dir, **kw):
+        """Flagship word-level pipeline (the default; recommended)."""
+        kw.setdefault("det", "word-det/det.onnx")
+        kw.setdefault("det_thresh", 0.40)
+        kw.setdefault("det_unclip", 1.3)
+        return cls(models_dir, **kw)
+
+    @classmethod
+    def line(cls, models_dir, **kw):
+        """Line-level pipeline — for degraded scans / hard layouts (see class doc)."""
+        kw.setdefault("det", "line-det/det.onnx")
+        kw.setdefault("det_thresh", 0.30)
+        kw.setdefault("det_unclip", 1.8)
+        return cls(models_dir, **kw)
+
+    def __init__(self, models_dir, *,
+                 det="word-det/det.onnx",
+                 ctc="server-svtrv2/ctc.onnx",
+                 nrtr_encoder="server-svtrv2/nrtr-encoder.onnx",
+                 nrtr_decstep="server-svtrv2/nrtr-decstep.onnx",
+                 charset="charset_v2f.txt",
+                 providers=None,
+                 det_thresh=0.40, det_unclip=1.3, det_max_side=1280,
+                 dilate_w=0, dilate_h=0,
+                 conf_threshold=0.50,
+                 gershayim=True, geresh_yod=True):
+        import onnxruntime as ort
+        prov = providers or ['CUDAExecutionProvider', 'CPUExecutionProvider']
+
+        def mp(rel):
+            return rel if os.path.isabs(rel) else os.path.join(models_dir, rel)
+
+        self.det_sess = ort.InferenceSession(mp(det), providers=prov)
+        self.det_inp = self.det_sess.get_inputs()[0].name
+        self.rec = PlanECascade(mp(ctc), mp(nrtr_encoder), mp(nrtr_decstep),
+                                mp(charset), conf_threshold=conf_threshold,
+                                providers=prov)
+        self.det_thresh = det_thresh
+        self.det_unclip = det_unclip
+        self.det_max_side = det_max_side
+        self.dilate_w = dilate_w
+        self.dilate_h = dilate_h
+        self.gershayim = gershayim
+        self.geresh_yod = geresh_yod
+
+    def read(self, path, *, page=1, dpi=150, rec_mode="cascade"):
+        """Recognize one image or PDF page. Returns {lines, words, meta}."""
+        img = render_page(path, dpi=dpi, page=page)
+        return self.read_array(img, rec_mode=rec_mode)
+
+    def read_array(self, img_bgr, *, rec_mode="cascade"):
+        """Recognize an in-memory BGR image array."""
+        bboxes = detect_words(img_bgr, self.det_sess, self.det_inp,
+                              thresh=self.det_thresh, unclip_ratio=self.det_unclip,
+                              max_side=self.det_max_side,
+                              dilate_w=self.dilate_w, dilate_h=self.dilate_h)
+        crops, keep = [], []
+        for bb in bboxes:
+            c = crop_bbox(img_bgr, bb)
+            if c is not None:
+                crops.append(c)
+                keep.append(bb)
+        preds = self.rec.rec_crops(crops, mode=rec_mode)
+
+        words = []
+        for bb, txt in zip(keep, preds):
+            if self.gershayim:
+                txt = post_process(txt)
+            if txt.strip():
+                words.append({"bbox": list(bb), "text": txt})
+
+        # assemble lines in reading order (logical Unicode order)
+        lines = []
+        rows = cluster_rows(words)
+        for row, direction in zip(rows, row_directions(rows)):
+            ordered = order_row(row, direction)
+            text = " ".join(w["text"] for w in ordered).strip()
+            if self.geresh_yod:
+                text = fix_geresh_yod_text(text)
+            if not text:
+                continue
+            xs1 = min(w["bbox"][0] for w in ordered); ys1 = min(w["bbox"][1] for w in ordered)
+            xs2 = max(w["bbox"][2] for w in ordered); ys2 = max(w["bbox"][3] for w in ordered)
+            lines.append({"text": text, "bbox": [xs1, ys1, xs2, ys2],
+                          "n_words": len(ordered)})
+
+        return {
+            "lines": lines,
+            "words": words,
+            "meta": {
+                "n_words": len(words),
+                "n_lines": len(lines),
+                "n_nrtr_fallback": self.rec.last_n_fallback,
+                "rec_mode": rec_mode,
+            },
+        }