CLAUDE.md

Annotator Tool

Gradio annotation tool for facade frame detection. Deployed to HF Spaces as Infin8-AI/Annotation.

Files

• 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:

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:

# Add remote once
git remote add hf https://YOUR_HF_TOKEN@huggingface.co/spaces/Infin8-AI/Annotation

# Push this subdirectory as the Space root
git subtree push --prefix=tools/annotator hf main

Training loop

See scripts/build_dataset_from_events.py and scripts/train_facade_detector.py at the repo root.

# From repo root — after exporting events.jsonl from the Gradio tool
python scripts/build_dataset_from_events.py --events events.jsonl --pdf source.pdf
python scripts/train_facade_detector.py --version v2
cp models/yolo_facade_v2/best.pt tools/annotator/best.pt