inteintegrity2026-08-18

在树莓派 5 与 Hailo-8 上进行路面坑洞检测

在树莓派 5 上使用 Hailo-8 加速运行 YOLOv8n HEF 模型检测路面坑洞，带道路区域 ROI 过滤、短时跟踪补框和浏览器 MJPEG 实时预览。

CVObject DetectionRoad SafetyGitHub

本项目在树莓派 5 上使用 Hailo-8 加速器运行编译为 Hailo HEF 格式的 YOLOv8n 模型，从视频中检测路面坑洞。既支持带标注输出的批量视频推理，也支持实时 MJPEG 网页预览（含 FPS、坑洞计数和累计事件计数）。道路区域 ROI 过滤器可抑制天空和人行道上的误检，短时跟踪器用黄色补框桥接短暂丢失的检测。

源代码：https://github.com/Seeed-Projects/reComputer-AI-Lab-Project/tree/main/pi_project/pothole_detection

功能

  • 在树莓派 5 上使用 Hailo-8 加速 YOLOv8n 推理
  • 单类别坑洞检测，配合 Hailo NMS 后处理
  • 道路区域 ROI 梯形过滤，剔除非道路区域的检测
  • 短时跟踪补框（黄色框，最多容忍 3 帧丢失）
  • 独立坑洞轨迹的累计事件计数
  • 批量视频推理，叠加 FPS 和置信度标签
  • 基于浏览器的 MJPEG 预览和状态 API（8000 端口）
  • 内置演示视频、HEF 模型和设备验证工具
  • 支持裸机和 Docker 两种部署方式
  • 35 个无需硬件的单元测试（语法、配置、后处理）

硬件与软件

组件要求
主板树莓派 5，64 位 ARM (aarch64)
加速器Hailo-8 M.2 Key M 2280 (/dev/hailo0)
HailoRT4.23.0
Python3.11
裸机系统Raspberry Pi OS 64 位 Bookworm
容器运行时支持 arm64 的 Docker

宿主机驱动、固件、共享库和 Python 包必须使用互相兼容的 HailoRT 版本。内置 HEF 模型面向 Hailo-8，而非 Hailo-8L。

模型信息

属性值
架构YOLOv8n
类别1（pothole）
输入尺寸640 × 640 RGB
输入模式uint8（量化）
输出Hailo NMS（YXYX 坐标 + 置信度）
HEF SHA-2566acec07e677cf4ae54919e0dd7105799ea8a50f1f48bd72528a6550b611b6856

框颜色说明

颜色含义
橙色Hailo 直接检测（带置信度标签）
黄色跟踪补框——本帧检测丢失，由前几帧桥接

跟踪器为每个坑洞分配唯一 ID。当检测短暂丢失（如运动模糊）时，黄色框会桥接空档以避免闪烁。连续丢失超过 max_missed（默认 3 帧）后，该轨迹被移除。

Docker 快速启动

从 GHCR 拉取预构建的 linux/arm64 镜像：

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

运行内置视频和网页仪表板：

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

在同一网络的浏览器中打开：

text
http://<PI_IP>:8000

仪表板显示标注视频流、推理 FPS、可见坑洞数、累计事件数和帧号。

获取项目

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

在 Raspberry Pi OS 上运行

安装板卡依赖并创建 Python 虚拟环境：

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

安装脚本会检查 aarch64 和 Python 3.11，安装系统包，创建带 --system-site-packages 的 .venv，从 pip 安装 fastapi 和 uvicorn，并从本地捆绑的 wheel 安装 HailoRT——无需联网下载或版本升级。安装完成后，若新装了 Hailo PCIe 驱动请重启。然后验证加速器和模型：

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

用内置视频启动浏览器仪表板：

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

不需要网页仪表板、想直接生成处理后的 MP4 时，运行：

bash
./scripts/run_demo.sh

处理结果保存为 outputs/pothole_demo_hailo8.mp4，附带 .json 报告（帧数、FPS、检测统计）。

从源码构建容器

仓库包含 Dockerfile 和配套的 HailoRT 4.23.0 Python 3.11 aarch64 wheel。在仓库根目录构建镜像：

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

若宿主机的 HailoRT 安装在其他路径，请调整两个共享库挂载点，并保持宿主机与容器版本兼容。

Web API

  • GET /：浏览器仪表板，实时 MJPEG 流和指标
  • GET /api/video_feed：MJPEG 标注视频流
  • GET /api/status：JSON（FPS、坑洞数、累计事件、错误状态）
  • GET /healthz：服务和推理健康检查

仅验证配置

使用 --check-config 在不加载 HailoRT 的情况下检查路径和配置结构：

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

配置参数

configs/runtime.json 控制全部运行时行为：

配置节键默认值说明
modelpathmodels/hef/pothole_yolov8n_hailo8.hefHEF 模型路径
modelimgsz640输入尺寸（须与 HEF 一致）
modelconfidence0.18最小检测置信度
modeliou0.55NMS IoU 阈值
road_roienabledtrue启用道路区域过滤
road_roihorizon_y0.18地平线（道路区域顶部）
temporalmax_missed3移除轨迹前允许的最大连续丢失帧数
temporalmin_hits2显示轨迹前的最小命中数

命令行覆盖参数：--source、--output、--confidence、--iou。

使用其他视频

修改 configs/runtime.json 选择其他输入输出路径，或在命令行传 --source。接实时摄像头时用 --source 0。

项目结构

text
pi_project/pothole_detection/
├── app/                 # 视频推理入口
├── configs/             # 模型与运行时配置
├── input/               # 内置演示视频
├── models/hef/          # Hailo-8 HEF 模型
├── pothole_monitor/     # 帧处理器与短时跟踪器
├── runtime/             # HailoRT 集成与 YOLO 后处理
├── scripts/             # 安装、探测、Docker、演示脚本
├── tools/               # 部署验证工具
├── tests/               # 无需硬件的单元测试
└── web_detection.py     # FastAPI 仪表板与 MJPEG 流