Putgaten detectie met Raspberry Pi 5 en Hailo-8

Dit project detecteert putgaten in het wegdek vanuit video met een YOLOv8n-model gecompileerd naar het Hailo HEF-formaat, versneld door een Hailo-8 op een Raspberry Pi 5. Het biedt zowel batch-videoinferentie met geannoteerde uitvoer als een realtime MJPEG-webvoorbeeld met FPS, putgatenteller en cumulatieve teller. Een ROI-weggebiedfilter onderdrukt fout-positieven van lucht en stoep, terwijl een tijdelijke tracker korte detectiehiaten overbrugt met gele opvulboxen.

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

Functies

• Hailo-8-versnelde YOLOv8n-inferentie op Raspberry Pi 5
• Putgatdetectie met één klasse en Hailo NMS-naverwerking
• Trapeziumvormig ROI-weggebiedfilter om niet-wegdetecties te verwerpen
• Tijdelijke tracker met korte opvulling (gele boxen, max. 3 gemiste frames)
• Cumulatieve teller voor unieke putgattracks
• Batch-videoinferentie met FPS-overlay en betrouwbaarheidslabels
• Browsergebaseerd MJPEG-voorbeeld en status-API op poort 8000
• Inbegrepen demovideo, HEF-model en hulpmiddelen voor apparaatvalidatie
• Bare-metal- en Docker-implementatieopties
• 35 hardwarevrije unittests voor syntaxis, configuratie en naverwerking

Hardware en software

De hostdriver, firmware, gedeelde bibliotheek en het Python-pakket moeten compatibele HailoRT-versies gebruiken. Het inbegrepen HEF-model is bedoeld voor Hailo-8, niet voor Hailo-8L.

Modelinformatie

Kleurlegenda van de boxen

De tracker wijst unieke ID's toe aan elk putgat. Gaat een detectie kort verloren (bijv. door bewegingsonscherpte), dan overbrugt de gele box het gat om flikkering te voorkomen. Na max_missed opeenvolgende missers (standaard 3) wordt de track verwijderd.

Snelstart met Docker

Haal de voorgebouwde linux/arm64-image van GHCR:

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

Draai de meegeleverde video en het webdashboard:

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

Open het volgende adres in een browser op hetzelfde netwerk:

http://<PI_IP>:8000

Het dashboard toont de geannoteerde videostream, inferentie-FPS, zichtbaar aantal putgaten, cumulatief aantal gebeurtenissen en framenummer.

Het project ophalen

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

Draaien op Raspberry Pi OS

Installeer de boardafhankelijkheden en maak een virtuele Python-omgeving:

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

Het installatiescript controleert aarch64 en Python 3.11, installeert systeempakketten, maakt een .venv met --system-site-packages, installeert fastapi en uvicorn via pip en installeert HailoRT vanuit de meegeleverde lokale wheel — zonder internetdownload of versie-upgrade. Herstart na installatie als de Hailo PCIe-driver nieuw is geïnstalleerd. Valideer daarna de versneller en modellen:

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

Start het browserdashboard met de meegeleverde video:

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

Voor een verwerkte MP4 zonder het webdashboard:

./scripts/run_demo.sh

Het resultaat wordt opgeslagen als outputs/pothole_demo_hailo8.mp4, vergezeld van een .json-rapport met frameaantal, FPS en detectiestatistieken.

De container vanuit de broncode bouwen

De repository bevat de Dockerfile en de bijbehorende HailoRT 4.23.0 Python 3.11 aarch64-wheel. Bouw de image vanuit de hoofdmap van de repository:

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

Is HailoRT op een ander hostpad geïnstalleerd, pas dan de twee mounts van gedeelde bibliotheken aan en houd de host- en containerversies compatibel.

Web-API

• GET /: browserdashboard met live MJPEG-stream en statistieken
• GET /api/video_feed: geannoteerde MJPEG-videostream
• GET /api/status: JSON met FPS, putgataantal, cumulatieve gebeurtenissen en foutstatus
• GET /healthz: gezondheidscontrole van service en inferentie

Alleen de configuratie valideren

Gebruik --check-config om paden en configuratiestructuur te controleren zonder HailoRT te laden:

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

Configuratieparameters

configs/runtime.json bepaalt het volledige runtimegedrag:

Commandoregel-overrides: --source, --output, --confidence, --iou.

Een andere video gebruiken

Werk configs/runtime.json bij om een ander invoer-/uitvoerpad te kiezen, of geef --source door op de commandoregel. Gebruik voor een live camera --source 0.

Projectstructuur

pi_project/pothole_detection/
├── app/                 # Toegangspunt videoinferentie
├── configs/             # Model- en runtimeconfiguratie
├── input/               # Meegeleverde demovideo
├── models/hef/          # Hailo-8 HEF-model
├── pothole_monitor/     # Frameprocessor en tijdelijke tracker
├── runtime/             # HailoRT-integratie en YOLO-naverwerking
├── scripts/             # Installatie-, probe-, Docker- en demoscripts
├── tools/               # Validatiehulpmiddelen voor implementatie
├── tests/               # Hardwarevrije unittests
└── web_detection.py     # FastAPI-dashboard en MJPEG-stream