Détection de nids-de-poule avec Raspberry Pi 5 et Hailo-8

Ce projet détecte les nids-de-poule de la chaussée depuis une vidéo à l'aide d'un modèle YOLOv8n compilé au format HEF de Hailo et accéléré par un Hailo-8 sur un Raspberry Pi 5. Il offre à la fois l'inférence vidéo par lots avec sortie annotée et une prévisualisation web MJPEG en temps réel affichant les FPS, le compteur de nids-de-poule et le compteur cumulé d'événements. Un filtre ROI de zone routière supprime les faux positifs du ciel et des trottoirs, tandis qu'un suivi temporel comble les brèves lacunes de détection avec des boîtes jaunes de comblement.

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

Fonctionnalités

Inférence YOLOv8n accélérée par Hailo-8 sur Raspberry Pi 5
Détection de nids-de-poule en classe unique avec post-traitement NMS de Hailo
Filtre ROI trapézoïdal de zone routière pour rejeter les détections hors chaussée
Suivi temporel avec comblement de brèves lacunes (boîtes jaunes, 3 images manquées maximum)
Compteur cumulé d'événements pour les pistes de nids-de-poule uniques
Inférence vidéo par lots avec incrustation FPS et étiquettes de confiance
Prévisualisation MJPEG dans le navigateur et API de statut sur le port 8000
Vidéo de démonstration, modèle HEF et outils de validation de l'appareil inclus
Options de déploiement bare-metal et Docker
35 tests unitaires sans matériel pour la syntaxe, la configuration et le post-traitement

Matériel et logiciel

Composant	Exigence
Carte	Raspberry Pi 5, ARM 64 bits (aarch64)
Accélérateur	Hailo-8 M.2 Key M 2280 (`/dev/hailo0`)
HailoRT	4.23.0
Python	3.11
OS bare-metal	Raspberry Pi OS Bookworm 64 bits
Runtime de conteneurs	Docker avec prise en charge arm64

Le pilote hôte, le micrologiciel, la bibliothèque partagée et le paquet Python doivent utiliser des versions HailoRT compatibles. Le modèle HEF inclus cible le Hailo-8, et non le Hailo-8L.

Informations sur le modèle

Propriété	Valeur
Architecture	YOLOv8n
Classes	1 (`pothole`)
Taille d'entrée	640 × 640 RVB
Mode d'entrée	uint8 (quantifié)
Sortie	Hailo NMS (coordonnées YXYX + confiance)
SHA-256 du HEF	`6acec07e677cf4ae54919e0dd7105799ea8a50f1f48bd72528a6550b611b6856`

Légende des couleurs des boîtes

Couleur	Signification
Orange	Détection directe Hailo (avec étiquette de confiance)
Jaune	Comblement de suivi — détection manquée sur cette image, comblée depuis les images précédentes

Le suivi attribue des identifiants uniques à chaque nid-de-poule. Lorsqu'une détection est brièvement perdue (p. ex. flou de mouvement), la boîte jaune comble la lacune pour éviter le scintillement. Après max_missed absences consécutives (3 par défaut), la piste est supprimée.

Démarrage rapide avec Docker

Récupérez l'image linux/arm64 préconstruite depuis GHCR :

bash

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

Exécutez la vidéo incluse et le tableau de bord web :

bash

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

Ouvrez l'adresse suivante depuis un navigateur sur le même réseau :

text

http://<PI_IP>:8000

Le tableau de bord affiche le flux vidéo annoté, les FPS d'inférence, le nombre de nids-de-poule visibles, le compteur cumulé d'événements et le numéro d'image.

Obtenir le projet

bash

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

Exécution sur Raspberry Pi OS

Installez les dépendances de la carte et créez un environnement virtuel Python :

bash

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

L'installateur vérifie aarch64 et Python 3.11, installe les paquets système, crée un .venv avec --system-site-packages, installe fastapi et uvicorn via pip et installe HailoRT depuis la roue locale incluse — sans téléchargement internet ni mise à niveau de version. Après l'installation, redémarrez si le pilote PCIe Hailo vient d'être installé. Validez ensuite l'accélérateur et les modèles :

bash

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

Démarrez le tableau de bord navigateur avec la vidéo incluse :

bash

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

Pour générer un MP4 traité sans le tableau de bord web, exécutez :

bash

./scripts/run_demo.sh

Le résultat est enregistré dans outputs/pothole_demo_hailo8.mp4, accompagné d'un rapport .json contenant le nombre d'images, les FPS et les statistiques de détection.

Construire le conteneur depuis les sources

Le dépôt contient le Dockerfile et la roue HailoRT 4.23.0 Python 3.11 aarch64 correspondante. Construisez l'image depuis la racine du dépôt :

bash

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

Si HailoRT est installé dans un autre chemin hôte, ajustez les deux montages de bibliothèques partagées en gardant les versions hôte et conteneur compatibles.

API web

GET / : tableau de bord navigateur avec flux MJPEG en direct et métriques
GET /api/video_feed : flux vidéo MJPEG annoté
GET /api/status : JSON avec FPS, nombre de nids-de-poule, événements cumulés et état d'erreur
GET /healthz : contrôle de santé du service et de l'inférence

Valider uniquement la configuration

Utilisez --check-config pour vérifier les chemins et la structure de configuration sans charger HailoRT :

bash

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

Paramètres de configuration

configs/runtime.json contrôle tout le comportement d'exécution :

Section	Clé	Défaut	Description
`model`	`path`	`models/hef/pothole_yolov8n_hailo8.hef`	Chemin du modèle HEF
`model`	`imgsz`	`640`	Dimension d'entrée (doit correspondre au HEF)
`model`	`confidence`	`0.18`	Confiance de détection minimale
`model`	`iou`	`0.55`	Seuil IoU NMS
`road_roi`	`enabled`	`true`	Activer le filtrage de zone routière
`road_roi`	`horizon_y`	`0.18`	Ligne d'horizon (haut de la zone routière)
`temporal`	`max_missed`	`3`	Images consécutives manquées max avant suppression de la piste
`temporal`	`min_hits`	`2`	Succès minimum avant affichage d'une piste

Paramètres de remplacement en ligne de commande : --source, --output, --confidence, --iou.

Utiliser une autre vidéo

Mettez à jour configs/runtime.json pour sélectionner un autre chemin d'entrée/sortie, ou passez --source en ligne de commande. Pour une caméra en direct, utilisez --source 0.

Structure du projet

text

pi_project/pothole_detection/
├── app/                 # Point d'entrée d'inférence vidéo
├── configs/             # Configuration du modèle et de l'exécution
├── input/               # Vidéo de démonstration incluse
├── models/hef/          # Modèle HEF Hailo-8
├── pothole_monitor/     # Processeur d'images et suivi temporel
├── runtime/             # Intégration HailoRT et post-traitement YOLO
├── scripts/             # Scripts d'installation, de sonde, Docker et démo
├── tools/               # Utilitaires de validation du déploiement
├── tests/               # Tests unitaires sans matériel
└── web_detection.py     # Tableau de bord FastAPI et flux MJPEG