1st version

.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+models

README.md

@@ -12,3 +12,63 @@ short_description: Minimal feature-detection with Classical and Deep Learning
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# FeatureLab Mini — Classic & DL Detectors
+
+FeatureLab now exposes a production-friendly layout: FastAPI serves the detector runtime over HTTP/WebSocket while Gradio rides on top for internal demos.
+
+## Runtime Overview
+```
+FastAPI (/v1/detect/*)  <-- shared numpy/CV runtime -->  Gradio UI (/)
+```
+- **Classical path**: Canny, Harris, Probabilistic Hough, contour-based ellipse fitting.
+- **Deep path**: ONNX models (HED, SuperPoint, SOLD2, etc.) auto-loaded from `./models`.
+- **Responses**: base64 PNG overlays, rich feature metadata, timings, model info.
+
+## Run locally
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python app.py  # FastAPI + Gradio on http://localhost:7860
+```
+
+## HTTP API
+- `POST /v1/detect/edges|corners|lines|ellipses`
+- Body:
+  ```json
+  {
+    "image": "<base64 png/jpeg>",
+    "params": { "canny_low": 50, "canny_high": 150, "...": "..." },
+    "mode": "classical|dl|both",
+    "compare": false,
+    "dl_model": "hed.onnx"
+  }
+  ```
+- Response:
+  ```json
+  {
+    "overlay": "<png base64>",
+    "overlays": { "classical": "...", "dl": "..." },
+    "features": { "classical": {...}, "dl": {...} },
+    "timings": { "classical": 7.2, "dl": 18.5, "total": 25.7 },
+    "fps_estimate": 38.9,
+    "model": { "name": "opencv-classical", "version": "4.10.0" },
+    "models": { "classical": {...}, "dl": {...} }
+  }
+  ```
+- Multipart uploads: `POST /v1/detect/<detector>/upload` with `file`, optional `params` (JSON string), `mode`, `compare`, `dl_model`.
+
+## WebSocket API
+- Connect to `/v1/detect/stream`.
+- Send JSON payloads with the same shape as HTTP.
+- Receive the detection response for each frame — suitable for webcam or live sources.
+
+## Gradio Demo
+- Still bundled for quick experiments (webcam capture, parameter sliders).
+- Fully decoupled: the UI calls the same runtime, so React/Tauri front-ends can swap in later without touching detector code.
+
+## Deploying
+- Hugging Face Spaces (Gradio) still works — FastAPI runs inside the Space process.
+- For container/desktop targets, run `uvicorn app:app` or embed the FastAPI router into your existing service.
+
+GPU/Core ML acceleration (ONNX) is optional; drop models into `./models` to enable DL paths. Continuous upgrades toward Core ML / PyTorch backends can reuse the same API surface.

app.py

@@ -0,0 +1,15 @@
+"""
+Thin entrypoint for local runs.
+Imports the FastAPI app from the backend package and runs it.
+"""
+
+import os
+import uvicorn
+
+from backend.py.app.main import app  # noqa: F401
+
+
+if __name__ == "__main__":
+    host = os.getenv("HOST", "127.0.0.1")
+    port = int(os.getenv("PORT", "7862"))
+    uvicorn.run("app:app", host=host, port=port, reload=False)

backend/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/api/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/api/v1/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/api/v1/detect.py

@@ -0,0 +1,262 @@
+import json
+from typing import Any, Dict, Optional
+
+import cv2
+import numpy as np
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile, WebSocket, WebSocketDisconnect
+
+from ...models.schemas import DetectionParams, DetectionRequest, DetectionResponse
+from ...services.runtime_adapter import DetectionResult, run_detection
+from ...utils.image_io import decode_base64_image, encode_png_base64
+
+
+router = APIRouter(prefix="/v1/detect", tags=["detection"])
+
+DETECTOR_KEYS: Dict[str, str] = {
+    "edges": "Edges (Canny)",
+    "corners": "Corners (Harris)",
+    "lines": "Lines (Hough)",
+    "ellipses": "Ellipses (Contours + fitEllipse)",
+}
+
+ALLOWED_MODES = {"classical", "dl", "both"}
+
+
+def _detector_label(key: str) -> str:
+    if key not in DETECTOR_KEYS:
+        raise HTTPException(status_code=404, detail=f"Unknown detector '{key}'.")
+    return DETECTOR_KEYS[key]
+
+
+def _resolve_mode(mode: str, compare: bool) -> str:
+    if compare:
+        return "both"
+    if mode not in ALLOWED_MODES:
+        return "classical"
+    return mode
+
+
+def _choose_primary(mode: str, overlays: Dict[str, str]) -> Optional[str]:
+    if mode == "dl" and "dl" in overlays:
+        return "dl"
+    if mode == "classical" and "classical" in overlays:
+        return "classical"
+    if mode == "both":
+        if "classical" in overlays:
+            return "classical"
+        if "dl" in overlays:
+            return "dl"
+    return next(iter(overlays.keys()), None)
+
+
+def _format_result(result: DetectionResult, mode: str) -> DetectionResponse:
+    overlays_encoded: Dict[str, Optional[str]] = {}
+    for path, image in result.overlays.items():
+        if image is None:
+            overlays_encoded[path] = None
+            continue
+        overlays_encoded[path] = encode_png_base64(image)
+
+    primary = _choose_primary(mode, {k: v for k, v in overlays_encoded.items() if v})
+    model_info = result.models.get(primary or "classical", result.models.get("classical", {}))
+
+    return DetectionResponse(
+        overlay=overlays_encoded.get(primary) if primary else None,
+        overlays=overlays_encoded,
+        features=result.features,
+        timings=result.timings_ms,
+        fps_estimate=result.fps_estimate,
+        model=model_info,
+        models=result.models,
+    )
+
+
+def _json_params(params: Optional[DetectionParams]) -> Optional[Dict[str, Any]]:
+    if params is None:
+        return None
+    return params.dict(exclude_none=True)
+
+
+@router.post("/edges", response_model=DetectionResponse)
+async def detect_edges(payload: DetectionRequest):
+    try:
+        image = decode_base64_image(payload.image)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid image payload: {exc}")
+    runtime_mode = _resolve_mode(payload.mode, payload.compare)
+    result = run_detection(
+        image,
+        _detector_label("edges"),
+        params=_json_params(payload.params),
+        mode=runtime_mode,
+        dl_choice=payload.dl_model.strip() if payload.dl_model else None,
+    )
+    return _format_result(result, runtime_mode)
+
+
+@router.post("/corners", response_model=DetectionResponse)
+async def detect_corners(payload: DetectionRequest):
+    try:
+        image = decode_base64_image(payload.image)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid image payload: {exc}")
+    runtime_mode = _resolve_mode(payload.mode, payload.compare)
+    result = run_detection(
+        image,
+        _detector_label("corners"),
+        params=_json_params(payload.params),
+        mode=runtime_mode,
+        dl_choice=payload.dl_model.strip() if payload.dl_model else None,
+    )
+    return _format_result(result, runtime_mode)
+
+
+@router.post("/lines", response_model=DetectionResponse)
+async def detect_lines(payload: DetectionRequest):
+    try:
+        image = decode_base64_image(payload.image)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid image payload: {exc}")
+    runtime_mode = _resolve_mode(payload.mode, payload.compare)
+    result = run_detection(
+        image,
+        _detector_label("lines"),
+        params=_json_params(payload.params),
+        mode=runtime_mode,
+        dl_choice=payload.dl_model.strip() if payload.dl_model else None,
+    )
+    return _format_result(result, runtime_mode)
+
+
+@router.post("/ellipses", response_model=DetectionResponse)
+async def detect_ellipses(payload: DetectionRequest):
+    try:
+        image = decode_base64_image(payload.image)
+    except Exception as exc:
+        raise HTTPException(status_code=400, detail=f"Invalid image payload: {exc}")
+    runtime_mode = _resolve_mode(payload.mode, payload.compare)
+    result = run_detection(
+        image,
+        _detector_label("ellipses"),
+        params=_json_params(payload.params),
+        mode=runtime_mode,
+        dl_choice=payload.dl_model.strip() if payload.dl_model else None,
+    )
+    return _format_result(result, runtime_mode)
+
+
+async def _handle_upload(
+    detector_key: str,
+    file: UploadFile,
+    params: Optional[str],
+    mode: str,
+    compare: bool,
+    dl_model: Optional[str],
+) -> DetectionResponse:
+    content = await file.read()
+    array = np.frombuffer(content, dtype=np.uint8)
+    decoded = cv2.imdecode(array, cv2.IMREAD_COLOR)
+    if decoded is None:
+        raise HTTPException(status_code=400, detail="Unable to decode uploaded image.")
+    image = cv2.cvtColor(decoded, cv2.COLOR_BGR2RGB)
+    params_dict: Optional[Dict[str, Any]] = None
+    if params:
+        try:
+            params_dict = json.loads(params)
+            if not isinstance(params_dict, dict):
+                raise ValueError("params JSON must decode to an object.")
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=f"Invalid params: {exc}")
+    runtime_mode = _resolve_mode(mode, compare)
+    result = run_detection(
+        image,
+        _detector_label(detector_key),
+        params=params_dict,
+        mode=runtime_mode,
+        dl_choice=dl_model.strip() if dl_model else None,
+    )
+    return _format_result(result, runtime_mode)
+
+
+def _upload_endpoint(detector_key: str):
+    async def endpoint(
+        file: UploadFile = File(...),
+        params: Optional[str] = Form(None),
+        mode: str = Form("classical"),
+        compare: bool = Form(False),
+        dl_model: Optional[str] = Form(None),
+    ):
+        return await _handle_upload(detector_key, file, params, mode, compare, dl_model)
+
+    return endpoint
+
+
+router.add_api_route(
+    "/edges/upload", _upload_endpoint("edges"), methods=["POST"], response_model=DetectionResponse
+)
+router.add_api_route(
+    "/corners/upload", _upload_endpoint("corners"), methods=["POST"], response_model=DetectionResponse
+)
+router.add_api_route(
+    "/lines/upload", _upload_endpoint("lines"), methods=["POST"], response_model=DetectionResponse
+)
+router.add_api_route(
+    "/ellipses/upload", _upload_endpoint("ellipses"), methods=["POST"], response_model=DetectionResponse
+)
+
+
+@router.websocket("/stream")
+async def detection_stream(websocket: WebSocket):
+    await websocket.accept()
+    await websocket.send_json({"ready": True})
+    try:
+        while True:
+            message = await websocket.receive_text()
+            try:
+                payload = json.loads(message)
+            except json.JSONDecodeError:
+                await websocket.send_json({"error": "Invalid JSON payload."})
+                continue
+
+            detector_key = payload.get("detector")
+            if detector_key not in DETECTOR_KEYS:
+                await websocket.send_json({"error": "Unknown detector key."})
+                continue
+
+            image_b64 = payload.get("image")
+            if not image_b64:
+                await websocket.send_json({"error": "Missing 'image' field."})
+                continue
+
+            try:
+                image = decode_base64_image(image_b64)
+            except Exception as exc:
+                await websocket.send_json({"error": f"Invalid image payload: {exc}"})
+                continue
+
+            params = payload.get("params")
+            if params is not None and not isinstance(params, dict):
+                await websocket.send_json({"error": "'params' must be an object."})
+                continue
+
+            mode = payload.get("mode", "classical")
+            compare = bool(payload.get("compare", False))
+            dl_model = payload.get("dl_model") or payload.get("model")
+
+            runtime_mode = _resolve_mode(mode, compare)
+            try:
+                result = run_detection(
+                    image,
+                    _detector_label(detector_key),
+                    params=params,
+                    mode=runtime_mode,
+                    dl_choice=dl_model.strip() if dl_model else None,
+                )
+            except Exception as exc:  # pragma: no cover
+                await websocket.send_json({"error": str(exc)})
+                continue
+
+            await websocket.send_json(_format_result(result, runtime_mode).dict())
+    except WebSocketDisconnect:
+        return
+

backend/py/app/gradio_demo/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/gradio_demo/ui.py

@@ -0,0 +1,168 @@
+from typing import Any, Dict, Optional, Tuple
+
+import gradio as gr
+import numpy as np
+
+from ..inference.dl import DL_MODELS
+from ..services.runtime_adapter import DEFAULT_PARAMS, run_detection
+
+
+TITLE = "FeatureLab Mini — Classic vs DL"
+DESC = (
+    "Minimal feature-detection demo with Classical and Deep Learning paths, now backed by a shared runtime."
+)
+
+
+def _gradio_runtime(
+    image: Optional[np.ndarray],
+    detector: str,
+    compare: bool,
+    dl_choice: str,
+    canny_low: int,
+    canny_high: int,
+    harris_k: float,
+    harris_block: int,
+    harris_ksize: int,
+    hough_thresh: int,
+    hough_min_len: int,
+    hough_max_gap: int,
+    ellipse_min_area: int,
+    max_ellipses: int,
+) -> Tuple[Optional[np.ndarray], Optional[np.ndarray], Dict[str, Any]]:
+    if image is None:
+        return None, None, {"info": "No image provided."}
+
+    params = {
+        "canny_low": int(canny_low),
+        "canny_high": int(canny_high),
+        "harris_k": float(harris_k),
+        "harris_block": int(harris_block),
+        "harris_ksize": int(harris_ksize),
+        "hough_thresh": int(hough_thresh),
+        "hough_min_len": int(hough_min_len),
+        "hough_max_gap": int(hough_max_gap),
+        "ellipse_min_area": int(ellipse_min_area),
+        "max_ellipses": int(max_ellipses),
+    }
+
+    mode = "both" if compare else "classical"
+    dl_model = dl_choice.strip() or None
+    result = run_detection(image, detector, params=params, mode=mode, dl_choice=dl_model)
+
+    classical_img = result.overlays.get("classical")
+    dl_img = result.overlays.get("dl")
+    meta = {
+        "timings_ms": result.timings_ms,
+        "fps_estimate": result.fps_estimate,
+        "features": result.features,
+        "models": result.models,
+    }
+    return classical_img, dl_img, meta
+
+
+def build_demo() -> gr.Blocks:
+    defaults = dict(DEFAULT_PARAMS)
+
+    with gr.Blocks(title=TITLE) as demo:
+        gr.Markdown(f"# {TITLE}\n{DESC}")
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                in_img = gr.Image(
+                    type="numpy",
+                    label="Input image (Upload / Clipboard / Webcam)",
+                )
+
+                detector = gr.Radio(
+                    [
+                        "Edges (Canny)",
+                        "Corners (Harris)",
+                        "Lines (Hough)",
+                        "Ellipses (Contours + fitEllipse)",
+                    ],
+                    value="Edges (Canny)",
+                    label="Detector",
+                )
+
+                compare = gr.Checkbox(value=True, label="Compare Classical vs DL side-by-side")
+                dl_choice = gr.Textbox(value="", label="DL model filename (optional, in ./models)")
+
+                with gr.Accordion("Parameters", open=False):
+                    canny_low = gr.Slider(0, 255, value=defaults["canny_low"], step=1, label="Canny low threshold")
+                    canny_high = gr.Slider(0, 255, value=defaults["canny_high"], step=1, label="Canny high threshold")
+                    harris_k = gr.Slider(0.02, 0.15, value=defaults["harris_k"], step=0.005, label="Harris k")
+                    harris_block = gr.Slider(2, 8, value=defaults["harris_block"], step=1, label="Harris blockSize")
+                    harris_ksize = gr.Slider(3, 7, value=defaults["harris_ksize"], step=2, label="Harris ksize (odd)")
+                    hough_thresh = gr.Slider(1, 200, value=defaults["hough_thresh"], step=1, label="Hough threshold")
+                    hough_min_len = gr.Slider(1, 300, value=defaults["hough_min_len"], step=1, label="Hough minLineLength")
+                    hough_max_gap = gr.Slider(0, 50, value=defaults["hough_max_gap"], step=1, label="Hough maxLineGap")
+                    ellipse_min_area = gr.Slider(10, 50000, value=defaults["ellipse_min_area"], step=10, label="Ellipse min area (px^2)")
+                    max_ellipses = gr.Slider(1, 20, value=defaults["max_ellipses"], step=1, label="Max ellipses")
+
+                with gr.Accordion("DL Models (how to enable)", open=False):
+                    dl_lines = "\n".join(
+                        f"- **{det}**: {', '.join(models) if models else 'n/a'}" for det, models in DL_MODELS.items()
+                    )
+                    gr.Markdown(
+                        f"""
+                        Place ONNX files in `./models` (create the folder next to the repo root).
+
+                        **Expected filenames (defaults):**
+                        {dl_lines}
+
+                        Backends use onnxruntime with CoreML (if available) or CPU provider.
+                        """
+                    )
+
+                run_btn = gr.Button("Run", variant="primary")
+
+            with gr.Column(scale=1):
+                with gr.Row():
+                    out_img_classical = gr.Image(type="numpy", label="Classical Overlay", interactive=False)
+                    out_img_dl = gr.Image(type="numpy", label="DL Overlay", interactive=False)
+                meta_json = gr.JSON(label="Timings / Metadata")
+
+        run_btn.click(
+            fn=_gradio_runtime,
+            inputs=[
+                in_img,
+                detector,
+                compare,
+                dl_choice,
+                canny_low,
+                canny_high,
+                harris_k,
+                harris_block,
+                harris_ksize,
+                hough_thresh,
+                hough_min_len,
+                hough_max_gap,
+                ellipse_min_area,
+                max_ellipses,
+            ],
+            outputs=[out_img_classical, out_img_dl, meta_json],
+        )
+
+        # Auto-run whenever a new image is captured or uploaded
+        in_img.change(
+            fn=_gradio_runtime,
+            inputs=[
+                in_img,
+                detector,
+                compare,
+                dl_choice,
+                canny_low,
+                canny_high,
+                harris_k,
+                harris_block,
+                harris_ksize,
+                hough_thresh,
+                hough_min_len,
+                hough_max_gap,
+                ellipse_min_area,
+                max_ellipses,
+            ],
+            outputs=[out_img_classical, out_img_dl, meta_json],
+        )
+
+    return demo

backend/py/app/inference/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/inference/classical.py

@@ -0,0 +1,87 @@
+from typing import Any, Dict, Tuple
+
+import cv2
+import numpy as np
+
+from .common import to_bgr, to_rgb
+
+
+def detect_classical(
+    image: np.ndarray,
+    detector: str,
+    canny_low: int,
+    canny_high: int,
+    harris_k: float,
+    harris_block: int,
+    harris_ksize: int,
+    hough_thresh: int,
+    hough_min_len: int,
+    hough_max_gap: int,
+    ellipse_min_area: int,
+    max_ellipses: int,
+) -> Tuple[np.ndarray, Dict[str, Any]]:
+    bgr = to_bgr(image)
+    gray = cv2.cvtColor(bgr, cv2.COLOR_BGR2GRAY)
+
+    overlay = bgr.copy()
+    meta: Dict[str, Any] = {"path": "classical"}
+
+    if detector == "Edges (Canny)":
+        edges = cv2.Canny(gray, canny_low, canny_high, L2gradient=True)
+        overlay[edges > 0] = (0, 255, 0)
+        meta["num_edge_pixels"] = int(np.count_nonzero(edges))
+
+    elif detector == "Corners (Harris)":
+        gray32 = np.float32(gray)
+        dst = cv2.cornerHarris(gray32, blockSize=harris_block, ksize=harris_ksize, k=harris_k)
+        dst = cv2.dilate(dst, None)
+        thresh = 0.01 * dst.max() if dst.max() > 0 else 0.0
+        corners = np.argwhere(dst > thresh)
+        for (y, x) in corners:
+            cv2.circle(overlay, (int(x), int(y)), 2, (0, 255, 255), -1)
+        meta["num_corners"] = int(len(corners))
+
+    elif detector == "Lines (Hough)":
+        edges = cv2.Canny(gray, canny_low, canny_high, L2gradient=True)
+        lines = cv2.HoughLinesP(edges, rho=1, theta=np.pi / 180, threshold=hough_thresh,
+                                minLineLength=hough_min_len, maxLineGap=hough_max_gap)
+        n = 0
+        if lines is not None:
+            for l in lines:
+                x1, y1, x2, y2 = l[0]
+                cv2.line(overlay, (x1, y1), (x2, y2), (255, 128, 0), 2)
+            n = len(lines)
+        meta["num_lines"] = int(n)
+
+    elif detector == "Ellipses (Contours + fitEllipse)":
+        edges = cv2.Canny(gray, canny_low, canny_high, L2gradient=True)
+        contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_NONE)
+        ellipses = []
+        for cnt in contours:
+            if len(cnt) < 5:
+                continue
+            try:
+                (cx, cy), (MA, ma), angle = cv2.fitEllipse(cnt)
+                area = float(np.pi * (MA / 2) * (ma / 2))
+                if area >= ellipse_min_area:
+                    ellipses.append(((cx, cy), (MA, ma), angle, area))
+            except cv2.error:
+                continue
+        ellipses.sort(key=lambda e: e[3], reverse=True)
+        kept = []
+        for e in ellipses:
+            if len(kept) >= max_ellipses:
+                break
+            (cx, cy), (MA, ma), angle, area = e
+            if all((cx - kx) ** 2 + (cy - ky) ** 2 > 100 for ((kx, ky), _, _, _) in kept):
+                kept.append(e)
+        for (cx, cy), (MA, ma), angle, area in kept:
+            cv2.ellipse(overlay, ((int(cx), int(cy)), (int(MA), int(ma)), float(angle)), (0, 200, 255), 2)
+            cv2.circle(overlay, (int(cx), int(cy)), 2, (0, 200, 255), -1)
+        meta["num_ellipses"] = int(len(kept))
+
+    else:
+        meta["error"] = f"Unknown detector: {detector}"
+
+    return to_rgb(overlay), meta
+

backend/py/app/inference/common.py

@@ -0,0 +1,15 @@
+import cv2
+import numpy as np
+
+
+def to_bgr(img: np.ndarray) -> np.ndarray:
+    if img.ndim == 2:
+        return cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
+    if img.shape[2] == 4:
+        return cv2.cvtColor(img, cv2.COLOR_RGBA2BGR)
+    return cv2.cvtColor(img, cv2.COLOR_RGB2BGR)
+
+
+def to_rgb(img: np.ndarray) -> np.ndarray:
+    return cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+

backend/py/app/inference/dl.py

@@ -0,0 +1,171 @@
+import os
+from typing import Any, Dict, Optional, Tuple
+
+import cv2
+import numpy as np
+
+from .common import to_bgr, to_rgb
+
+try:
+    import onnxruntime as ort  # type: ignore
+except Exception:  # pragma: no cover
+    ort = None  # type: ignore
+
+
+MODEL_DIR = os.path.join(os.getcwd(), "models")
+
+DL_MODELS = {
+    "Edges (Canny)": ["hed.onnx", "dexined.onnx"],
+    "Corners (Harris)": ["superpoint.onnx"],
+    "Lines (Hough)": ["sold2.onnx", "hawp.onnx"],
+    "Ellipses (Contours + fitEllipse)": ["ellipse_head.onnx"],
+}
+
+
+def _find_model(detector: str, choice_name: Optional[str]) -> Optional[str]:
+    if choice_name:
+        p = os.path.join(MODEL_DIR, choice_name)
+        return p if os.path.isfile(p) else None
+    for fname in DL_MODELS.get(detector, []):
+        p = os.path.join(MODEL_DIR, fname)
+        if os.path.isfile(p):
+            return p
+    return None
+
+
+def _load_session(path: str):
+    if ort is None:
+        raise RuntimeError("onnxruntime not installed. `pip install onnxruntime`.")
+    providers = ["CoreMLExecutionProvider", "CPUExecutionProvider"] if "darwin" in os.sys.platform else ["CPUExecutionProvider"]
+    try:
+        return ort.InferenceSession(path, providers=providers)
+    except Exception as e:
+        raise RuntimeError(f"Failed to load ONNX model '{path}': {e}")
+
+
+def detect_dl(
+    image: np.ndarray,
+    detector: str,
+    model_choice: Optional[str],
+) -> Tuple[np.ndarray, Dict[str, Any]]:
+    bgr = to_bgr(image)
+    rgb = to_rgb(bgr)
+    h, w = rgb.shape[:2]
+    meta: Dict[str, Any] = {"path": "dl"}
+
+    model_path = _find_model(detector, model_choice)
+    if model_path is None:
+        meta["warning"] = (
+            f"No ONNX model found for '{detector}'. Place a model in ./models."
+            f" Expected one of: {DL_MODELS.get(detector, [])}"
+        )
+        return rgb, meta
+
+    meta["model_path"] = model_path
+
+    try:
+        sess = _load_session(model_path)
+    except Exception as e:
+        meta["error"] = str(e)
+        return rgb, meta
+
+    input_name = sess.get_inputs()[0].name
+    in_shape = sess.get_inputs()[0].shape  # e.g., [1,3,H,W] or dynamic
+    target_h, target_w = None, None
+    if len(in_shape) == 4:
+        target_h = in_shape[2] if isinstance(in_shape[2], int) and in_shape[2] > 0 else 512
+        target_w = in_shape[3] if isinstance(in_shape[3], int) and in_shape[3] > 0 else 512
+    else:
+        target_h, target_w = 512, 512
+
+    img_resized = cv2.resize(rgb, (target_w, target_h), interpolation=cv2.INTER_AREA)
+    x = img_resized.astype(np.float32) / 255.0
+    if x.ndim == 2:
+        x = np.expand_dims(x, axis=-1)
+    if x.shape[2] == 1:
+        x = np.repeat(x, 3, axis=2)
+    x = np.transpose(x, (2, 0, 1))[None, ...]  # NCHW
+
+    try:
+        outputs = sess.run(None, {input_name: x})
+    except Exception as e:
+        meta["error"] = f"ONNX inference failed: {e}"
+        return rgb, meta
+
+    overlay = rgb.copy()
+    if detector == "Edges (Canny)":
+        pred = outputs[0]
+        if pred.ndim == 4:
+            prob = pred[0, 0]
+            prob = (prob - prob.min()) / (prob.max() - prob.min() + 1e-8)
+            edges = (prob > 0.5).astype(np.uint8) * 255
+            edges = cv2.resize(edges, (w, h), interpolation=cv2.INTER_NEAREST)
+            bgr2 = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+            bgr2[edges > 0] = (0, 255, 0)
+            overlay = cv2.cvtColor(bgr2, cv2.COLOR_BGR2RGB)
+            meta["edge_prob_mean"] = float(prob.mean())
+        else:
+            meta["warning"] = "Unexpected model output shape for edges."
+
+    elif detector == "Corners (Harris)":
+        pred = outputs[0]
+        if pred.ndim == 4:
+            heat = pred[0, 0]
+            heat = (heat - heat.min()) / (heat.max() - heat.min() + 1e-8)
+            heat = cv2.resize(heat, (w, h), interpolation=cv2.INTER_CUBIC)
+            ys, xs = np.where(heat > 0.5)
+            overlay = rgb.copy()
+            for (y, x_) in zip(ys.tolist(), xs.tolist()):
+                cv2.circle(overlay, (int(x_), int(y)), 2, (0, 255, 255), -1)
+            meta["num_corners"] = int(len(xs))
+        else:
+            meta["warning"] = "Unexpected model output shape for corners."
+
+    elif detector == "Lines (Hough)":
+        pred = outputs[0]
+        if pred.ndim == 4:
+            heat = pred[0, 0]
+            heat = (heat - heat.min()) / (heat.max() - heat.min() + 1e-8)
+            mask = (heat > 0.5).astype(np.uint8) * 255
+            mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+            lines = cv2.HoughLinesP(mask, 1, np.pi/180, 50, minLineLength=30, maxLineGap=5)
+            overlay = rgb.copy()
+            n = 0
+            if lines is not None:
+                for l in lines:
+                    x1, y1, x2, y2 = l[0]
+                    cv2.line(overlay, (x1, y1), (x2, y2), (255, 128, 0), 2)
+                n = len(lines)
+            meta["num_lines"] = int(n)
+        else:
+            meta["warning"] = "Unexpected model output for lines."
+
+    elif detector == "Ellipses (Contours + fitEllipse)":
+        pred = outputs[0]
+        if pred.ndim == 4:
+            heat = pred[0, 0]
+            heat = (heat - heat.min()) / (heat.max() - heat.min() + 1e-8)
+            mask = (heat > 0.5).astype(np.uint8) * 255
+            mask = cv2.resize(mask, (w, h), interpolation=cv2.INTER_NEAREST)
+            contours, _ = cv2.findContours(mask, cv2.RETR_LIST, cv2.CHAIN_APPROX_NONE)
+            count = 0
+            for cnt in contours:
+                if len(cnt) < 5:
+                    continue
+                try:
+                    (cx, cy), (MA, ma), angle = cv2.fitEllipse(cnt)
+                    area = float(np.pi * (MA / 2) * (ma / 2))
+                    if area >= 300:
+                        cv2.ellipse(overlay, ((int(cx), int(cy)), (int(MA), int(ma)), float(angle)), (0, 200, 255), 2)
+                        count += 1
+                except cv2.error:
+                    continue
+            meta["num_ellipses"] = int(count)
+        else:
+            meta["warning"] = "Unexpected model output for ellipses."
+
+    else:
+        meta["error"] = f"Unknown detector: {detector}"
+
+    return overlay, meta
+

backend/py/app/main.py

@@ -0,0 +1,36 @@
+import os
+from typing import Any
+
+import gradio as gr
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .api.v1.detect import router as detect_router
+from .gradio_demo.ui import build_demo
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="FeatureLab Runtime", version="0.3.0")
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(detect_router)
+
+    demo = build_demo()
+    gr.mount_gradio_app(app, demo, path="/")
+
+    @app.get("/health")
+    async def healthcheck() -> Any:
+        return {"status": "ok"}
+
+    return app
+
+
+app = create_app()
+

backend/py/app/services/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/services/runtime_adapter.py

@@ -0,0 +1,148 @@
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional
+
+import cv2
+import numpy as np
+
+from ..inference.classical import detect_classical
+from ..inference.dl import DL_MODELS, detect_dl
+
+
+DEFAULT_PARAMS: Dict[str, Any] = {
+    "canny_low": 50,
+    "canny_high": 150,
+    "harris_k": 0.05,
+    "harris_block": 2,
+    "harris_ksize": 3,
+    "hough_thresh": 50,
+    "hough_min_len": 30,
+    "hough_max_gap": 5,
+    "ellipse_min_area": 300,
+    "max_ellipses": 5,
+}
+
+PARAM_TYPES: Dict[str, Any] = {
+    "canny_low": int,
+    "canny_high": int,
+    "harris_k": float,
+    "harris_block": int,
+    "harris_ksize": int,
+    "hough_thresh": int,
+    "hough_min_len": int,
+    "hough_max_gap": int,
+    "ellipse_min_area": int,
+    "max_ellipses": int,
+}
+
+CLASSICAL_MODEL_INFO = {"name": "opencv-classical", "version": cv2.__version__}
+
+try:
+    import onnxruntime as ort  # type: ignore
+except Exception:  # pragma: no cover
+    ort = None  # type: ignore
+
+DL_MODEL_INFO = {
+    "name": "onnxruntime" if ort is not None else "onnxruntime-missing",
+    "version": getattr(ort, "__version__", "unknown"),
+}
+
+
+def merge_params(params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    merged = DEFAULT_PARAMS.copy()
+    if params:
+        for key, value in params.items():
+            if value is None or key not in DEFAULT_PARAMS:
+                continue
+            caster = PARAM_TYPES.get(key, lambda x: x)
+            try:
+                merged[key] = caster(value)
+            except (TypeError, ValueError):
+                continue
+    return merged
+
+
+@dataclass
+class DetectionResult:
+    overlays: Dict[str, np.ndarray] = field(default_factory=dict)
+    features: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    timings_ms: Dict[str, float] = field(default_factory=dict)
+    fps_estimate: Optional[float] = None
+    models: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+
+
+def run_detection(
+    image: np.ndarray,
+    detector: str,
+    params: Optional[Dict[str, Any]] = None,
+    mode: Literal["classical", "dl", "both"] = "classical",
+    dl_choice: Optional[str] = None,
+) -> DetectionResult:
+    merged = merge_params(params)
+    overlays: Dict[str, np.ndarray] = {}
+    features: Dict[str, Dict[str, Any]] = {}
+    timings: Dict[str, float] = {}
+    models: Dict[str, Dict[str, Any]] = {}
+
+    execute_classical = mode in ("classical", "both")
+    execute_dl = mode in ("dl", "both")
+
+    total_ms = 0.0
+
+    if execute_classical:
+        t0 = time.perf_counter()
+        classical_img, classical_meta = detect_classical(
+            image,
+            detector,
+            merged["canny_low"],
+            merged["canny_high"],
+            merged["harris_k"],
+            merged["harris_block"],
+            merged["harris_ksize"],
+            merged["hough_thresh"],
+            merged["hough_min_len"],
+            merged["hough_max_gap"],
+            merged["ellipse_min_area"],
+            merged["max_ellipses"],
+        )
+        t_ms = (time.perf_counter() - t0) * 1000.0
+        overlays["classical"] = classical_img
+        features["classical"] = classical_meta
+        timings["classical"] = round(t_ms, 2)
+        models["classical"] = CLASSICAL_MODEL_INFO
+        total_ms += t_ms
+
+    if execute_dl:
+        t0 = time.perf_counter()
+        dl_img, dl_meta = detect_dl(image, detector, dl_choice)
+        t_ms = (time.perf_counter() - t0) * 1000.0
+        overlays["dl"] = dl_img
+        features["dl"] = dl_meta
+        timings["dl"] = round(t_ms, 2)
+        model_name = (
+            os.path.basename(dl_meta["model_path"]) if "model_path" in dl_meta else DL_MODEL_INFO["name"]
+        )
+        models["dl"] = {"name": model_name, "version": DL_MODEL_INFO["version"]}
+        total_ms += t_ms
+
+    timings["total"] = round(total_ms, 2)
+    fps = round(1000.0 / total_ms, 2) if total_ms > 0 else None
+
+    return DetectionResult(
+        overlays=overlays,
+        features=features,
+        timings_ms=timings,
+        fps_estimate=fps,
+        models=models,
+    )
+
+
+__all__ = [
+    "DetectionResult",
+    "DEFAULT_PARAMS",
+    "DL_MODELS",
+    "merge_params",
+    "run_detection",
+]
+

backend/py/app/utils/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

backend/py/app/utils/image_io.py

@@ -0,0 +1,26 @@
+import base64
+from typing import Optional
+
+import cv2
+import numpy as np
+
+
+def encode_png_base64(image: np.ndarray) -> str:
+    bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+    success, buf = cv2.imencode('.png', bgr)
+    if not success:
+        raise RuntimeError('Failed to encode image to PNG.')
+    return base64.b64encode(buf.tobytes()).decode('ascii')
+
+
+def decode_base64_image(data: str) -> np.ndarray:
+    # Support data URLs: data:image/png;base64,....
+    if ',' in data and data.strip().startswith('data:'):
+        data = data.split(',', 1)[1]
+    binary = base64.b64decode(data)
+    arr = np.frombuffer(binary, dtype=np.uint8)
+    image = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+    if image is None:
+        raise ValueError('Unable to decode image.')
+    return cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+

requirements.txt

@@ -0,0 +1,6 @@
+gradio>=4.44.0
+opencv-python-headless>=4.10.0.84
+numpy>=1.26.0
+fastapi>=0.112.0
+uvicorn>=0.30.0
+python-multipart>=0.0.9