OCR Compare: PaddleOCR vs PaddleOCR-VL with click-to-edit boxes

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/sample.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,51 @@
 ---
 title: OCR Compare
-emoji: 💻
-colorFrom: gray
-colorTo: indigo
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
 sdk: gradio
-sdk_version: 6.28.0
-python_version: '3.12'
+sdk_version: 5.50.0
 app_file: app.py
+python_version: "3.12"
+short_description: Classic PaddleOCR vs PaddleOCR-VL with click-to-edit boxes
+startup_duration_timeout: 1h
 pinned: false
+license: apache-2.0
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# OCR Compare: PaddleOCR vs PaddleOCR-VL
+
+Upload a scanned PDF or image and read the same page with two engines:
+
+| | Engine | Runs on |
+|---|---|---|
+| Left | **PaddleOCR** (PP-OCRv5 detection + recognition) | Space CPU |
+| Right | **PaddleOCR-VL** (0.9B vision-language model) | ZeroGPU |
+
+Both panels show the page with **one invisible box per detected line**. Click a
+box to see its text, correct it, and see what the other engine read at the same
+spot. Below the panels, a table lists every place where the two readings differ.
+
+## How to use
+
+1. Upload a PDF or image, or click **Load sample**.
+2. Click **Run both**.
+3. Click any line on either page.
+   - **Show all boxes** colours each box by agreement.
+   - **Show recognized text** draws the OCR text over the page.
+
+## PaddleOCR-VL box modes
+
+- **Same text lines as classic** (default). VL re-reads the exact lines that
+  classic PaddleOCR detected, so any difference is purely down to recognition.
+- **VL's own layout zones**. VL detects regions (text, tables, formulas) itself
+  and reads each whole region. This shows how VL handles a page on its own.
+  Tables come back as HTML and formulas as LaTeX.
+
+## Notes
+
+- Edits live only in your browser, so they are for comparison and nothing is
+  written back to a file.
+- Free ZeroGPU gives each visitor a few minutes of GPU per day. VL reads at most
+  150 lines per page. Untick **Run PaddleOCR-VL** to use classic only.
+- The first launch downloads both models, which takes a few minutes.

app.py

@@ -0,0 +1,526 @@
+"""
+OCR Compare -- classic PaddleOCR vs PaddleOCR-VL, side by side
+==============================================================
+
+  PDF / image page
+     ├─► classic PaddleOCR (PP-OCRv5 det + rec, CPU)   ─┐
+     └─► PaddleOCR-VL-0.9B (VLM, ZeroGPU)              ─┤  same {text, box} shape
+                                                        ▼
+         two page panels with invisible click-to-edit boxes + a diff table
+
+Everything runs on Hugging Face: PaddlePaddle on the Space CPU, the VLM on
+ZeroGPU. The box overlay and comparison live in overlay.py.
+
+The VLM loading code (version pins, kwarg shim, chunked GPU calls, prompt
+slicing) is carried over from the PaddleOCR-VL-Doc-Editor Space, where each of
+those was needed to make it run on ZeroGPU at all.
+"""
+
+try:
+    import spaces  # must be imported before torch / any CUDA-touching import
+except ImportError:  # local run without the HF `spaces` package
+
+    class spaces:  # noqa: N801
+        @staticmethod
+        def GPU(*args, **kwargs):
+            if args and callable(args[0]):
+                return args[0]
+            return lambda fn: fn
+
+
+import io
+import os
+import time
+import traceback
+
+import fitz  # PyMuPDF
+import gradio as gr
+import numpy as np
+from PIL import Image
+
+from overlay import (
+    CSS,
+    HEAD_JS,
+    TABLE_HEADERS,
+    compare,
+    image_to_data_uri,
+    overlay_html,
+    placeholder_html,
+    quad_to_box,
+    reading_order,
+    table_rows,
+)
+
+try:
+    import torch
+except ImportError:  # local UI testing without the VLM stack
+    torch = None
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+VL_MODEL = "PaddlePaddle/PaddleOCR-VL"
+CLASSIC_MODELS = {
+    "mobile (fast)": ("PP-OCRv5_mobile_det", "PP-OCRv5_mobile_rec"),
+    "server (accurate)": ("PP-OCRv5_server_det", "PP-OCRv5_server_rec"),
+}
+LAYOUT_MODELS = ["PP-DocLayoutV2", "PP-DocLayout_plus-L", "PP-DocLayout-L"]
+
+VL_SAME_LINES = "Same text lines as classic (fair comparison)"
+VL_LAYOUT = "VL's own layout zones (text / table / formula)"
+
+RENDER_DPI = 150
+MAX_SIDE = 2200          # cap the long side of a rendered page (px)
+MAX_PAGES = 30
+MAX_VL_ITEMS = 150       # bound GPU time per page
+SAMPLE_PATH = "examples/sample.png"
+
+# Free ZeroGPU caps each call's duration and each visitor's GPU-seconds per day,
+# so recognition runs in several short allocations rather than one long one.
+GPU_DURATION = 55
+CHUNK_LINES = 24         # short single-line crops
+CHUNK_ZONES = 10         # whole regions (can be long)
+
+PROMPTS = {"ocr": "OCR:", "table": "Table Recognition:",
+           "formula": "Formula Recognition:", "chart": "Chart Recognition:"}
+MAX_TOKENS = {"ocr": 1024, "table": 1536, "formula": 512, "chart": 1024}
+LABEL_TO_TASK = {"table": "table", "formula": "formula", "equation": "formula",
+                 "chart": "chart"}
+
+ON_ZEROGPU = bool(os.environ.get("SPACES_ZERO_GPU"))
+USE_CUDA = torch is not None and (ON_ZEROGPU or torch.cuda.is_available())
+DEVICE = "cuda" if USE_CUDA else "cpu"
+
+# ---------------------------------------------------------------------------
+# Models (lazy singletons)
+# ---------------------------------------------------------------------------
+_classic: dict = {}
+_layout = {"model": None}
+_vlm = {"model": None, "processor": None, "error": None}
+
+
+def _get_classic(size: str):
+    if size in _classic:
+        return _classic[size]
+    from paddleocr import PaddleOCR
+
+    det, rec = CLASSIC_MODELS[size]
+    print(f"[classic] loading {det} + {rec}", flush=True)
+    engine = PaddleOCR(
+        text_detection_model_name=det,
+        text_recognition_model_name=rec,
+        # Keep the page exactly as rendered so boxes line up with the image.
+        use_doc_orientation_classify=False,
+        use_doc_unwarping=False,
+        use_textline_orientation=False,
+    )
+    _classic[size] = engine
+    return engine
+
+
+def _get_layout():
+    if _layout["model"] is not None:
+        return _layout["model"]
+    from paddleocr import LayoutDetection
+
+    last = None
+    for name in LAYOUT_MODELS:
+        try:
+            _layout["model"] = LayoutDetection(model_name=name)
+            print("[layout] using", name, flush=True)
+            return _layout["model"]
+        except Exception as e:  # noqa: BLE001
+            last = e
+            print(f"[layout] {name} failed: {e}", flush=True)
+    raise RuntimeError(f"Could not load a layout model: {last}")
+
+
+def _patch_transformers_masking():
+    """PaddleOCR-VL's remote code calls create_causal_mask(inputs_embeds=...),
+    but transformers 4.55 names that parameter `input_embeds`. Rename it."""
+    import functools
+
+    try:
+        import transformers.masking_utils as mu
+    except Exception as e:  # noqa: BLE001
+        print("[patch] masking_utils unavailable:", e, flush=True)
+        return
+    orig = mu.create_causal_mask
+    if getattr(orig, "_paddleocr_shim", False):
+        return
+
+    @functools.wraps(orig)
+    def shim(*args, **kwargs):
+        if "inputs_embeds" in kwargs and "input_embeds" not in kwargs:
+            kwargs["input_embeds"] = kwargs.pop("inputs_embeds")
+        return orig(*args, **kwargs)
+
+    shim._paddleocr_shim = True
+    mu.create_causal_mask = shim
+
+
+def _load_vlm():
+    if _vlm["model"] is not None:
+        return
+    if torch is None:
+        raise RuntimeError("PyTorch is not installed, so PaddleOCR-VL is unavailable here.")
+    _patch_transformers_masking()
+    from transformers import AutoModelForCausalLM, AutoProcessor
+
+    print("[vlm] loading", VL_MODEL, flush=True)
+    model = AutoModelForCausalLM.from_pretrained(
+        VL_MODEL, trust_remote_code=True, torch_dtype=torch.bfloat16
+    ).eval()
+    if DEVICE == "cuda":
+        model = model.to("cuda")
+    _vlm["processor"] = AutoProcessor.from_pretrained(VL_MODEL, trust_remote_code=True)
+    _vlm["model"] = model
+    print("[vlm] ready", flush=True)
+
+
+# Load the VLM at import so ZeroGPU can pack the weights (ZeroGPU best practice).
+try:
+    _load_vlm()
+except Exception as e:  # noqa: BLE001
+    _vlm["error"] = str(e)
+    print("[vlm] eager load failed, will retry on first use:", e, flush=True)
+
+# ---------------------------------------------------------------------------
+# Pages
+# ---------------------------------------------------------------------------
+
+
+def _cap(img: Image.Image) -> Image.Image:
+    w, h = img.size
+    if max(w, h) > MAX_SIDE:
+        s = MAX_SIDE / max(w, h)
+        img = img.resize((int(w * s), int(h * s)), Image.LANCZOS)
+    return img
+
+
+def load_pages(path):
+    if not path:
+        return []
+    if os.path.splitext(path)[1].lower() == ".pdf":
+        doc = fitz.open(path)
+        zoom = RENDER_DPI / 72.0
+        pages = []
+        for i, page in enumerate(doc):
+            if i >= MAX_PAGES:
+                break
+            pix = page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), alpha=False)
+            pages.append(_cap(Image.open(io.BytesIO(pix.tobytes("png"))).convert("RGB")))
+        doc.close()
+        return pages
+    return [_cap(Image.open(path).convert("RGB"))]
+
+
+# ---------------------------------------------------------------------------
+# Engine 1: classic PaddleOCR (CPU)
+# ---------------------------------------------------------------------------
+
+
+def _result_dict(res):
+    """PaddleOCR 3.x results are dict-like; .json gives plain lists."""
+    try:
+        j = res.json
+        if isinstance(j, dict):
+            return j.get("res", j)
+    except Exception:  # noqa: BLE001
+        pass
+    return res
+
+
+def run_classic(img: Image.Image, size: str):
+    """-> (items, detected_boxes). detected_boxes includes lines the recognizer
+    returned empty, so the VL 'same lines' mode sees every detection."""
+    engine = _get_classic(size)
+    bgr = np.ascontiguousarray(np.array(img.convert("RGB"))[:, :, ::-1])  # Paddle expects BGR
+    res = _result_dict(list(engine.predict(bgr))[0])
+    texts = list(res.get("rec_texts") or [])
+    scores = list(res.get("rec_scores") or [])
+    polys = list(res.get("rec_polys") or [])
+    items = []
+    for i, text in enumerate(texts):
+        if i >= len(polys) or not str(text).strip():
+            continue
+        items.append({
+            "text": str(text).strip(),
+            "box": quad_to_box(polys[i]),
+            "conf": float(scores[i]) * 100 if i < len(scores) else None,
+            "label": "text line",
+        })
+    det = [quad_to_box(p) for p in (res.get("dt_polys") or polys)]
+    return reading_order(items), det
+
+
+# ---------------------------------------------------------------------------
+# Engine 2: PaddleOCR-VL (ZeroGPU)
+# ---------------------------------------------------------------------------
+
+
+def _vlm_one(crop: Image.Image, task: str, max_tokens: int) -> str:
+    model, processor = _vlm["model"], _vlm["processor"]
+    messages = [{"role": "user", "content": [
+        {"type": "image", "image": crop},
+        {"type": "text", "text": PROMPTS[task]},
+    ]}]
+    inputs = processor.apply_chat_template(
+        messages, tokenize=True, add_generation_prompt=True,
+        return_dict=True, return_tensors="pt",
+    ).to(model.device)
+    with torch.inference_mode():
+        out = model.generate(**inputs, max_new_tokens=max_tokens,
+                             do_sample=False, use_cache=True)
+    # Decode only the new tokens; otherwise the prompt is echoed back.
+    text = processor.batch_decode(out[:, inputs["input_ids"].shape[1]:],
+                                  skip_special_tokens=True)[0]
+    for marker in ("Assistant:", "assistant\n", "assistant:"):
+        if marker in text:
+            text = text.split(marker)[-1]
+    return text.strip()
+
+
+@spaces.GPU(duration=GPU_DURATION)
+def _recognize_chunk(img: Image.Image, chunk: list[dict]) -> list[dict]:
+    """One short GPU allocation. Returns the chunk (ZeroGPU runs this in a
+    separate process, so in-place mutation would not come back)."""
+    _load_vlm()
+    W, H = img.size
+    for z in chunk:
+        x1, y1, x2, y2 = z["box"]
+        if z.get("line"):
+            # a little vertical padding helps the recognizer on tight line boxes
+            pad = max(2, int((y2 - y1) * 0.15))
+            y1, y2 = max(0, y1 - pad), min(H, y2 + pad)
+            max_tokens = 128
+        else:
+            max_tokens = MAX_TOKENS.get(z["task"], 1024)
+        try:
+            z["text"] = _vlm_one(img.crop((x1, y1, x2, y2)), z["task"], max_tokens)
+        except Exception as e:  # noqa: BLE001
+            z["text"] = f"[recognition error: {e}]"
+    return chunk
+
+
+def _layout_zones(img: Image.Image) -> list[dict]:
+    out = _get_layout().predict(np.array(img), batch_size=1)
+    res = _result_dict(list(out)[0])
+    W, H = img.size
+    zones = []
+    for b in res.get("boxes", []):
+        coord = b.get("coordinate") or b.get("bbox") or b.get("box")
+        if coord is None:
+            continue
+        x1, y1, x2, y2 = [float(v) for v in coord[:4]]
+        x1, y1, x2, y2 = max(0, x1), max(0, y1), min(W, x2), min(H, y2)
+        if x2 - x1 < 3 or y2 - y1 < 3:
+            continue
+        label = str(b.get("label", "text")).lower().strip()
+        zones.append({"box": [int(x1), int(y1), int(x2), int(y2)], "label": label,
+                      "task": LABEL_TO_TASK.get(label, "ocr")})
+    return reading_order(zones)
+
+
+def run_vl(img: Image.Image, mode: str, line_boxes: list[list[int]]):
+    if mode == VL_SAME_LINES:
+        zones = [{"box": b, "label": "text line", "task": "ocr", "line": True}
+                 for b in line_boxes]
+        chunk = CHUNK_LINES
+    else:
+        zones = _layout_zones(img)
+        chunk = CHUNK_ZONES
+    zones = reading_order(zones)[:MAX_VL_ITEMS]
+    for i in range(0, len(zones), chunk):
+        zones[i : i + chunk] = _recognize_chunk(img, zones[i : i + chunk])
+    return [{"text": z.get("text", ""), "box": z["box"], "conf": None, "label": z["label"]}
+            for z in zones]
+
+
+# ---------------------------------------------------------------------------
+# Gradio callbacks
+# ---------------------------------------------------------------------------
+
+EMPTY_TABLE = gr.update(value=[], headers=TABLE_HEADERS)
+
+
+def on_upload(path):
+    pages = load_pages(path)
+    if not pages:
+        return (gr.update(choices=[], value=None), [], placeholder_html("Upload a PDF or image."),
+                placeholder_html("Upload a PDF or image."), [], EMPTY_TABLE, "")
+    choices = [(f"Page {i + 1}", i) for i in range(len(pages))]
+    msg = f"Loaded {len(pages)} page(s). Pick a page and click **Run both**."
+    ready = placeholder_html("Click “Run both” to OCR this page.")
+    return (gr.update(choices=choices, value=0), pages, ready, ready, [], EMPTY_TABLE, msg)
+
+
+def load_sample():
+    return on_upload(SAMPLE_PATH if os.path.exists(SAMPLE_PATH) else None)
+
+
+def _summary(t_classic, n_classic, t_vl, n_vl, stats, vl_mode, note=""):
+    lines = [f"**PaddleOCR (classic):** {n_classic} lines in {t_classic:.1f}s"]
+    if t_vl is not None:
+        mode = "same lines" if vl_mode == VL_SAME_LINES else "layout zones"
+        lines.append(f"**PaddleOCR-VL:** {n_vl} boxes ({mode}) in {t_vl:.1f}s")
+    if stats:
+        c = stats["counts"]
+        mean = f"{stats['mean_ratio'] * 100:.1f}%" if stats["mean_ratio"] is not None else "—"
+        lines.append(
+            f"**Agreement:** {c['same']} same · {c['minor']} minor · {c['differs']} differ · "
+            f"{c['only-classic']} only classic · {c['only-vl']} only VL "
+            f"(mean similarity {mean})"
+        )
+    if note:
+        lines.append(note)
+    return "  \n".join(lines)
+
+
+def run_both(page_idx, pages, classic_size, vl_mode, use_vl, only_diff):
+    if not pages:
+        raise gr.Error("Upload a document (or click “Load sample”) first.")
+    img = pages[int(page_idx or 0)]
+    uri = image_to_data_uri(img)  # encode once, reuse for both panels
+    waiting = placeholder_html("Waiting for classic PaddleOCR…")
+
+    yield (placeholder_html("Running classic PaddleOCR on CPU…"), waiting, [],
+           EMPTY_TABLE, "Running classic PaddleOCR…")
+
+    t0 = time.perf_counter()
+    try:
+        classic, det_boxes = run_classic(img, classic_size)
+    except Exception as e:  # noqa: BLE001
+        traceback.print_exc()
+        raise gr.Error(f"Classic PaddleOCR failed: {e}")
+    t_classic = time.perf_counter() - t0
+    classic_html = overlay_html(img, classic, "classic", uri)
+
+    if not use_vl:
+        yield (classic_html, placeholder_html("PaddleOCR-VL is switched off."), [],
+               EMPTY_TABLE, _summary(t_classic, len(classic), None, 0, None, vl_mode))
+        return
+
+    if vl_mode == VL_SAME_LINES and not det_boxes:
+        yield (classic_html, placeholder_html("Classic found no text lines to re-read."),
+               [], EMPTY_TABLE, _summary(t_classic, len(classic), None, 0, None, vl_mode))
+        return
+
+    yield (classic_html, placeholder_html("Running PaddleOCR-VL on ZeroGPU…"), [],
+           EMPTY_TABLE,
+           _summary(t_classic, len(classic), None, 0, None, vl_mode) + "  \nRunning PaddleOCR-VL…")
+
+    t0 = time.perf_counter()
+    try:
+        vl = run_vl(img, vl_mode, det_boxes)
+    except Exception as e:  # noqa: BLE001
+        traceback.print_exc()
+        yield (classic_html, placeholder_html(f"PaddleOCR-VL failed: {e}"), [], EMPTY_TABLE,
+               _summary(t_classic, len(classic), None, 0, None, vl_mode))
+        return
+    t_vl = time.perf_counter() - t0
+
+    rows, stats = compare(classic, vl)  # also tags boxes with their diff row
+    note = ""
+    if vl_mode == VL_SAME_LINES and len(det_boxes) > MAX_VL_ITEMS:
+        note = f"_VL re-read the first {MAX_VL_ITEMS} of {len(det_boxes)} lines (GPU budget)._"
+    yield (
+        overlay_html(img, classic, "classic", uri),
+        overlay_html(img, vl, "vl", uri),
+        rows,
+        gr.update(value=table_rows(rows, only_diff), headers=TABLE_HEADERS),
+        _summary(t_classic, len(classic), t_vl, len(vl), stats, vl_mode, note),
+    )
+
+
+def on_filter(rows, only_diff):
+    return gr.update(value=table_rows(rows or [], only_diff), headers=TABLE_HEADERS)
+
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+with gr.Blocks(title="OCR Compare", theme=gr.themes.Soft(), css=CSS, head=HEAD_JS) as demo:
+    pages_state = gr.State([])
+    rows_state = gr.State([])
+
+    gr.Markdown(
+        "# 🔍 OCR Compare — PaddleOCR vs PaddleOCR-VL\n"
+        "Upload a scan, run both engines, and compare them side by side. "
+        "**Every word or line is an invisible box — click one to see and edit its text.** "
+        "The other engine's reading for the same spot is shown under the editor."
+    )
+
+    with gr.Row():
+        file_in = gr.File(label="PDF or image", type="filepath",
+                          file_types=[".pdf", ".png", ".jpg", ".jpeg", ".bmp", ".webp", ".tif", ".tiff"],
+                          scale=3)
+        with gr.Column(scale=2):
+            page_sel = gr.Dropdown(label="Page", choices=[], interactive=True)
+            with gr.Row():
+                sample_btn = gr.Button("Load sample")
+                run_btn = gr.Button("Run both", variant="primary")
+
+    with gr.Accordion("Options", open=False):
+        with gr.Row():
+            classic_size = gr.Radio(list(CLASSIC_MODELS), value="mobile (fast)",
+                                    label="Classic PaddleOCR models")
+            vl_mode = gr.Radio([VL_SAME_LINES, VL_LAYOUT], value=VL_SAME_LINES,
+                               label="PaddleOCR-VL boxes",
+                               info="Same lines isolates recognition quality; layout "
+                                    "zones shows how VL would read the page on its own.")
+            use_vl = gr.Checkbox(value=True, label="Run PaddleOCR-VL (uses ZeroGPU quota)")
+
+    with gr.Row():
+        show_boxes = gr.Checkbox(value=False, label="Show all boxes (colored by agreement)")
+        show_text = gr.Checkbox(value=False, label="Show recognized text on the page")
+
+    status = gr.Markdown("Upload a PDF or image, or click **Load sample**.")
+
+    with gr.Row(equal_height=False):
+        with gr.Column():
+            gr.Markdown("### PaddleOCR (classic)")
+            classic_panel = gr.HTML(placeholder_html("No page yet."), padding=False)
+        with gr.Column():
+            gr.Markdown("### PaddleOCR-VL")
+            vl_panel = gr.HTML(placeholder_html("No page yet."), padding=False)
+
+    gr.Markdown(
+        "### Differences\n"
+        "Green = identical · yellow = minor · red = different · blue/purple = found by "
+        "one engine only. Row numbers match the “diff row” shown when you click a box."
+    )
+    only_diff = gr.Checkbox(value=True, label="Only show rows that differ")
+    diff_table = gr.Dataframe(headers=TABLE_HEADERS, value=[], wrap=True, interactive=False,
+                              column_widths=["6%", "14%", "8%", "36%", "36%"])
+
+    # --- wiring ---
+    upload_out = [page_sel, pages_state, classic_panel, vl_panel, rows_state, diff_table, status]
+    file_in.change(on_upload, inputs=file_in, outputs=upload_out)
+    sample_btn.click(load_sample, inputs=None, outputs=upload_out)
+
+    def _page_changed(_):
+        ready = placeholder_html("Click “Run both” to OCR this page.")
+        return ready, ready, [], EMPTY_TABLE
+
+    page_sel.change(_page_changed, inputs=page_sel,
+                    outputs=[classic_panel, vl_panel, rows_state, diff_table])
+    run_btn.click(
+        run_both,
+        inputs=[page_sel, pages_state, classic_size, vl_mode, use_vl, only_diff],
+        outputs=[classic_panel, vl_panel, rows_state, diff_table, status],
+    )
+    only_diff.change(on_filter, inputs=[rows_state, only_diff], outputs=diff_table)
+
+    # Display toggles are pure CSS classes on <body>; no server round trip.
+    show_boxes.change(None, inputs=show_boxes, outputs=None,
+                      js="(v) => { document.body.classList.toggle('ocrc-show-boxes', v); }")
+    show_text.change(None, inputs=show_text, outputs=None,
+                     js="(v) => { document.body.classList.toggle('ocrc-show-text', v); }")
+
+    demo.queue(default_concurrency_limit=1, max_size=16)
+
+
+if __name__ == "__main__":
+    demo.launch()

overlay.py

@@ -0,0 +1,405 @@
+"""Invisible click-to-edit boxes + engine comparison.
+
+Pure Python (no ML imports), so it can be tested without the models.
+
+Every OCR engine is normalised to the same item shape:
+
+    {"text": str, "box": [x1, y1, x2, y2], "conf": float | None, "label": str}
+
+where the box is in page-image pixels. From that one shape we build:
+
+  * overlay_html()  -- the page image with one invisible <div> per item,
+                       positioned in percentages so it stays aligned at any size;
+  * compare()       -- which classic lines fall inside which VL box, and how
+                       similar their text is.
+
+Gradio has no "clickable box over a word" component, so the boxes are plain
+HTML and the click-to-edit behaviour is a small script (HEAD_JS) injected into
+the page head: scripts placed inside gr.HTML are not executed.
+"""
+
+from __future__ import annotations
+
+import base64
+import html
+import io
+import re
+import unicodedata
+from difflib import SequenceMatcher
+
+# ---------------------------------------------------------------------------
+# Normalisation
+# ---------------------------------------------------------------------------
+
+
+def quad_to_box(poly) -> list[int]:
+    """Any polygon (4 corner points, or a flat list) -> tight upright [x1,y1,x2,y2]."""
+    pts = poly.tolist() if hasattr(poly, "tolist") else list(poly)
+    if pts and not isinstance(pts[0], (list, tuple)):
+        # flat [x1, y1, x2, y2, ...]
+        pts = [pts[i : i + 2] for i in range(0, len(pts) - 1, 2)]
+    xs = [float(p[0]) for p in pts]
+    ys = [float(p[1]) for p in pts]
+    return [int(min(xs)), int(min(ys)), int(round(max(xs))), int(round(max(ys)))]
+
+
+def reading_order(items: list[dict]) -> list[dict]:
+    return sorted(items, key=lambda it: (it["box"][1], it["box"][0]))
+
+
+_TAG = re.compile(r"<[^>]+>")
+_WS = re.compile(r"\s+")
+
+
+def norm_text(text: str) -> str:
+    """Text as compared: tags stripped (VL tables are HTML), case and spacing folded."""
+    t = unicodedata.normalize("NFKC", text or "")
+    t = _TAG.sub(" ", t)
+    return _WS.sub(" ", t).strip().lower()
+
+
+def _squash(text: str) -> str:
+    return norm_text(text).replace(" ", "")
+
+
+# ---------------------------------------------------------------------------
+# Comparison
+# ---------------------------------------------------------------------------
+
+STATUS_LABEL = {
+    "same": "✅ same",
+    "minor": "🟡 minor",
+    "differs": "🔴 differs",
+    "only-classic": "🔵 only classic",
+    "only-vl": "🟣 only VL",
+}
+
+
+def _contains(box, x, y, pad=2):
+    return box[0] - pad <= x <= box[2] + pad and box[1] - pad <= y <= box[3] + pad
+
+
+def _area(box):
+    return max(1, box[2] - box[0]) * max(1, box[3] - box[1])
+
+
+def compare(classic: list[dict], vl: list[dict]) -> tuple[list[dict], dict]:
+    """Match classic lines to VL boxes and score the text difference.
+
+    Each classic line is assigned to the smallest VL box containing its centre.
+    That works for both VL modes: with "same lines" every VL box *is* a classic
+    line; with "layout zones" a VL region collects the several lines inside it,
+    and their text is joined in reading order before comparing.
+
+    Mutates the items in place, setting ``grp`` (shared by matched boxes across
+    both panels), ``row`` (the diff-table row) and ``status``. Returns
+    (rows, stats); rows are dicts ready for the table.
+    """
+    for it in classic + vl:
+        it.pop("grp", None)
+        it.pop("row", None)
+        it["status"] = ""
+
+    members: dict[int, list[int]] = {vi: [] for vi in range(len(vl))}
+    unassigned: list[int] = []
+    for ci, c in enumerate(classic):
+        x = (c["box"][0] + c["box"][2]) / 2
+        y = (c["box"][1] + c["box"][3]) / 2
+        best, best_area = None, None
+        for vi, v in enumerate(vl):
+            if _contains(v["box"], x, y):
+                a = _area(v["box"])
+                if best is None or a < best_area:
+                    best, best_area = vi, a
+        if best is None:
+            unassigned.append(ci)
+        else:
+            members[best].append(ci)
+
+    raw_rows = []
+    for vi, v in enumerate(vl):
+        cis = sorted(members[vi], key=lambda i: (classic[i]["box"][1], classic[i]["box"][0]))
+        c_text = " ".join(classic[i]["text"] for i in cis).strip()
+        v_text = (v.get("text") or "").strip()
+        if not c_text and not v_text:
+            continue
+        if not cis:
+            status, ratio = "only-vl", 0.0
+        elif not v_text:
+            status, ratio = "only-classic", 0.0
+        else:
+            ratio = SequenceMatcher(None, norm_text(c_text), norm_text(v_text)).ratio()
+            if _squash(c_text) == _squash(v_text):
+                status, ratio = "same", 1.0
+            elif ratio >= 0.9:
+                status = "minor"
+            else:
+                status = "differs"
+        raw_rows.append(
+            {"y": v["box"][1], "x": v["box"][0], "classic": c_text, "vl": v_text,
+             "ratio": ratio, "status": status, "vl_idx": [vi], "classic_idx": cis}
+        )
+
+    for ci in unassigned:
+        c = classic[ci]
+        raw_rows.append(
+            {"y": c["box"][1], "x": c["box"][0], "classic": c["text"], "vl": "",
+             "ratio": 0.0, "status": "only-classic", "vl_idx": [], "classic_idx": [ci]}
+        )
+
+    raw_rows.sort(key=lambda r: (r["y"], r["x"]))
+    rows = []
+    for n, r in enumerate(raw_rows, start=1):
+        grp = f"g{n}"
+        for i in r["vl_idx"]:
+            vl[i].update(grp=grp, row=n, status=r["status"])
+        for i in r["classic_idx"]:
+            classic[i].update(grp=grp, row=n, status=r["status"])
+        rows.append({"n": n, **{k: r[k] for k in ("classic", "vl", "ratio", "status")}})
+
+    counts = {k: 0 for k in STATUS_LABEL}
+    for r in rows:
+        counts[r["status"]] += 1
+    both = [r for r in rows if r["status"] in ("same", "minor", "differs")]
+    stats = {
+        "rows": len(rows),
+        "counts": counts,
+        "compared": len(both),
+        "mean_ratio": (sum(r["ratio"] for r in both) / len(both)) if both else None,
+    }
+    return rows, stats
+
+
+def table_rows(rows: list[dict], only_differences: bool = False) -> list[list]:
+    out = []
+    for r in rows:
+        if only_differences and r["status"] == "same":
+            continue
+        match = f"{r['ratio'] * 100:.0f}%" if r["status"] in ("same", "minor", "differs") else "—"
+        out.append([r["n"], STATUS_LABEL[r["status"]], match, r["classic"], r["vl"]])
+    return out
+
+
+TABLE_HEADERS = ["#", "Status", "Match", "PaddleOCR (classic)", "PaddleOCR-VL"]
+
+
+# ---------------------------------------------------------------------------
+# Overlay HTML
+# ---------------------------------------------------------------------------
+
+
+def image_to_data_uri(img, max_side: int = 1600, quality: int = 85) -> str:
+    """Embed the page as a JPEG data URI (only the display copy is downscaled;
+    boxes are percentages, so they stay aligned regardless)."""
+    im = img.convert("RGB")
+    w, h = im.size
+    if max(w, h) > max_side:
+        s = max_side / max(w, h)
+        im = im.resize((int(w * s), int(h * s)))
+    buf = io.BytesIO()
+    im.save(buf, format="JPEG", quality=quality)
+    return "data:image/jpeg;base64," + base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def overlay_html(img, items: list[dict], engine: str, data_uri: str | None = None) -> str:
+    """The page image with one invisible, clickable box per item."""
+    W, H = img.size
+    uri = data_uri or image_to_data_uri(img)
+    boxes = []
+    for i, it in enumerate(items):
+        x1, y1, x2, y2 = it["box"]
+        x1, y1 = max(0, x1), max(0, y1)
+        x2, y2 = min(W, x2), min(H, y2)
+        if x2 <= x1 or y2 <= y1:
+            continue
+        left, top = 100 * x1 / W, 100 * y1 / H
+        width, height = 100 * (x2 - x1) / W, 100 * (y2 - y1) / H
+        # Font size in container-width units (the page div is an inline-size
+        # container), so the optional text layer scales with the image.
+        font = 100 * (y2 - y1) / W * 0.72
+        text = it.get("text") or ""
+        conf = it.get("conf")
+        attrs = {
+            "data-engine": engine,
+            "data-id": str(i),
+            "data-grp": it.get("grp", ""),
+            "data-row": str(it.get("row", "")),
+            "data-status": it.get("status", ""),
+            "data-label": it.get("label", ""),
+            "data-conf": "" if conf is None else f"{conf:.0f}",
+            "data-orig": text,
+            "data-text": text,
+            "title": text,
+        }
+        attr_s = " ".join(f'{k}="{html.escape(v, quote=True)}"' for k, v in attrs.items())
+        boxes.append(
+            f'<div class="ocrc-box" {attr_s} style="left:{left:.3f}%;top:{top:.3f}%;'
+            f'width:{width:.3f}%;height:{height:.3f}%;font-size:{font:.3f}cqw"></div>'
+        )
+    return (
+        f'<div class="ocrc-page" data-engine="{engine}">'
+        f'<img src="{uri}" alt="page" draggable="false">{"".join(boxes)}</div>'
+    )
+
+
+def placeholder_html(message: str) -> str:
+    return f'<div class="ocrc-empty">{html.escape(message)}</div>'
+
+
+# ---------------------------------------------------------------------------
+# CSS + click-to-edit script
+# ---------------------------------------------------------------------------
+
+CSS = """
+.ocrc-page{position:relative;width:100%;container-type:inline-size;line-height:0;
+  user-select:none;border:1px solid var(--border-color-primary);border-radius:6px;overflow:hidden}
+.ocrc-page img{width:100%;height:auto;display:block}
+.ocrc-empty{padding:48px 16px;text-align:center;color:var(--body-text-color-subdued);
+  border:1px dashed var(--border-color-primary);border-radius:6px}
+.ocrc-box{position:absolute;cursor:pointer;box-sizing:border-box;border-radius:2px;
+  min-width:4px;min-height:4px;line-height:1}
+.ocrc-box:hover{outline:2px solid #2563eb;background:rgba(37,99,235,.10)}
+.ocrc-box.active{outline:2px solid #2563eb;background:rgba(37,99,235,.18)}
+.ocrc-box.edited{outline:2px dashed #16a34a}
+body.ocrc-show-boxes .ocrc-box{outline:1px solid #94a3b8}
+body.ocrc-show-boxes .ocrc-box[data-status=same]{outline-color:#16a34a}
+body.ocrc-show-boxes .ocrc-box[data-status=minor]{outline-color:#ca8a04}
+body.ocrc-show-boxes .ocrc-box[data-status=differs]{outline:2px solid #dc2626;background:rgba(220,38,38,.08)}
+body.ocrc-show-boxes .ocrc-box[data-status=only-classic]{outline:2px solid #2563eb}
+body.ocrc-show-boxes .ocrc-box[data-status=only-vl]{outline:2px solid #9333ea}
+body.ocrc-show-text .ocrc-box::after{content:attr(data-text);position:absolute;inset:0;
+  background:rgba(255,255,255,.92);color:#111;font-family:Arial,sans-serif;
+  white-space:nowrap;overflow:hidden;padding:0 1px}
+.ocrc-editor{position:fixed;z-index:1000;width:340px;max-width:calc(100vw - 16px);
+  background:var(--background-fill-primary,#fff);color:var(--body-text-color,#111);
+  border:1px solid var(--border-color-primary,#ccc);border-radius:8px;
+  box-shadow:0 8px 28px rgba(0,0,0,.22);padding:10px 12px;font-size:13px;line-height:1.4}
+.ocrc-editor[hidden]{display:none}
+.ocrc-ed-head{font-weight:600;margin-bottom:4px}
+.ocrc-ed-meta{color:var(--body-text-color-subdued,#666);font-size:12px;margin-bottom:6px}
+.ocrc-editor textarea{width:100%;box-sizing:border-box;font:inherit;padding:6px;
+  border:1px solid var(--border-color-primary,#ccc);border-radius:6px;
+  background:var(--input-background-fill,#fff);color:inherit;resize:vertical}
+.ocrc-ed-other{margin-top:6px;font-size:12px;color:var(--body-text-color-subdued,#666)}
+.ocrc-ed-other b{color:var(--body-text-color,#111);font-weight:600}
+.ocrc-ed-btns{display:flex;gap:6px;margin-top:8px;justify-content:flex-end}
+.ocrc-ed-btns button{font:inherit;padding:4px 10px;border-radius:6px;cursor:pointer;
+  border:1px solid var(--border-color-primary,#ccc);background:transparent;color:inherit}
+.ocrc-ed-btns button[data-act=save]{background:#2563eb;border-color:#2563eb;color:#fff}
+"""
+
+HEAD_JS = r"""
+<script>
+(function () {
+  if (window.__ocrcInit) return;
+  window.__ocrcInit = true;
+
+  var NAMES = { classic: "PaddleOCR (classic)", vl: "PaddleOCR-VL" };
+  var ed = null, cur = null;
+
+  function editor() {
+    if (ed) return ed;
+    ed = document.createElement("div");
+    ed.className = "ocrc-editor";
+    ed.hidden = true;
+    ed.innerHTML =
+      '<div class="ocrc-ed-head"></div><div class="ocrc-ed-meta"></div>' +
+      '<textarea rows="3" spellcheck="false"></textarea>' +
+      '<div class="ocrc-ed-other"></div>' +
+      '<div class="ocrc-ed-btns"><button data-act="reset">Reset</button>' +
+      '<button data-act="close">Close</button><button data-act="save">Save</button></div>';
+    document.body.appendChild(ed);
+    ed.addEventListener("click", function (ev) {
+      var act = ev.target.getAttribute && ev.target.getAttribute("data-act");
+      if (!act) return;
+      if (act === "save") save();
+      else if (act === "reset") { ed.querySelector("textarea").value = cur.getAttribute("data-orig"); save(); }
+      else hide();
+    });
+    ed.querySelector("textarea").addEventListener("keydown", function (ev) {
+      if (ev.key === "Enter" && !ev.shiftKey) { ev.preventDefault(); save(); }
+      else if (ev.key === "Escape") { hide(); }
+    });
+    return ed;
+  }
+
+  function clearActive() {
+    document.querySelectorAll(".ocrc-box.active").forEach(function (b) { b.classList.remove("active"); });
+  }
+
+  function hide() {
+    if (ed) ed.hidden = true;
+    clearActive();
+    cur = null;
+  }
+
+  function save() {
+    if (!cur) return;
+    var v = ed.querySelector("textarea").value;
+    cur.setAttribute("data-text", v);
+    cur.setAttribute("title", v);
+    cur.classList.toggle("edited", v !== cur.getAttribute("data-orig"));
+    hide();
+  }
+
+  function open(box) {
+    var e = editor();
+    cur = box;
+    var engine = box.getAttribute("data-engine");
+    var row = box.getAttribute("data-row");
+    var conf = box.getAttribute("data-conf");
+    var label = box.getAttribute("data-label");
+    e.querySelector(".ocrc-ed-head").textContent = NAMES[engine] || engine;
+    var meta = [];
+    if (row) meta.push("diff row #" + row);
+    if (label) meta.push(label);
+    if (conf) meta.push("confidence " + conf + "%");
+    e.querySelector(".ocrc-ed-meta").textContent = meta.join(" · ");
+    e.querySelector("textarea").value = box.getAttribute("data-text");
+
+    // What did the other engine read in the same place?
+    var other = e.querySelector(".ocrc-ed-other");
+    var grp = box.getAttribute("data-grp");
+    other.textContent = "";
+    if (grp) {
+      var texts = [];
+      document.querySelectorAll('.ocrc-box[data-grp="' + grp + '"]').forEach(function (b) {
+        if (b.getAttribute("data-engine") !== engine) texts.push(b.getAttribute("data-text"));
+      });
+      var otherName = NAMES[engine === "vl" ? "classic" : "vl"];
+      var label2 = document.createElement("b");
+      label2.textContent = otherName + ": ";
+      other.appendChild(label2);
+      other.appendChild(document.createTextNode(texts.length ? texts.join(" ") : "(nothing here)"));
+    }
+
+    var r = box.getBoundingClientRect();
+    e.hidden = false;
+    var w = e.offsetWidth, h = e.offsetHeight;
+    var left = Math.min(Math.max(8, r.left), window.innerWidth - w - 8);
+    var top = r.bottom + 6;
+    if (top + h > window.innerHeight - 8) top = Math.max(8, r.top - h - 6);
+    e.style.left = left + "px";
+    e.style.top = top + "px";
+    var ta = e.querySelector("textarea");
+    ta.focus();
+    ta.select();
+  }
+
+  document.addEventListener("click", function (ev) {
+    if (ed && ed.contains(ev.target)) return;
+    var box = ev.target.closest && ev.target.closest(".ocrc-box");
+    if (!box) { if (ed && !ed.hidden) hide(); return; }
+    clearActive();
+    var grp = box.getAttribute("data-grp");
+    if (grp) {
+      document.querySelectorAll('.ocrc-box[data-grp="' + grp + '"]').forEach(function (b) { b.classList.add("active"); });
+    }
+    box.classList.add("active");
+    open(box);
+  });
+
+  window.addEventListener("scroll", function () { if (ed && !ed.hidden) hide(); }, true);
+})();
+</script>
+"""

requirements.txt

@@ -0,0 +1,22 @@
+# Same pins as the PaddleOCR-VL-Doc-Editor Space, where they are known to work
+# together on ZeroGPU. Do not bump them one at a time.
+
+# --- PaddleOCR-VL recognition (PyTorch, ZeroGPU) ---
+torch==2.10.0
+torchvision==0.25.0
+# The model's remote code was written for transformers 4.55.0; 4.57 renamed a
+# kwarg it passes and 5.x removed a helper it imports. app.py shims the rename.
+transformers==4.55.0
+accelerate>=1.5.0
+safetensors>=0.5.3
+sentencepiece>=0.2.0
+einops>=0.8.1
+
+# --- Classic PaddleOCR + layout detection (PaddlePaddle, CPU) ---
+# Plain paddleocr, NOT the [doc-parser] extra: that extra pulls a conflicting
+# transformers.
+paddlepaddle==3.2.1
+paddleocr>=3.4.0
+
+# --- PDF rendering ---
+PyMuPDF>=1.24.0