Schlaglocherkennung mit Raspberry Pi 5 und Hailo-8

Dieses Projekt erkennt Straßenschlaglöcher aus Videos mit einem YOLOv8n-Modell im Hailo-HEF-Format, beschleunigt durch einen Hailo-8 auf einem Raspberry Pi 5. Es bietet sowohl Batch-Video-Inferenz mit annotierter Ausgabe als auch eine Echtzeit-MJPEG-Webvorschau mit FPS, Schlaglochzähler und kumulativem Ereigniszähler. Ein ROI-Straßenbereichsfilter unterdrückt Fehlalarme von Himmel und Gehweg, während ein zeitlicher Tracker kurze Erkennungslücken mit gelben Lückenfüllungsboxen überbrückt.

Quellcode: https://github.com/Seeed-Projects/reComputer-AI-Lab-Project/tree/main/pi_project/pothole_detection

Funktionen

• Hailo-8-beschleunigte YOLOv8n-Inferenz auf Raspberry Pi 5
• Ein-Klassen-Schlaglocherkennung mit Hailo-NMS-Nachverarbeitung
• Trapezförmiger ROI-Straßenbereichsfilter zur Unterdrückung von Nicht-Straßen-Erkennungen
• Zeitlicher Tracker mit kurzer Lückenfüllung (gelbe Boxen, max. 3 verpasste Frames)
• Kumulativer Ereigniszähler für eindeutige Schlagloch-Tracks
• Batch-Video-Inferenz mit FPS-Overlay und Konfidenzbeschriftungen
• Browserbasierte MJPEG-Vorschau und Status-API auf Port 8000
• Enthaltenes Demovideo, HEF-Modell und Geräte-Validierungstools
• Bare-Metal- und Docker-Bereitstellungsoptionen
• 35 Hardware-freie Unit-Tests für Syntax, Konfiguration und Nachverarbeitung

Hardware und Software

Host-Treiber, Firmware, gemeinsame Bibliothek und Python-Paket müssen kompatible HailoRT-Versionen verwenden. Das enthaltene HEF-Modell zielt auf Hailo-8 ab, nicht auf Hailo-8L.

Modellinformationen

Boxfarben-Legende

Der Tracker vergibt eindeutige IDs für jedes Schlagloch. Geht eine Erkennung kurzzeitig verloren (z. B. durch Bewegungsunschärfe), überbrückt die gelbe Box die Lücke, um Flackern zu vermeiden. Nach max_missed aufeinanderfolgenden Fehlern (Standard 3) wird der Track entfernt.

Schnellstart mit Docker

Vorkonstruiertes linux/arm64-Image von GHCR ziehen:

sudo docker pull \
  ghcr.io/seeed-projects/recomputer-ai-lab-project/pothole_detection:latest

Enthaltenes Video und Web-Dashboard ausführen:

sudo docker run --rm \
  --name rpi5-hailo8-pothole-detection \
  --privileged \
  --net=host \
  -e PYTHONUNBUFFERED=1 \
  --device /dev/hailo0:/dev/hailo0 \
  -v /usr/lib/libhailort.so.4.23.0:/usr/lib/libhailort.so.4.23.0:ro \
  -v /usr/lib/libhailort.so:/usr/lib/libhailort.so:ro \
  ghcr.io/seeed-projects/recomputer-ai-lab-project/pothole_detection:latest \
  python web_detection.py \
    --config configs/runtime.json \
    --source input/demo.mp4 \
    --host 0.0.0.0 \
    --port 8000

Im Browser im selben Netzwerk folgende Adresse öffnen:

http://<PI_IP>:8000

Das Dashboard zeigt den annotierten Videostream, Inferenz-FPS, sichtbare Schlaglochanzahl, kumulative Ereignisanzahl und Framenummer.

Projekt beziehen

git clone https://github.com/Seeed-Projects/reComputer-AI-Lab-Project.git
cd reComputer-AI-Lab-Project

Ausführung auf Raspberry Pi OS

Board-Abhängigkeiten installieren und Python-Virtual-Environment erstellen:

cd pi_project/pothole_detection
chmod +x scripts/*.sh
./scripts/install_rpi5.sh

Das Installationsskript prüft aarch64 und Python 3.11, installiert Systempakete, erstellt ein .venv mit --system-site-packages, installiert fastapi und uvicorn per pip und installiert HailoRT aus dem mitgelieferten lokalen Wheel — ohne Internet-Download oder Versions-Upgrade. Nach der Installation bei neu installiertem Hailo-PCIe-Treiber neu starten. Anschließend Beschleuniger und Modelle validieren:

./scripts/probe.sh
python3 tools/check_deployment.py

Browser-Dashboard mit mitgeliefertem Video starten:

python3 web_detection.py \
  --config configs/runtime.json \
  --source input/demo.mp4

Für ein verarbeitetes MP4 ohne Web-Dashboard:

./scripts/run_demo.sh

Das Ergebnis wird unter outputs/pothole_demo_hailo8.mp4 gespeichert, begleitet von einem .json-Bericht mit Frame-Anzahl, FPS und Erkennungsstatistiken.

Container aus dem Quellcode bauen

Das Repository enthält das Dockerfile und das passende HailoRT 4.23.0 Python 3.11 aarch64-Wheel. Image vom Repository-Stammverzeichnis bauen:

sudo docker build \
  -f docker/hailo8/pothole_detection.dockerfile \
  -t pothole_detection:latest \
  pi_project/pothole_detection

Wenn HailoRT unter einem anderen Host-Pfad installiert ist, passen Sie die beiden gemeinsamen Bibliotheksmounts an und halten Sie Host- und Container-Version kompatibel.

Web-API

• GET /: Browser-Dashboard mit Live-MJPEG-Stream und Metriken
• GET /api/video_feed: MJPEG-annotierter Videostream
• GET /api/status: JSON mit FPS, Schlaglochanzahl, kumulativen Ereignissen und Fehlerstatus
• GET /healthz: Dienst- und Inferenz-Gesundheitsprüfung

Nur die Konfiguration validieren

Mit --check-config werden Pfade und Konfigurationsstruktur ohne HailoRT-Prüfung geprüft:

cd pi_project/pothole_detection
python3 app/infer_video_hailo.py --check-config
python3 web_detection.py --check-config

Konfigurationsparameter

configs/runtime.json steuert das gesamte Laufzeitverhalten:

Kommandozeilen-Overrides: --source, --output, --confidence, --iou.

Anderes Video verwenden

configs/runtime.json aktualisieren, um einen anderen Ein- und Ausgabepfad zu wählen, oder --source über die Kommandozeile übergeben. Für eine Live-Kamera --source 0 verwenden.

Projektstruktur

pi_project/pothole_detection/
├── app/                 # Video-Inferenz-Einstiegspunkt
├── configs/             # Modell- und Laufzeitkonfiguration
├── input/               # Mitgeliefertes Demovideo
├── models/hef/          # Hailo-8-HEF-Modell
├── pothole_monitor/     # Frame-Prozessor und zeitlicher Tracker
├── runtime/             # HailoRT-Integration und YOLO-Nachverarbeitung
├── scripts/             # Installations-, Prüf-, Docker- und Demo-Skripte
├── tools/               # Bereitstellungs-Validierungswerkzeuge
├── tests/               # Hardware-freie Unit-Tests
└── web_detection.py     # FastAPI-Dashboard und MJPEG-Stream