feat(ai): tiled inference, machine API, and label JSON interchange in annotator

- detection.py: detect_tiled (640x640 windows, stride 480, cross-tile NMS
IoU 0.5); detect_rectangles auto-tiles images larger than one tile, fixing
zero-detection on full sheets; render_pdf_page + pt/px converters; model
resolution via FACADE_MODEL_REPO (HF Hub, revision-pinnable) with
FACADE_MODEL_PATH override; CUDA device auto-detect.
- app.py: all detect paths render at DETECTION_DPI=200 (Review tab scales
back to its 100-DPI canvas space); hidden machine API /detect_image and
/detect_page for gradio_client callers; Review tab exports/imports
canonical per-page label JSON (PDF-point coords, provenance, rejected
boxes) for the training pipeline.

Verified: 229-box parity with the validated tiled baseline on
testRollingPart5.pdf p1 via both API endpoints; label export/import
round-trips.

CLAUDE.md

@@ -4,12 +4,47 @@ Gradio annotation tool for facade frame detection. Deployed to HF Spaces as `Inf
 
 ## Files
 
-- `app.py` — Gradio UI (3 tabs: Detect, Review & Edit, Send to Backend)
-- `detection.py` — YOLO inference wrapper with OpenCV fallback
+- `app.py` — Gradio UI (3 tabs: Detect, Review & Edit, Send to Backend) + hidden machine API
+- `detection.py` — YOLO inference wrapper (tiled for full sheets) with OpenCV fallback
 - `requirements.txt` — Python deps for local dev and HF Spaces
 - `packages.txt` — System deps (poppler-utils) for HF Spaces
 - `best.pt` — YOLO11n weights (not in git — download from HF Hub or train locally)
 
+## Detection
+
+Full drawing sheets are detected with **tiled inference** (`detect_tiled`: 640×640 windows,
+stride 480, cross-tile NMS IoU 0.5) at **200 DPI** — whole-sheet single-pass inference finds
+nothing because mullions shrink below detectable size. `detect_rectangles()` tiles
+automatically for images larger than one tile. Constants live in `detection.py`
+(`TILE_SIZE`, `TILE_STRIDE`, `TILE_MERGE_IOU`, `DETECTION_DPI`) and must match the
+training dataset builder.
+
+Model resolution order: `FACADE_MODEL_PATH` (local file) → `FACADE_MODEL_REPO`
+(HF Hub, e.g. `Infin8-AI/estimat8-vm-v1`, pin with `FACADE_MODEL_REVISION`, auth with
+`HF_TOKEN`) → `best.pt` next to `detection.py`.
+
+## Machine API (for backends)
+
+Hidden endpoints exposed via the Gradio API, called with `gradio_client`:
+
+```python
+from gradio_client import Client, handle_file
+client = Client("Infin8-AI/Annotation", hf_token=...)   # or http://localhost:7860
+result = client.predict(handle_file("page.png"), 0.25, api_name="/detect_image")
+# -> {"width_px", "height_px", "model_version", "boxes": [{x1,y1,x2,y2,conf}]}
+```
+
+- `/detect_image (image_file, conf)` — primary: caller renders the PDF page and uploads one PNG.
+- `/detect_page (pdf_file, page_number, dpi, conf)` — testing/fallback; avoid for big PDFs
+  (gradio_client re-uploads the file every call).
+
+## Label JSON import/export (Review & Edit tab)
+
+`↓ Labels` exports every annotated page as canonical per-page label JSON (coordinates in
+**PDF points**, provenance + rejected boxes preserved), zipped. The Import field loads such
+JSONs back (audited → approved, machine bootstrap → pending, rejected → rejected). This is
+the audit interchange format consumed by `scripts/annotation/` at the repo root.
+
 ## Deploying to HF Spaces
 
 HF Spaces builds from `hf/main`. The Space expects files at the repo root, so use git subtree:

app.py

@@ -12,7 +12,15 @@ import cv2
 import gradio as gr
 import numpy as np
 import requests
-from detection import detect_rectangles, draw_detections, get_model_version
+from detection import (
+    DETECTION_DPI,
+    detect_rectangles,
+    draw_detections,
+    get_model_version,
+    pt_to_px,
+    px_to_pt,
+    render_pdf_page,
+)
 from PIL import Image
 
 # Fix gradio_client 5.9.1 crash when schema is a bool
@@ -100,7 +108,7 @@ def _load_image_for_detect(image_path, pdf_path, pdf_page):
             img = _pil_to_bgr(Image.open(image_path))
         return img
     if pdf_path and PDF_SUPPORT:
-        rgb = _render_pdf_page(pdf_path, pdf_page, dpi=150)
+        rgb = _render_pdf_page(pdf_path, pdf_page, dpi=DETECTION_DPI)
         return cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR) if rgb is not None else None
     return None
 
@@ -336,6 +344,177 @@ def run_detection(
     return annotated_rgb, payload, shapes, f"[{engine}] Detected {len(boxes)} panel(s)."
 
 
+# ---------------------------------------------------------------------------
+# Machine API endpoints (called by the backend via gradio_client)
+# ---------------------------------------------------------------------------
+def detect_image_api(image_file, conf=0.25):
+    """
+    Detect frames on a single page image (PNG/JPG). Primary backend entrypoint:
+    the caller renders the PDF page itself and uploads only the image.
+
+    Returns {"width_px", "height_px", "model_version", "boxes": [{x1,y1,x2,y2,conf}]}
+    with coordinates in the uploaded image's pixel space.
+    """
+    if image_file is None:
+        return {"error": "image file is required"}
+    path = image_file if isinstance(image_file, str) else image_file.name
+    img = cv2.imread(path)
+    if img is None:
+        try:
+            img = _pil_to_bgr(Image.open(path))
+        except Exception as exc:
+            return {"error": f"could not read image: {exc}"}
+    boxes = detect_rectangles(img, conf=float(conf))
+    h, w = img.shape[:2]
+    return {
+        "width_px": int(w),
+        "height_px": int(h),
+        "model_version": get_model_version(),
+        "boxes": boxes,
+    }
+
+
+def detect_page_api(pdf_file, page_number=1, dpi=DETECTION_DPI, conf=0.25):
+    """
+    Render one PDF page at the given DPI and detect frames on it.
+    Testing/fallback path — prefer detect_image_api to avoid re-uploading
+    large PDFs per page.
+    """
+    if pdf_file is None:
+        return {"error": "pdf file is required"}
+    path = pdf_file if isinstance(pdf_file, str) else pdf_file.name
+    rgb = render_pdf_page(path, int(page_number), dpi=int(dpi))
+    if rgb is None:
+        return {"error": f"could not render page {page_number}"}
+    bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    boxes = detect_rectangles(bgr, conf=float(conf))
+    h, w = rgb.shape[:2]
+    return {
+        "page_number": int(page_number),
+        "dpi": int(dpi),
+        "width_px": int(w),
+        "height_px": int(h),
+        "model_version": get_model_version(),
+        "boxes": boxes,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Per-page label JSON import/export (canonical ground-truth format)
+# ---------------------------------------------------------------------------
+_LABEL_DISPLAY_DPI = 100  # the Review tab canvas coordinate space
+
+
+def _source_tag(ann, model_version):
+    src = ann.get("source", "unknown")
+    if src == "yolo":
+        return f"yolo:{model_version}"
+    if src in ("human_added", "human"):
+        return "human:gradio"
+    return src
+
+
+def on_rv_export_labels(rv_pdf, rv_annotations):
+    """Export every page with annotations as canonical label JSONs (zipped).
+
+    Coordinates are converted from the 100-DPI canvas space to PDF points so
+    labels are DPI-independent and merge with other sources downstream.
+    """
+    if rv_pdf is None:
+        return None, "No PDF loaded."
+    pages = {p: anns for p, anns in (rv_annotations or {}).items() if anns}
+    if not pages:
+        return None, "No annotations to export."
+    stem = Path(rv_pdf).stem
+    mv = get_model_version()
+    tmp_dir = Path(tempfile.mkdtemp(prefix="labels_"))
+    written = []
+    for page, anns in sorted(pages.items()):
+        boxes, rejected = [], []
+        for ann in anns:
+            entry = {
+                "id": ann.get("uid") or str(uuid.uuid4()),
+                "x1_pt": round(px_to_pt(ann["x1"], _LABEL_DISPLAY_DPI), 3),
+                "y1_pt": round(px_to_pt(ann["y1"], _LABEL_DISPLAY_DPI), 3),
+                "x2_pt": round(px_to_pt(ann["x2"], _LABEL_DISPLAY_DPI), 3),
+                "y2_pt": round(px_to_pt(ann["y2"], _LABEL_DISPLAY_DPI), 3),
+                "source": _source_tag(ann, mv),
+                "conf": round(float(ann.get("conf", 1.0)), 4),
+                "history": ann.get("history", []),
+            }
+            (rejected if ann.get("status") == "rejected" else boxes).append(entry)
+        data = {
+            "doc": stem,
+            "pdf": Path(rv_pdf).name,
+            "page": int(page),
+            "page_type": "",
+            "audit_status": "audited",
+            "audited_at": datetime.now(UTC).isoformat(),
+            "boxes": boxes,
+            "rejected_boxes": rejected,
+        }
+        out = tmp_dir / f"p{int(page):03d}.json"
+        out.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        written.append(out)
+    zip_path = tmp_dir / f"{stem}_labels.zip"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for f in written:
+            zf.write(f, f.name)
+    return str(zip_path), f"Exported labels for {len(written)} page(s)."
+
+
+def on_rv_import_labels(label_files, rv_pdf, rv_page, rv_annotations):
+    """Import canonical label JSON(s) into the Review tab.
+
+    Boxes from audited/verified files arrive approved; machine bootstrap files
+    arrive pending; rejected_boxes arrive rejected (so they round-trip).
+    """
+    if not label_files:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "No label files provided."
+    rv_annotations = dict(rv_annotations or {})
+    loaded_pages = []
+    for lf in label_files:
+        path = lf if isinstance(lf, str) else lf.name
+        try:
+            data = json.loads(Path(path).read_text(encoding="utf-8"))
+        except Exception as exc:
+            return (
+                _build_canvas_json(None, rv_annotations.get(rv_page, [])),
+                _build_review_df(rv_annotations.get(rv_page, [])),
+                rv_annotations,
+                f"Failed to parse {Path(path).name}: {exc}",
+            )
+        page = int(data.get("page", 1))
+        default_status = "approved" if data.get("audit_status") in ("audited", "verified") else "pending"
+        anns = []
+        for status, group in ((default_status, data.get("boxes", [])), ("rejected", data.get("rejected_boxes", []))):
+            for box in group:
+                anns.append(
+                    {
+                        "id": len(anns),
+                        "uid": box.get("id"),
+                        "x1": pt_to_px(box["x1_pt"], _LABEL_DISPLAY_DPI),
+                        "y1": pt_to_px(box["y1_pt"], _LABEL_DISPLAY_DPI),
+                        "x2": pt_to_px(box["x2_pt"], _LABEL_DISPLAY_DPI),
+                        "y2": pt_to_px(box["y2_pt"], _LABEL_DISPLAY_DPI),
+                        "conf": float(box.get("conf", 1.0)),
+                        "status": status,
+                        "source": box.get("source", "unknown"),
+                        "history": box.get("history", []),
+                    }
+                )
+        rv_annotations[page] = anns
+        loaded_pages.append(page)
+    current = rv_annotations.get(rv_page, [])
+    img_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=100) if rv_pdf is not None and rv_page in loaded_pages else None
+    return (
+        _build_canvas_json(img_rgb, current),
+        _build_review_df(current),
+        rv_annotations,
+        f"Imported labels for page(s) {sorted(loaded_pages)}.",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Send to Backend handler
 # ---------------------------------------------------------------------------
@@ -494,18 +673,24 @@ def on_rv_detect(rv_pdf, rv_page, rv_annotations, rv_conf):
     img_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=100)
     if img_rgb is None:
         return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "Failed to render page."
-    img_bgr = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2BGR)
     from detection import _get_model
 
     using_yolo = _get_model() is not None
-    boxes = detect_rectangles(img_bgr, conf=float(rv_conf))
+    # Detect on a DETECTION_DPI render (the model's working resolution), then
+    # scale boxes back into the 100-DPI display space the canvas uses.
+    detect_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=DETECTION_DPI)
+    if detect_rgb is None:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "Failed to render page."
+    detect_bgr = cv2.cvtColor(detect_rgb, cv2.COLOR_RGB2BGR)
+    boxes = detect_rectangles(detect_bgr, conf=float(rv_conf))
+    scale = 100.0 / DETECTION_DPI
     annotations = [
         {
             "id": i,
-            "x1": b["x1"],
-            "y1": b["y1"],
-            "x2": b["x2"],
-            "y2": b["y2"],
+            "x1": b["x1"] * scale,
+            "y1": b["y1"] * scale,
+            "x2": b["x2"] * scale,
+            "y2": b["y2"] * scale,
             "conf": b["conf"],
             "status": "pending",
             "source": "yolo" if using_yolo else "opencv",
@@ -533,7 +718,7 @@ def on_rv_detect_all(rv_pdf, rv_page, rv_total, rv_annotations, rv_conf):
     using_yolo = _get_model() is not None
     all_anns = dict(rv_annotations)
     total_found = 0
-    detect_dpi = 72  # lower DPI = smaller images = much faster inference per page
+    detect_dpi = DETECTION_DPI  # the model's working resolution; lower DPI misses most frames
     try:
         doc = fitz.open(rv_pdf)
         mat = fitz.Matrix(detect_dpi / 72, detect_dpi / 72)
@@ -1184,7 +1369,13 @@ with gr.Blocks(title="Takeoff AI Annotator") as demo:
                     with gr.Row():
                         export_events_btn = gr.Button("↓ Events", scale=1)
                         export_dataset_btn = gr.Button("↓ Dataset", scale=1)
+                        export_labels_btn = gr.Button("↓ Labels", scale=1)
                     export_file_out = gr.File(label="Download", visible=True)
+                    import_labels_in = gr.File(
+                        label="Import label JSON(s)",
+                        file_count="multiple",
+                        file_types=[".json"],
+                    )
 
             gr.Markdown(
                 "`A` approve   `C` copy   `Del` delete   "
@@ -1318,6 +1509,16 @@ with gr.Blocks(title="Takeoff AI Annotator") as demo:
                 inputs=[rv_ledger_state, rv_pdf_state],
                 outputs=[export_file_out],
             )
+            export_labels_btn.click(
+                fn=on_rv_export_labels,
+                inputs=[rv_pdf_state, rv_annotations_state],
+                outputs=[export_file_out, rv_status],
+            )
+            import_labels_in.upload(
+                fn=on_rv_import_labels,
+                inputs=[import_labels_in, rv_pdf_state, rv_page_state, rv_annotations_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_status],
+            )
 
         # ------------------------------------------------------------------ #
         #  Tab 3: Send to Backend                                              #
@@ -1354,6 +1555,32 @@ with gr.Blocks(title="Takeoff AI Annotator") as demo:
                 outputs=[response_output],
             )
 
+    # ------------------------------------------------------------------ #
+    #  Machine API (hidden) — called by backends via gradio_client:        #
+    #    client.predict(handle_file(png), 0.25, api_name="/detect_image")  #
+    # ------------------------------------------------------------------ #
+    with gr.Row(visible=False):
+        api_image_in = gr.File(label="api_image", file_types=["image"])
+        api_pdf_in = gr.File(label="api_pdf", file_types=[".pdf"])
+        api_page_in = gr.Number(value=1, precision=0)
+        api_dpi_in = gr.Number(value=DETECTION_DPI, precision=0)
+        api_conf_in = gr.Number(value=0.25)
+        api_json_out = gr.JSON()
+        api_detect_image_btn = gr.Button("api detect_image")
+        api_detect_page_btn = gr.Button("api detect_page")
+    api_detect_image_btn.click(
+        fn=detect_image_api,
+        inputs=[api_image_in, api_conf_in],
+        outputs=[api_json_out],
+        api_name="detect_image",
+    )
+    api_detect_page_btn.click(
+        fn=detect_page_api,
+        inputs=[api_pdf_in, api_page_in, api_dpi_in, api_conf_in],
+        outputs=[api_json_out],
+        api_name="detect_page",
+    )
+
     gr.HTML(_CANVAS_JS)
 
 if __name__ == "__main__":

detection.py

@@ -1,11 +1,17 @@
 """
 YOLO-based facade frame detector for Takeoff AI Annotator.
 
-The model is loaded once at startup from the path set by the FACADE_MODEL_PATH
-environment variable (defaults to 'best.pt' in the same directory as this
-file). Pass a different path at launch time:
-
-    FACADE_MODEL_PATH=/path/to/best.pt python app.py
+Model resolution order:
+1. FACADE_MODEL_PATH — explicit local weights path.
+2. FACADE_MODEL_REPO — HF Hub model repo (e.g. 'Infin8-AI/estimat8-vm-v1');
+   downloads 'best.pt' at FACADE_MODEL_REVISION (default 'main') using
+   HF_TOKEN for private repos. Pinning a revision is the rollback mechanism.
+3. 'best.pt' next to this file.
+
+Full drawing sheets must be detected with tiled inference (the model is
+trained on 640x640 tiles; whole-sheet inference shrinks mullions below
+detectable size). detect_rectangles() routes through detect_tiled()
+automatically for images larger than one tile.
 """
 
 from __future__ import annotations
@@ -16,20 +22,59 @@ from pathlib import Path
 import cv2
 import numpy as np
 
+# Tiling geometry — must match the training dataset builder.
+TILE_SIZE = 640
+TILE_STRIDE = 480
+TILE_MERGE_IOU = 0.5
+DETECTION_DPI = 200
+
 # ---------------------------------------------------------------------------
 # Model loading
 # ---------------------------------------------------------------------------
 _MODEL = None
 _MODEL_PATH: str | None = None
+_DEVICE: str | None = None
+
+
+def _resolve_model_path() -> str:
+    explicit = os.environ.get("FACADE_MODEL_PATH")
+    if explicit:
+        return explicit
+
+    repo = os.environ.get("FACADE_MODEL_REPO")
+    if repo:
+        try:
+            from huggingface_hub import hf_hub_download
+
+            return hf_hub_download(
+                repo_id=repo,
+                filename="best.pt",
+                revision=os.environ.get("FACADE_MODEL_REVISION") or "main",
+                token=os.environ.get("HF_TOKEN") or None,
+            )
+        except Exception as exc:
+            print(f"[detection] WARNING: HF Hub download failed ({exc}). Trying local best.pt.")
+
+    return str(Path(__file__).parent / "best.pt")
+
+
+def get_device() -> str:
+    """'cuda' when available (local training boxes), else 'cpu' (HF Space)."""
+    global _DEVICE
+    if _DEVICE is None:
+        try:
+            import torch
+
+            _DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+        except Exception:
+            _DEVICE = "cpu"
+    return _DEVICE
 
 
 def _get_model():
     global _MODEL, _MODEL_PATH
 
-    path = os.environ.get(
-        "FACADE_MODEL_PATH",
-        str(Path(__file__).parent / "best.pt"),
-    )
+    path = _resolve_model_path()
 
     if _MODEL is None or path != _MODEL_PATH:
         try:
@@ -37,7 +82,7 @@ def _get_model():
 
             _MODEL = YOLO(path)
             _MODEL_PATH = path
-            print(f"[detection] Loaded YOLO model from: {path}")
+            print(f"[detection] Loaded YOLO model from: {path} (device={get_device()})")
         except Exception as exc:
             print(f"[detection] WARNING: Could not load YOLO model ({exc}). Falling back to OpenCV contour detection.")
             _MODEL = None
@@ -85,15 +130,127 @@ def detect_rectangles(
 
     Returns a list of dicts: {x1, y1, x2, y2, conf} in image pixel coordinates.
     conf is the model confidence (0-1). OpenCV fallback sets conf=1.0.
+
+    Images larger than one tile are detected via detect_tiled() — whole-sheet
+    single-pass inference finds nothing on full drawings.
     """
     model = _get_model()
 
     if model is not None:
+        h, w = image.shape[:2]
+        if max(h, w) > TILE_SIZE:
+            return detect_tiled(image, conf=conf, iou=iou)
         return _yolo_detect(model, image, conf=conf, iou=iou)
 
     return _cv_detect(image, min_area=min_area, max_area=max_area, epsilon_factor=epsilon_factor, threshold=threshold)
 
 
+def detect_tiled(
+    image: np.ndarray,
+    conf: float = 0.25,
+    iou: float = 0.45,
+    tile: int = TILE_SIZE,
+    stride: int = TILE_STRIDE,
+    nms_iou: float = TILE_MERGE_IOU,
+) -> list[dict]:
+    """
+    Sliding-window YOLO detection for full drawing sheets.
+
+    Runs the model on tile x tile windows with the given stride (windows are
+    added at the right/bottom edges so the whole sheet is covered), offsets
+    each tile's boxes back into sheet coordinates, then merges duplicates from
+    overlapping tiles with confidence-sorted greedy NMS at nms_iou.
+
+    Returns boxes sorted top-to-bottom, left-to-right.
+    """
+    model = _get_model()
+    if model is None:
+        return []
+
+    h, w = image.shape[:2]
+    ys = list(range(0, max(h - tile, 0) + 1, stride)) or [0]
+    xs = list(range(0, max(w - tile, 0) + 1, stride)) or [0]
+    if ys[-1] + tile < h:
+        ys.append(h - tile)
+    if xs[-1] + tile < w:
+        xs.append(w - tile)
+
+    boxes: list[dict] = []
+    for oy in ys:
+        for ox in xs:
+            window = image[oy : oy + tile, ox : ox + tile]
+            for b in _yolo_detect(model, window, conf=conf, iou=iou):
+                boxes.append(
+                    {
+                        "x1": b["x1"] + ox,
+                        "y1": b["y1"] + oy,
+                        "x2": b["x2"] + ox,
+                        "y2": b["y2"] + oy,
+                        "conf": b["conf"],
+                    }
+                )
+
+    boxes.sort(key=lambda b: -b["conf"])
+    kept: list[dict] = []
+    for b in boxes:
+        if all(_box_iou(b, k) < nms_iou for k in kept):
+            kept.append(b)
+
+    kept.sort(key=lambda b: (round(b["y1"], 2), round(b["x1"], 2)))
+    return kept
+
+
+def _box_iou(a: dict, b: dict) -> float:
+    ix1, iy1 = max(a["x1"], b["x1"]), max(a["y1"], b["y1"])
+    ix2, iy2 = min(a["x2"], b["x2"]), min(a["y2"], b["y2"])
+    inter = max(0.0, ix2 - ix1) * max(0.0, iy2 - iy1)
+    if inter == 0:
+        return 0.0
+    area_a = (a["x2"] - a["x1"]) * (a["y2"] - a["y1"])
+    area_b = (b["x2"] - b["x1"]) * (b["y2"] - b["y1"])
+    return inter / (area_a + area_b - inter)
+
+
+# ---------------------------------------------------------------------------
+# PDF rendering + coordinate conversion
+# ---------------------------------------------------------------------------
+
+
+def render_pdf_page(pdf_path: str, page_number: int, dpi: int = DETECTION_DPI) -> np.ndarray | None:
+    """
+    Render one PDF page (1-indexed) to an RGB numpy array at the given DPI.
+
+    Opens the document per call and releases it immediately — safe for very
+    large drawing sets (183 MB / 53 pages) because only one page's pixmap is
+    ever held in memory.
+    """
+    try:
+        import fitz  # PyMuPDF
+
+        doc = fitz.open(pdf_path)
+        try:
+            idx = max(0, min(page_number - 1, len(doc) - 1))
+            page = doc[idx]
+            mat = fitz.Matrix(dpi / 72, dpi / 72)
+            pix = page.get_pixmap(matrix=mat, colorspace=fitz.csRGB)
+            return np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, 3)
+        finally:
+            doc.close()
+    except Exception as exc:
+        print(f"[detection] PDF render error: {exc}")
+        return None
+
+
+def px_to_pt(value: float, dpi: int) -> float:
+    """Render-pixel -> PDF-point (canonical ML label space)."""
+    return value * 72.0 / dpi
+
+
+def pt_to_px(value: float, dpi: int) -> float:
+    """PDF-point -> render-pixel at the given DPI."""
+    return value * dpi / 72.0
+
+
 def _yolo_detect(
     model,
     image: np.ndarray,
@@ -105,7 +262,7 @@ def _yolo_detect(
         conf=conf,
         iou=iou,
         imgsz=640,
-        device="cpu",
+        device=get_device(),
         verbose=False,
     )
     boxes: list[dict] = []

requirements.txt

@@ -7,3 +7,4 @@ pymupdf>=1.23.0
 ultralytics>=8.3.0
 plotly>=5.18.0
 pandas>=2.0.0
+huggingface_hub>=0.26.0