From b447d3e7c5b1c09eb76560741537339394c3caa7 Mon Sep 17 00:00:00 2001 From: Joachim Hummel Date: Mon, 1 Jun 2026 14:16:54 +0200 Subject: [PATCH] README: Voraussetzungen aktualisiert (CUDA-GPU, ESP32-CAM, MQTT) - NVIDIA-GPU mit CUDA als Voraussetzung dokumentiert (FP16, CPU-Fallback) - ESP32-CAM als MJPEG-Live-Quelle inkl. CAMERA_URL/Fan-out/Always-on - MQTT-Broker fuer Crossing-Events (Topic, Payload, Env-Konfig) - Installation um CUDA-PyTorch, requests und paho-mqtt ergaenzt Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d0bfd08..2e368b7 100644 --- a/README.md +++ b/README.md @@ -15,19 +15,35 @@ Eine webbasierte Anwendung zur Echtzeit-Objekterkennung und -Verfolgung mittels ## Voraussetzungen - Python 3.12 oder höher -- Webcam (für Live-Erkennung) +- **NVIDIA-Grafikkarte mit CUDA-Unterstützung** – für die Echtzeit-Erkennung erforderlich (siehe [Hardware & CUDA](#hardware--cuda)) +- **ESP32-CAM** als Live-Quelle, die einen MJPEG-Stream im Netzwerk bereitstellt (siehe [Kamera / Livestream (ESP32-CAM)](#kamera--livestream-esp32-cam)) +- **MQTT-Broker** zum Empfang der Zähl-Events (z. B. [Mosquitto](https://mosquitto.org/); siehe [MQTT / Zähl-Events](#mqtt--zähl-events)) - YOLO-Modell (`yolo11s.pt`) im Hauptverzeichnis +> ⚠️ **Wichtig:** Für die flüssige Live-Erkennung wird eine **NVIDIA-GPU mit CUDA** benötigt. Ohne CUDA läuft die Inferenz auf der CPU und ist für Echtzeit-Streams zu langsam. + ## Installation 1. Repository klonen oder herunterladen 2. Erforderliche Python-Pakete installieren: ```bash -pip3 install flask opencv-python numpy ultralytics +pip3 install flask opencv-python numpy ultralytics requests paho-mqtt ``` -3. Sicherstellen, dass die Modelldatei `yolo11s.pt` im Hauptverzeichnis vorhanden ist +3. **CUDA-fähiges PyTorch installieren** (für GPU-Beschleunigung). Die passende + Variante richtet sich nach der installierten CUDA-Version, z. B. für CUDA 12.x: +```bash +pip3 install torch --index-url https://download.pytorch.org/whl/cu121 +``` + Prüfen, ob die GPU erkannt wird: +```bash +python3 -c "import torch; print(torch.cuda.is_available())" +``` + Gibt der Befehl `True` aus, wird die NVIDIA-GPU genutzt und FP16-Inferenz + automatisch aktiviert. + +4. Sicherstellen, dass die Modelldatei `yolo11s.pt` im Hauptverzeichnis vorhanden ist ## Verwendung @@ -69,6 +85,81 @@ Die Anwendung ist dann unter `http://localhost:8080` erreichbar. ## Technische Details +### Kamera / Livestream (ESP32-CAM) + +In diesem Beispiel dient eine **ESP32-CAM** als Live-Quelle. Sie stellt einen +**MJPEG-Stream** im Netzwerk bereit, den die Anwendung abgreift, mit YOLO +auswertet und an die Browser-Viewer weiterverteilt. + +- Die Stream-Adresse wird über die Umgebungsvariable `CAMERA_URL` gesetzt. + Standard ist die typische ESP32-CAM-Adresse (Port `81`, Pfad `/stream`): + ```bash + export CAMERA_URL="http://CAMERA-IP:81/stream" + ``` +- Es wird **eine einzige Verbindung** zur ESP32-CAM aufgebaut und das Bild an + beliebig viele Zuschauer verteilt (Fan-out). So wird der begrenzte + Stream-Slot der ESP32-CAM nicht durch jeden Browser blockiert. +- Mit `GRABBER_ALWAYS_ON=1` läuft der Grabber rund um die Uhr und zählt auch + dann, wenn niemand zuschaut. Bei `0` (Standard) verbindet er sich nur, solange + ein Browser den Stream betrachtet – das gibt den ESP32-Slot wieder frei. + +> 💡 Statt einer ESP32-CAM kann über `CAMERA_URL` auch jede andere MJPEG-/HTTP- +> Stream-Quelle eingebunden werden. + +### MQTT / Zähl-Events + +Jede erkannte Linienüberquerung wird als **MQTT-Event** veröffentlicht. Dafür +wird ein **MQTT-Broker** benötigt (z. B. [Mosquitto](https://mosquitto.org/)). +So lassen sich die Zähldaten z. B. über **n8n** weiterverarbeiten und in einer +Datenbank wie **NocoDB** ablegen. + +- Die Events werden auf dem Topic `{MQTT_TOPIC}/crossing` mit **QoS 1** + (nicht retained) publiziert. +- Das Payload ist JSON, z. B.: + ```json + { + "event": "crossing", + "camera": "cam1", + "source": "webcam", + "type": "car", + "track_id": 42, + "ts": "2026-06-01T12:34:56+02:00" + } + ``` +- Konfiguriert wird der Broker über Umgebungsvariablen: + + | Variable | Standard | Beschreibung | + | ------------ | ---------------------- | ------------------------------------ | + | `MQTT_HOST` | `127.0.0.1` | Adresse des MQTT-Brokers | + | `MQTT_PORT` | `1883` | Broker-Port | + | `MQTT_USER` | – | Benutzername (optional) | + | `MQTT_PASS` | – | Passwort (optional) | + | `MQTT_TOPIC` | `vehiclecounter/cam1` | Basis-Topic der Events | + | `CAMERA_ID` | `cam1` | Kamera-Kennung im Payload | + +> ℹ️ Die Verbindung zum Broker erfolgt asynchron. Ist der Broker nicht +> erreichbar, startet die Anwendung trotzdem – es werden dann lediglich keine +> Events übertragen. + +### Hardware & CUDA + +Die Objekterkennung mit YOLOv11 ist rechenintensiv. Für die Echtzeit-Verarbeitung +von Live-Streams wird daher eine **NVIDIA-Grafikkarte mit CUDA** benötigt. + +- **Mit NVIDIA-GPU (CUDA):** Die Inferenz läuft auf der Grafikkarte. Erkennt die + Anwendung eine CUDA-fähige GPU, wird automatisch **FP16-Inferenz** aktiviert + (per `YOLO_HALF` überschreibbar) – das halbiert den Speicherbedarf und erhöht + die Bildrate spürbar. +- **Ohne GPU (nur CPU):** Die Anwendung startet zwar, die Inferenz ist für + Live-Streams jedoch zu langsam. Ein zusätzliches **Motion-Gate** sorgt dafür, + dass YOLO nur bei tatsächlicher Bewegung im Bild ausgeführt wird, was die Last + reduziert – ersetzt eine GPU aber nicht. + +Voraussetzungen für die GPU-Nutzung: + +- NVIDIA-Treiber + passende CUDA-Runtime +- CUDA-fähiges PyTorch (siehe [Installation](#installation)) + ### Verwendete Technologien - **Flask**: Web-Framework für Routing und Template-Rendering