merge with main

Signed-off-by: Emil Badura <badura@tu-berlin.de>

Author: Tenebrae311

CONTRIBUTING.md

@@ -95,20 +95,30 @@ Before you can run the project locally, install the required tools:
 
 #### Prerequisites
 
-**Node.js 20+** (for frontend)
+**Node.js 20** (for frontend)
+
+Recommended: Use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions:
 ```bash
-brew install node@20
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+cd src/frontend
+nvm install  # Installs Node.js 20
+nvm use      # Switches to Node.js 20
 ```
 
-**Python 3.11+** (for backend)
+Alternative (without nvm):
 ```bash
-brew install python@3.11
+brew install node@20
 ```
 
+**Python 3.11** (for backend)
+
+The Makefile will automatically install Python 3.11 via `uv`. You just need `uv` installed:
+
 **uv** (Python package manager)
 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh
-# or on mac
+# or on macOS
 brew install uv
 ```
 
@@ -148,8 +158,7 @@ Linting catches code issues and enforces style guidelines. Always run before pus
 ```bash
 make lint                  # Lint all components (includes type checking)
 make lint-frontend         # Lint frontend with ESLint
-make lint-backend          # Lint backend with Ruff
-make type-check-backend    # Type check backend with mypy
+make lint-backend          # Lints and type checks backend with Ruff
 ```
 
 Before you push your changes, run `make lint` and address any errors.

Makefile

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: MIT
 
-.PHONY: help lint lint-frontend lint-backend type-check-backend 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 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
 
 help:
 	@echo "make"
@@ -54,20 +54,27 @@ dev: install
 install: install-frontend install-backend
 
 install-frontend:
+	@echo "Installing frontend dependencies (Node.js 20 required, see .nvmrc)"
 	cd src/frontend && npm install
 
 install-backend:
-	cd src/backend && uv venv
+	cd src/backend && uv python install   # Auto-uses .python-version (3.11)
+	cd src/backend && uv venv             # Auto-uses .python-version (3.11)
 	cd src/backend && uv pip install -r requirements.txt
 	cd src/backend && uv pip install -r requirements-dev.txt
 
+<<<<<<< HEAD
 lint: lint-frontend lint-backend lint-licensing type-check-backend
+=======
+lint: lint-frontend lint-backend
+>>>>>>> origin/main
 
 lint-frontend:
 	cd src/frontend && npm run lint
 
 lint-backend:
 	cd src/backend && uv run ruff check .
+	cd src/backend && uv run mypy .
 
 lint-licensing:
 	reuse lint
@@ -80,9 +87,6 @@ format-frontend:
 format-backend:
 	cd src/backend && uv run ruff format .
 
-type-check-backend:
-	cd src/backend && uv run mypy .
-
 test: test-frontend test-backend
 
 test-frontend:

src/backend/.python-version

@@ -0,0 +1,2 @@
+3.11
+

src/backend/requirements.txt

@@ -1,3 +1,10 @@
 # SPDX-FileCopyrightText: 2025 robot-visual-perception
 #
 # SPDX-License-Identifier: MIT
+fastapi==0.115.10
+aiortc==1.14.0
+av==16.0.1
+opencv-python==4.12.0.88
+pydantic==2.12.3
+uvicorn==0.38.0
+numpy==2.2.6

src/backend/webrtc/server.py

@@ -12,15 +12,16 @@
 - Wildcard origins without credentials (spec-compliant).
 
 Run:
-    uvicorn server:app --host 0.0.0.0 --port 8000
+    uv run uvicorn server:app --host 0.0.0.0 --port 8000
 """
 
 import asyncio
 import os
 import sys
 import contextlib
-from typing import Optional, List
+from typing import Optional, List, Tuple
 
+import numpy as np
 import cv2
 from fastapi import FastAPI, HTTPException, Response
 from fastapi.middleware.cors import CORSMiddleware
@@ -32,22 +33,24 @@
     RTCIceServer,
     VideoStreamTrack,
 )
+from av import VideoFrame
+
 
 # -----------------------------
 # Global camera singleton
 # -----------------------------
 
 
 class _SharedCamera:
-    def __init__(self):
+    def __init__(self) -> None:
         self._refcount = 0
         self._lock = asyncio.Lock()
-        self._cap = None
-        self._frame = None
+        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):
+    async def acquire(self) -> None:
         async with self._lock:
             self._refcount += 1
             if self._cap is None:
@@ -56,7 +59,7 @@ async def acquire(self):
                 self._running = True
                 self._reader_task = asyncio.create_task(self._read_loop())
 
-    async def release(self):
+    async def release(self) -> None:
         async with self._lock:
             self._refcount -= 1
             if self._refcount <= 0:
@@ -72,7 +75,7 @@ async def release(self):
                 self._reader_task = None
                 self._refcount = 0
 
-    async def _read_loop(self):
+    async def _read_loop(self) -> None:
         loop = asyncio.get_running_loop()
         try:
             while self._running and self._cap:
@@ -84,11 +87,13 @@ async def _read_loop(self):
         except asyncio.CancelledError:
             pass
 
-    def latest(self):
+    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] = []
@@ -101,7 +106,11 @@ def _open_camera(idx: int) -> cv2.VideoCapture:
 
     last_error: Optional[str] = None
     for backend in backends:
-        cap = cv2.VideoCapture(idx, backend) if backend != cv2.CAP_ANY else cv2.VideoCapture(idx)
+        cap = (
+            cv2.VideoCapture(idx, backend)
+            if backend != cv2.CAP_ANY
+            else cv2.VideoCapture(idx)
+        )
         if cap.isOpened():
             return cap
         cap.release()
@@ -113,16 +122,17 @@ def _open_camera(idx: int) -> cv2.VideoCapture:
     msg += ". Try CAMERA_INDEX=1 or ensure camera permissions are granted."
     raise RuntimeError(msg)
 
+
 # -----------------------------
 # Media track
 # -----------------------------
 class CameraVideoTrack(VideoStreamTrack):
     kind = "video"
 
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__()
 
-    async def recv(self):
+    async def recv(self) -> VideoFrame:
         pts, time_base = await self.next_timestamp()
 
         frame = None
@@ -138,15 +148,13 @@ async def recv(self):
             else:
                 await asyncio.sleep(0.005)
 
-        from av import VideoFrame
-        import cv2 as _cv2
-
-        rgb = _cv2.cvtColor(frame, _cv2.COLOR_BGR2RGB)
+        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB).astype(np.uint8)
         video_frame = VideoFrame.from_ndarray(rgb, format="rgb24")
         video_frame.pts = pts
         video_frame.time_base = time_base
         return video_frame
 
+
 # -----------------------------
 # FastAPI app
 # -----------------------------
@@ -161,30 +169,37 @@ async def recv(self):
     allow_headers=["*"],
 )
 
+
 class SDPModel(BaseModel):
     sdp: str
     type: str  # "offer"
 
+
 pcs: List[RTCPeerConnection] = []
 
+
 @app.get("/health")
-def health():
+def health() -> dict[str, str]:
     return {"status": "ok"}
 
+
 # Explicit OPTIONS handlers to avoid 405 on preflight in some setups
 @app.options("/offer")
 @app.options("/offer/")
-def options_offer():
+def options_offer() -> Response:
     return Response(status_code=204)
 
+
 # Accept both /offer and /offer/
 @app.post("/offer")
 @app.post("/offer/")
-async def offer(sdp: SDPModel):
+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"])])
+    cfg = RTCConfiguration(
+        iceServers=[RTCIceServer(urls=["stun:stun.l.google.com:19302"])]
+    )
     pc = RTCPeerConnection(configuration=cfg)
     pcs.append(pc)
 
@@ -205,12 +220,12 @@ async def offer(sdp: SDPModel):
             ice_ready.set_result(True)
 
     @pc.on("icegatheringstatechange")
-    def on_ice_gathering_state_change():
+    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():
+    async def on_ice_state_change() -> None:
         if pc.iceConnectionState in ("failed", "closed", "disconnected"):
             await _cleanup_pc(pc)
 
@@ -224,11 +239,13 @@ async def on_ice_state_change():
 
     return {"sdp": pc.localDescription.sdp, "type": pc.localDescription.type}
 
+
 @app.on_event("shutdown")
-async def on_shutdown():
+async def on_shutdown() -> None:
     await asyncio.gather(*[_cleanup_pc(pc) for pc in list(pcs)], return_exceptions=True)
 
-async def _cleanup_pc(pc: RTCPeerConnection):
+
+async def _cleanup_pc(pc: RTCPeerConnection) -> None:
     if pc in pcs:
         pcs.remove(pc)
     with contextlib.suppress(Exception):
@@ -238,6 +255,6 @@ async def _cleanup_pc(pc: RTCPeerConnection):
             await _shared_cam.release()
 
 
-def _read_frame(cap: cv2.VideoCapture):
+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()
+    return cap.read()

src/frontend/.nvmrc

@@ -0,0 +1,2 @@
+20
+

src/frontend/index.html

@@ -4,7 +4,7 @@
 SPDX-License-Identifier: MIT
 -->
 
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
@@ -16,4 +16,3 @@
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
-

src/frontend/src/App.tsx

@@ -31,4 +31,3 @@ function App() {
 }
 
 export default App;
-

src/frontend/src/main.tsx

@@ -14,4 +14,3 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
     <App />
   </React.StrictMode>
 );
-

src/frontend/tsconfig.json

@@ -22,4 +22,3 @@
   },
   "include": ["src"]
 }
-