Detección de baches en carreteras con Raspberry Pi 5 y Hailo-8

Este proyecto detecta baches en carreteras a partir de vídeo usando un modelo YOLOv8n compilado al formato HEF de Hailo y acelerado por un Hailo-8 en una Raspberry Pi 5. Ofrece tanto inferencia de vídeo por lotes con salida anotada como una previsualización web MJPEG en tiempo real con FPS, contador de baches y contador acumulado de eventos. Un filtro ROI de zona de carretera suprime los falsos positivos del cielo y la acera, mientras que un rastreador temporal salva breves huecos de detección con cajas amarillas de relleno.

Código fuente: https://github.com/Seeed-Projects/reComputer-AI-Lab-Project/tree/main/pi_project/pothole_detection

Funciones

Inferencia YOLOv8n acelerada por Hailo-8 en Raspberry Pi 5
Detección de baches de una sola clase con postprocesado NMS de Hailo
Filtro ROI trapezoidal de zona de carretera para rechazar detecciones ajenas a la calzada
Rastreador temporal con relleno de breves huecos (cajas amarillas, máx. 3 fotogramas perdidos)
Contador acumulado de eventos para pistas de baches únicas
Inferencia de vídeo por lotes con superposición de FPS y etiquetas de confianza
Previsualización MJPEG basada en navegador y API de estado en el puerto 8000
Vídeo de demostración, modelo HEF y herramientas de validación de dispositivo incluidos
Opciones de despliegue en metal desnudo y Docker
35 pruebas unitarias sin hardware para sintaxis, configuración y postprocesado

Hardware y software

Componente	Requisito
Placa	Raspberry Pi 5, ARM de 64 bits (aarch64)
Acelerador	Hailo-8 M.2 Key M 2280 (`/dev/hailo0`)
HailoRT	4.23.0
Python	3.11
SO en metal desnudo	Raspberry Pi OS Bookworm de 64 bits
Runtime de contenedores	Docker con soporte arm64

El controlador del host, el firmware, la biblioteca compartida y el paquete de Python deben usar versiones compatibles de HailoRT. El modelo HEF incluido está dirigido a Hailo-8, no a Hailo-8L.

Información del modelo

Propiedad	Valor
Arquitectura	YOLOv8n
Clases	1 (`pothole`)
Tamaño de entrada	640 × 640 RGB
Modo de entrada	uint8 (cuantizado)
Salida	Hailo NMS (coordenadas YXYX + confianza)
HEF SHA-256	`6acec07e677cf4ae54919e0dd7105799ea8a50f1f48bd72528a6550b611b6856`

Leyenda de colores de las cajas

Color	Significado
Naranja	Detección directa de Hailo (con etiqueta de confianza)
Amarillo	Relleno de hueco por seguimiento — la detección se perdió en este fotograma y se salva desde fotogramas anteriores

El rastreador asigna identificadores únicos a cada bache. Cuando una detección se pierde brevemente (p. ej., por desenfoque de movimiento), la caja amarilla salva el hueco para evitar el parpadeo. Tras max_missed fallos consecutivos (por defecto 3), la pista se elimina.

Inicio rápido con Docker

Descargue la imagen linux/arm64 preconstruida de GHCR:

bash

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

Ejecute el vídeo incluido y el panel 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

Abra la siguiente dirección desde un navegador en la misma red:

text

http://<PI_IP>:8000

El panel muestra el flujo de vídeo anotado, los FPS de inferencia, el número de baches visibles, el contador acumulado de eventos y el número de fotograma.

Obtener el proyecto

bash

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

Ejecución en Raspberry Pi OS

Instale las dependencias de la placa y cree un entorno virtual de Python:

bash

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

El instalador comprueba aarch64 y Python 3.11, instala los paquetes del sistema, crea un .venv con --system-site-packages, instala fastapi y uvicorn desde pip e instala HailoRT desde el wheel local incluido, sin descargas de internet ni actualizaciones de versión. Tras la instalación, reinicie si el controlador PCIe de Hailo se instaló por primera vez. Luego verifique el acelerador y los modelos:

bash

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

Inicie el panel del navegador con el vídeo incluido:

bash

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

Para generar un MP4 procesado sin el panel web, ejecute:

bash

./scripts/run_demo.sh

El resultado se guarda en outputs/pothole_demo_hailo8.mp4 junto con un informe .json con el número de fotogramas, los FPS y las estadísticas de detección.

Construir el contenedor desde el código fuente

El repositorio incluye el Dockerfile y el wheel de HailoRT 4.23.0 Python 3.11 aarch64 correspondiente. Construya la imagen desde la raíz del repositorio:

bash

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

Si HailoRT está instalado en otra ruta del host, ajuste los dos montajes de bibliotecas compartidas manteniendo compatibles las versiones del host y del contenedor.

API web

GET /: panel del navegador con flujo MJPEG en vivo y métricas
GET /api/video_feed: flujo de vídeo MJPEG anotado
GET /api/status: JSON con FPS, número de baches, eventos acumulados y estado de error
GET /healthz: comprobación de salud del servicio y de la inferencia

Validar solo la configuración

Use --check-config para comprobar rutas y estructura de configuración sin cargar HailoRT:

bash

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

Parámetros de configuración

configs/runtime.json controla todo el comportamiento en tiempo de ejecución:

Sección	Clave	Predeterminado	Descripción
`model`	`path`	`models/hef/pothole_yolov8n_hailo8.hef`	Ruta del modelo HEF
`model`	`imgsz`	`640`	Dimensión de entrada (debe coincidir con el HEF)
`model`	`confidence`	`0.18`	Confianza mínima de detección
`model`	`iou`	`0.55`	Umbral IoU de NMS
`road_roi`	`enabled`	`true`	Activar el filtrado de zona de carretera
`road_roi`	`horizon_y`	`0.18`	Línea del horizonte (parte superior de la zona de carretera)
`temporal`	`max_missed`	`3`	Máx. de fotogramas perdidos consecutivos antes de eliminar la pista
`temporal`	`min_hits`	`2`	Aciertos mínimos antes de mostrar una pista

Parámetros de anulación por línea de comandos: --source, --output, --confidence, --iou.

Usar otro vídeo

Actualice configs/runtime.json para seleccionar otra ruta de entrada y salida, o pase --source en la línea de comandos. Para una cámara en vivo, use --source 0.

Estructura del proyecto

text

pi_project/pothole_detection/
├── app/                 # Punto de entrada de inferencia de vídeo
├── configs/             # Configuración del modelo y del entorno de ejecución
├── input/               # Vídeo de demostración incluido
├── models/hef/          # Modelo HEF de Hailo-8
├── pothole_monitor/     # Procesador de fotogramas y rastreador temporal
├── runtime/             # Integración de HailoRT y postprocesado YOLO
├── scripts/             # Scripts de instalación, sondeo, Docker y demostración
├── tools/               # Utilidades de validación del despliegue
├── tests/               # Pruebas unitarias sin hardware
└── web_detection.py     # Panel FastAPI y flujo MJPEG