inteintegrity2026-08-18

Raspberry Pi 5 と Hailo-8 による路面陥没検出

Raspberry Pi 5 上の Hailo-8 で YOLOv8n HEF モデルを加速し、路面の陥没を検出。道路領域 ROI フィルタ、短時間トラッキング補完、ブラウザ MJPEG ライブプレビューを備えます。

CVObject DetectionRoad SafetyGitHub

本プロジェクトは、Raspberry Pi 5 上の Hailo-8 アクセラレータで、Hailo HEF 形式にコンパイルした YOLOv8n モデルを実行し、映像から路面の陥没（ポットホール）を検出します。注釈付き出力のバッチ映像推論と、FPS・陥没数・累積イベント数を表示するリアルタイム MJPEG ウェブプレビューの両方を提供します。道路領域 ROI フィルタが空や歩道の誤検出を抑制し、短期トラッカーが黄色の補完ボックスで一時的な検出欠落を橋渡しします。

ソースコード：https://github.com/Seeed-Projects/reComputer-AI-Lab-Project/tree/main/pi_project/pothole_detection

機能

  • Raspberry Pi 5 上での Hailo-8 アクセラレーテッド YOLOv8n 推論
  • Hailo NMS 後処理による単一クラスの陥没検出
  • 道路領域 ROI 台形フィルタで非道路検出を排除
  • 短期ギャップ補完トラッカー（黄ボックス、最大 3 フレーム欠落許容）
  • 一意な陥没トラックの累積イベントカウンタ
  • FPS オーバーレイと信頼度ラベル付きバッチ映像推論
  • ポート 8000 でのブラウザベース MJPEG プレビューとステータス API
  • デモ映像、HEF モデル、デバイス検証ツール同梱
  • ベアメタルと Docker の両デプロイ方式
  • ハードウェア不要の 35 個のユニットテスト（構文・設定・後処理）

ハードウェアとソフトウェア

コンポーネント要件
ボードRaspberry Pi 5、64 ビット ARM (aarch64)
アクセラレータHailo-8 M.2 Key M 2280 (/dev/hailo0)
HailoRT4.23.0
Python3.11
ベアメタル OSRaspberry Pi OS 64 ビット Bookworm
コンテナランタイムarm64 対応 Docker

ホストドライバ、ファームウェア、共有ライブラリ、Python パッケージは互換性のある HailoRT バージョンを使用してください。同梱の HEF モデルは Hailo-8L ではなく Hailo-8 向けです。

モデル情報

項目値
アーキテクチャ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 に保存され、フレーム数・FPS・検出統計を含む .json レポートが付属します。

ソースからコンテナをビルド

リポジトリには 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 が別のホストパスにインストールされている場合は、2 つの共有ライブラリのマウントを調整し、ホストとコンテナのバージョンの互換性を保ってください。

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 ストリーム