Backend server split into components

Signed-off-by: anuunchin <anuun.ch@gmail.com>

Author: anuunchin

Makefile

@@ -2,52 +2,64 @@
 #
 # SPDX-License-Identifier: MIT
 
-.PHONY: help lint lint-frontend lint-backend lint-licensing test test-frontend test-backend format format-frontend format-backend docker-build docker-build-frontend docker-build-backend docker-run-frontend docker-run-backend docker-stop docker-clean
+.PHONY: help \
+	dev install install-frontend install-backend \
+	lint lint-frontend lint-backend lint-licensing type-check-backend \
+	format format-frontend format-backend \
+	test test-frontend test-backend \
+	run-backend-local run-frontend-local \
+	docker-build docker-build-frontend docker-build-backend \
+	docker-run-frontend docker-run-backend \
+	docker-stop docker-clean
 
 help:
 	@echo "make"
-	@echo "		dev (or install)"
-	@echo "			install all dependencies for development"
-	@echo "		install-frontend"
-	@echo "			install frontend dependencies (npm)"
-	@echo "		install-backend"
-	@echo "			install backend dependencies (uv)"
-	@echo "		lint"
-	@echo "			runs all linters and type checking (frontend, backend, licensing)"
-	@echo "		lint-frontend"
-	@echo "			lints frontend code with npm run lint"
-	@echo "		lint-backend"
-	@echo "			lints backend Python code with ruff"
-	@echo "		lint-licensing"
-	@echo "			lints licensing files with reuse"
-	@echo "		type-check-backend"
-	@echo "			type checks backend Python code with mypy"
-	@echo "		format"
-	@echo "			formats all code (frontend and backend)"
-	@echo "		format-frontend"
-	@echo "			formats frontend code with prettier"
-	@echo "		format-backend"
-	@echo "			formats backend Python code with ruff"
-	@echo "		test"
-	@echo "			runs all tests (frontend and backend)"
-	@echo "		test-frontend"
-	@echo "			runs frontend tests with vitest"
-	@echo "		test-backend"
-	@echo "			runs backend tests with pytest"
-	@echo "		docker-build"
-	@echo "			builds all Docker images (frontend and backend)"
-	@echo "		docker-build-frontend"
-	@echo "			builds frontend Docker image"
-	@echo "		docker-build-backend"
-	@echo "			builds backend Docker image"
-	@echo "		docker-run-frontend"
-	@echo "			runs frontend container on port 8080"
-	@echo "		docker-run-backend"
-	@echo "			runs backend container on port 8000"
-	@echo "		docker-stop"
-	@echo "			stops running containers"
-	@echo "		docker-clean"
-	@echo "			stops containers and removes Docker images"
+	@echo "  dev (or install)"
+	@echo "      install all dependencies for development"
+	@echo "  install-frontend"
+	@echo "      install frontend dependencies (npm)"
+	@echo "  install-backend"
+	@echo "      install backend dependencies (uv)"
+	@echo "  lint"
+	@echo "      runs all linters and type checking (frontend, backend, licensing)"
+	@echo "  lint-frontend"
+	@echo "      lints frontend code with npm run lint"
+	@echo "  lint-backend"
+	@echo "      lints backend Python code with ruff"
+	@echo "  type-check-backend"
+	@echo "      type checks backend Python code with mypy"
+	@echo "  lint-licensing"
+	@echo "      lints licensing files with reuse"
+	@echo "  format"
+	@echo "      formats all code (frontend and backend)"
+	@echo "  format-frontend"
+	@echo "      formats frontend code with prettier"
+	@echo "  format-backend"
+	@echo "      formats backend code with ruff"
+	@echo "  test"
+	@echo "      runs all tests (frontend and backend)"
+	@echo "  test-frontend"
+	@echo "      runs frontend tests with vitest"
+	@echo "  test-backend"
+	@echo "      runs backend tests with pytest"
+	@echo "  run-backend-local"
+	@echo "      runs backend locally with uvicorn"
+	@echo "  run-frontend-local"
+	@echo "      runs frontend locally with Vite (uses VITE_BACKEND_URL)"
+	@echo "  docker-build"
+	@echo "      builds all Docker images (frontend and backend)"
+	@echo "  docker-build-frontend"
+	@echo "      builds frontend Docker image"
+	@echo "  docker-build-backend"
+	@echo "      builds backend Docker image"
+	@echo "  docker-run-frontend"
+	@echo "      runs frontend container on port 8080"
+	@echo "  docker-run-backend"
+	@echo "      runs backend container on port 8000"
+	@echo "  docker-stop"
+	@echo "      stops running containers"
+	@echo "  docker-clean"
+	@echo "      stops containers and removes Docker images"
 
 dev: install
 
@@ -63,7 +75,7 @@ install-backend:
 	cd src/backend && uv pip install -r requirements.txt
 	cd src/backend && uv pip install -r requirements-dev.txt
 
-lint: lint-frontend lint-backend lint-licensing type-check-backend
+lint: lint-frontend lint-backend lint-licensing
 
 lint-frontend:
 	cd src/frontend && npm run lint
@@ -91,6 +103,12 @@ test-frontend:
 test-backend:
 	cd src/backend && uv run pytest
 
+run-backend-local:
+	cd src/backend && uv run uvicorn webrtc.server:app --host 0.0.0.0 --port 8000
+
+run-frontend-local:
+	cd src/frontend && VITE_BACKEND_URL=http://localhost:8000 npm run dev
+
 docker-build: docker-build-frontend docker-build-backend
 
 docker-build-frontend:

src/backend/__init__.py

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+import asyncio
+import contextlib
+import os
+import sys
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+
+class _SharedCamera:
+    def __init__(self) -> None:
+        self._refcount = 0
+        self._lock = asyncio.Lock()
+        self._cap: Optional[cv2.VideoCapture] = None
+        self._frame: Optional[np.ndarray] = None
+        self._running = False
+        self._reader_task: Optional[asyncio.Task] = None
+
+    async def acquire(self) -> None:
+        async with self._lock:
+            self._refcount += 1
+            if self._cap is None:
+                idx = int(os.getenv("CAMERA_INDEX", "0"))
+                self._cap = _open_camera(idx)
+                self._running = True
+                self._reader_task = asyncio.create_task(self._read_loop())
+
+    async def release(self) -> None:
+        async with self._lock:
+            self._refcount -= 1
+            if self._refcount <= 0:
+                self._running = False
+                if self._reader_task:
+                    self._reader_task.cancel()
+                    with contextlib.suppress(Exception):
+                        await self._reader_task
+                if self._cap is not None:
+                    self._cap.release()
+                    self._cap = None
+                self._frame = None
+                self._reader_task = None
+                self._refcount = 0
+
+    async def _read_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        try:
+            while self._running and self._cap:
+                ok, frame = await loop.run_in_executor(None, _read_frame, self._cap)
+                if ok:
+                    self._frame = frame
+                else:
+                    await asyncio.sleep(0.03)
+        except asyncio.CancelledError:
+            pass
+
+    def latest(self) -> Optional[np.ndarray]:
+        return self._frame
+
+
+_shared_cam = _SharedCamera()
+
+
+def _open_camera(idx: int) -> cv2.VideoCapture:
+    """Try platform-appropriate backends before giving up."""
+    backends: List[int] = []
+    if sys.platform.startswith("win"):
+        backends = [cv2.CAP_DSHOW, cv2.CAP_ANY]
+    elif sys.platform == "darwin":
+        backends = [cv2.CAP_AVFOUNDATION, cv2.CAP_ANY]
+    else:
+        backends = [cv2.CAP_V4L2, cv2.CAP_ANY]
+
+    last_error: Optional[str] = None
+    for backend in backends:
+        cap = (
+            cv2.VideoCapture(idx, backend)
+            if backend != cv2.CAP_ANY
+            else cv2.VideoCapture(idx)
+        )
+        if cap.isOpened():
+            return cap
+        cap.release()
+        last_error = f"backend={backend}"
+
+    msg = f"Cannot open webcam at index {idx}"
+    if last_error:
+        msg += f" (last tried {last_error})"
+    msg += ". Try CAMERA_INDEX=1 or ensure camera permissions are granted."
+    raise RuntimeError(msg)
+
+
+def _read_frame(cap: cv2.VideoCapture) -> Tuple[bool, Optional[np.ndarray]]:
+    """Run in a thread to grab frames without blocking asyncio loop."""
+    return cap.read()

src/backend/camera.py

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+import asyncio
+import os
+from typing import Optional
+
+import cv2
+import numpy as np
+from ultralytics import YOLO  # type: ignore[import-untyped]
+
+
+class _Detector:
+    def __init__(self) -> None:
+        self._model = YOLO("yolov8n.pt")
+        self._last_det: Optional[list[tuple[int, int, int, int, int, float]]] = None
+        self._last_time: float = 0.0
+        self._lock = asyncio.Lock()
+        self._fov_deg: float = float(os.getenv("CAMERA_HFOV_DEG", "60"))
+
+    async def infer(
+        self, frame_bgr: np.ndarray
+    ) -> list[tuple[int, int, int, int, int, float]]:
+        now = asyncio.get_running_loop().time()
+        if self._last_det is not None and (now - self._last_time) < 0.10:
+            return self._last_det
+
+        async with self._lock:
+            now = asyncio.get_running_loop().time()
+            if self._last_det is not None and (now - self._last_time) < 0.10:
+                return self._last_det
+
+            rgb = cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB)
+            results = self._model.predict(rgb, imgsz=640, conf=0.25, verbose=False)
+            dets: list[tuple[int, int, int, int, int, float]] = []
+            if results:
+                r = results[0]
+                if r.boxes is not None and len(r.boxes) > 0:
+                    xyxy = r.boxes.xyxy.cpu().numpy().astype(int)
+                    cls = r.boxes.cls.cpu().numpy().astype(int)
+                    conf = r.boxes.conf.cpu().numpy()
+                    for (x1, y1, x2, y2), c, p in zip(xyxy, cls, conf):
+                        dets.append(
+                            (int(x1), int(y1), int(x2), int(y2), int(c), float(p))
+                        )
+
+            self._last_det = dets
+            self._last_time = now
+            return dets
+
+    def estimate_distance_m(
+        self, bbox: tuple[int, int, int, int], frame_width: int
+    ) -> float:
+        x1, y1, x2, y2 = bbox
+        pix_w = max(1, x2 - x1)
+        obj_w_m = float(os.getenv("OBJ_WIDTH_M", "0.5"))
+        fov_rad = np.deg2rad(self._fov_deg)
+        focal_px = (frame_width / 2.0) / np.tan(fov_rad / 2.0)
+        dist_m = (obj_w_m * focal_px) / pix_w
+        scale = float(os.getenv("DIST_SCALE", "1.5"))
+        return float(dist_m * scale)
+
+
+_detector = _Detector()

src/backend/detector.py

@@ -0,0 +1,105 @@
+# SPDX-FileCopyrightText: 2025 robot-visual-perception
+#
+# SPDX-License-Identifier: MIT
+import asyncio
+import contextlib
+
+from fastapi import APIRouter, HTTPException, Response
+from aiortc import (
+    RTCPeerConnection,
+    RTCSessionDescription,
+    RTCConfiguration,
+    RTCIceServer,
+)
+from aiortc.rtcrtpsender import RTCRtpSender
+
+from .schemas import SDPModel
+from .camera import _shared_cam
+from .tracks import CameraVideoTrack
+from .webrtc_utils import _cleanup_pc
+from .state import pcs, _datachannels
+
+router = APIRouter()
+
+
+@router.get("/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+# Explicit OPTIONS handlers to avoid 405 on preflight in some setups
+@router.options("/offer")
+@router.options("/offer/")
+def options_offer() -> Response:
+    return Response(status_code=204)
+
+
+# Accept both /offer and /offer/
+@router.post("/offer")
+@router.post("/offer/")
+async def offer(sdp: SDPModel) -> dict[str, str]:
+    if sdp.type != "offer":
+        raise HTTPException(400, "type must be 'offer'")
+
+    cfg = RTCConfiguration(
+        iceServers=[RTCIceServer(urls=["stun:stun.l.google.com:19302"])]
+    )
+    pc = RTCPeerConnection(configuration=cfg)
+    pcs.append(pc)
+
+    ice_ready = asyncio.get_event_loop().create_future()
+
+    try:
+        await _shared_cam.acquire()
+    except Exception as e:
+        await pc.close()
+        pcs.remove(pc)
+        raise HTTPException(500, f"Camera error: {e}")
+
+    local_video = CameraVideoTrack()
+    pc.addTrack(local_video)
+
+    # Create a data channel for metadata
+    ch = pc.createDataChannel("meta")
+    _datachannels[id(pc)] = ch
+
+    # Prefer H.264 to support Safari and improve cross-browser compatibility
+    try:
+        caps = RTCRtpSender.getCapabilities("video").codecs
+        h264 = [c for c in caps if getattr(c, "mimeType", "").lower() == "video/h264"]
+        if h264:
+            for t in pc.getTransceivers():
+                if t.kind == "video":
+                    t.setCodecPreferences(h264)
+    except Exception:
+        pass
+
+    if pc.iceGatheringState == "complete":
+        if not ice_ready.done():
+            ice_ready.set_result(True)
+
+    @pc.on("icegatheringstatechange")
+    def on_ice_gathering_state_change() -> None:
+        if pc.iceGatheringState == "complete" and not ice_ready.done():
+            ice_ready.set_result(True)
+
+    @pc.on("iceconnectionstatechange")
+    async def on_ice_state_change() -> None:
+        if pc.iceConnectionState in ("failed", "closed", "disconnected"):
+            await _cleanup_pc(pc)
+
+    offer_desc = RTCSessionDescription(sdp=sdp.sdp, type=sdp.type)
+    await pc.setRemoteDescription(offer_desc)
+    answer = await pc.createAnswer()
+    await pc.setLocalDescription(answer)
+
+    with contextlib.suppress(asyncio.TimeoutError):
+        await asyncio.wait_for(ice_ready, timeout=5)
+
+    return {"sdp": pc.localDescription.sdp, "type": pc.localDescription.type}
+
+
+# expose original shutdown hook name; server wires it
+async def on_shutdown() -> None:
+    # keep same semantics as original
+    await asyncio.gather(*[_cleanup_pc(pc) for pc in list(pcs)], return_exceptions=True)