reComputer RK3576 による YOLOv8 リアルタイム推論 C++ プロジェクト

RK3576 / RKNN / MPP / RGA / ZLMediaKit に基づく、マルチソース入力・マルチストリーム出力の YOLOv8 リアルタイム推論プロジェクトです。

現在のプロジェクトがサポートする機能:

• V4L2 カメラ入力
• RTSP ネットワークビデオ入力
• localvideo ローカルビデオファイルのループ入力
• 3つのRTSP出力ストリーム: メインストリーム / サブストリーム / AIデバッグストリーム
• YOLOv8 RKNN 推論、バウンディングボックス重畳、クラスラベル、時刻およびFPSのOSD
• libavformat を優先してRTSP/ローカル圧縮ストリーム入力に使用し、フォールバックとして ffmpeg pipe を使用

機能概要

• 入力ソース

• v4l2: USBカメラ、ローカルキャプチャに適す

• rtsp: IPC/NVR/ネットワークビデオストリームに適す

• localvideo: ローカルビデオ再生、オフライン検証、ループ推論に適す

• 出力ストリーム

• メインストリーム: rtsp://<board-ip>:8554/live/camera

• サブストリーム: rtsp://<board-ip>:8554/live/camera_sub

• AIデバッグストリーム: rtsp://<board-ip>:8554/live/camera_ai

• --streams main,sub,ai を使用して、任意の単一、二重、または3つのストリームを同時に出力

• 解像度戦略

• camera メインストリーム: 比例スケーリング + パディング (ストレッチなし)

• camera_sub サブストリーム: 比例スケーリング + 中央クロップ (ストレッチなし)

• camera_ai AIデバッグストリーム: 比例スケーリング + パディング (ストレッチなし)

• AI推論

• 固定入力 640x640

• 前処理に RGA letterbox を優先

• 検出キャッシュ、PTSマッチング、AIオーバーレイをサポート

デプロイガイド

依存関係

• RK3576 ボードランタイム環境
• RKNN ランタイム
• Rockchip MPP
• RGA / librga
• ZLMediaKit ランタイムライブラリ
• FFmpeg ランタイムライブラリまたはコマンドラインツール

ビルド手順

cd /home/parker/Projects/rk3576_yolov8tortsp_demo
chmod +x scripts/build-linux.sh
./scripts/build-linux.sh

ビルド出力:

• 実行ファイル: install/bin/rk3576_yolov8tortsp_demo
• ランタイムライブラリ: install/lib
• ドキュメント: install/docs
• モデルディレクトリ: install/model

実行前のセットアップ

cd install
export LD_LIBRARY_PATH="$(pwd)/lib:${LD_LIBRARY_PATH}"

モデルの配置

RKNNモデルを以下に配置します:

model/
  yolov8n_rk3576.rknn
  yolov8s_rk3576.rknn
  yolov8m_rk3576.rknn

--model が明示的に指定されない場合、プログラムは以下の順序で既存モデルを自動選択します:

1. model/yolov8n_rk3576.rknn
2. model/yolov8s_rk3576.rknn
3. model/yolov8m_rk3576.rknn

使用方法

V4L2 カメラ入力

sudo ./bin/rk3576_yolov8tortsp_demo \
  --source v4l2 \
  --device /dev/video0 \
  --model model/yolov8n_rk3576.rknn \
  --camera-width 1920 \
  --camera-height 1080 \
  --output-width 1280 \
  --output-height 720 \
  --fps 30 \
  --bitrate 4000000 \
  --perf-interval-ms 1000 \
  --rtsp-port 8554 \
  --rtsp-app live \
  --rtsp-stream camera

RTSP 入力

sudo ./bin/rk3576_yolov8tortsp_demo \
  --source rtsp \
  --rtsp-input-url "rtsp://192.168.100.101:554/live" \
  --rtsp-username "admin" \
  --rtsp-password "c32bdc3e" \
  --model model/yolov8n_rk3576.rknn \
  --camera-width 1920 \
  --camera-height 1080 \
  --output-width 1280 \
  --output-height 720 \
  --fps 30 \
  --bitrate 4000000 \
  --perf-interval-ms 1000 \
  --rtsp-timeout-ms 5000 \
  --rtsp-reconnect-ms 1000 \
  --rtsp-port 8554 \
  --rtsp-app live \
  --rtsp-stream camera

ローカルビデオループ入力

sudo ./bin/rk3576_yolov8tortsp_demo \
  --source localvideo \
  --localvideo ./videos/demo.mp4 \
  --model model/yolov8n_rk3576.rknn \
  --camera-width 1920 \
  --camera-height 1080 \
  --output-width 1280 \
  --output-height 720 \
  --fps 30 \
  --bitrate 4000000 \
  --perf-interval-ms 1000 \
  --rtsp-port 8554 \
  --rtsp-app live \
  --rtsp-stream camera

詳細ログ

デフォルトでは起動時のサマリーのみが表示されます。詳細なランタイムログを表示するには以下を追加します:

--detail-info

NPU入力フレームのエクスポート

sudo ./bin/rk3576_yolov8tortsp_demo \
  --source localvideo \
  --localvideo ./videos/demo.mp4 \
  --model model/yolov8n_rk3576.rknn \
  --streams ai \
  --dump-ai-input-dir ./debug_ai_input \
  --dump-ai-input-every 30 \
  --detail-info

特定の出力ストリームの有効化

--streams ai
--streams main,ai
--streams main,sub
--streams main,sub,ai

説明:

• --streams ai: AI推論のみを実行し camera_ai を出力
• --streams main,ai: メインストリームとAIデバッグストリームを出力
• --streams main,sub: 標準デュアルストリームのみ、RKNNモデルはロードしない
• 省略時はデフォルトで --streams main,sub,ai

ヘルプの表示

./bin/rk3576_yolov8tortsp_demo --help

API リファレンス

主要なコマンドライン引数

• --source <v4l2|rtsp|localvideo>: 入力ソースタイプ
• --device <path>: V4L2 デバイスノード
• --rtsp-input-url <url>: RTSP アドレス
• --rtsp-username <value>: RTSP ユーザー名
• --rtsp-password <value>: RTSP パスワード
• --localvideo <path>: ローカルビデオファイルパス
• --model <path>: RKNN モデルパス
• --camera-width <value> / --camera-height <value>: 入力解像度
• --output-width <value> / --output-height <value>: メインストリーム出力解像度
• --sub-width <value> / --sub-height <value>: サブストリーム出力解像度
• --fps <value>: ターゲットエンコードフレームレート
• --bitrate <value>: メインストリームターゲットビットレート
• --rtsp-port <value>: ローカルRTSPサーバーポート
• --rtsp-app <value>: RTSP アプリ名
• --rtsp-stream <value>: メインストリーム名
• --sub-stream <value>: サブストリーム名
• --ai-stream <value>: AIデバッグストリーム名
• --streams <items>: 有効化する出力ストリーム。main、sub、ai のコンマ区切り組み合わせをサポート
• --rtsp-timeout-ms <value>: RTSP 読み取りタイムアウト
• --rtsp-reconnect-ms <value>: RTSP 再接続間隔
• --perf-interval-ms <value>: PERF 出力周期
• --detail-info: 詳細ログを有効化
• --help: ヘルプを表示

PERF の意味

• process: ブランチ内の画像処理時間
• encode: MPP エンコード時間
• push: RTSP プッシュ時間
• e2e: ブランチ内の処理開始からプッシュ完了までの総時間
• fps: 実時間統計ウィンドウにより計算された実際のブランチスループット

プロジェクト構造の概要

rk3576_yolov8tortsp_demo
├── CMakeLists.txt
├── README.md
├── docs
├── include
│   ├── rk3576_demo
│   └── rk3576_yolo_demo
├── model
├── scripts
├── src
│   ├── ai          # RKNN inference and pre/post-processing
│   ├── app         # Application entry and orchestration
│   ├── branch      # 3-branch output, OSD, PERF
│   ├── camera      # V4L2 capture
│   ├── codec       # MPP encode/decode
│   ├── common      # Common types, logger, thread queues
│   ├── pipeline    # V2 distribution and processing pipeline
│   ├── rga         # Image scaling and conversion
│   ├── rtsp        # Local RTSP publishing
│   ├── source      # Input source abstraction and implementation
│   ├── utils
│   └── watermark   # Time/FPS/Label rendering
└── third_party

開発ガイド

1. 入力ソースの拡張

• 統一インターフェースは include/rk3576_yolo_demo/source/i_source.hpp
• ファクトリエントリは src/source/source_factory.cpp
• 新しい入力ソースは以下を実装する必要があります:
  • Open()
  • Close()
  • ReadPacket()
  • Describe()

2. ブランチ出力の拡張

• ブランチ実装は src/branch/branch_output.cpp にあります
• 現在、以下の3つのジオメトリ戦略をサポートしています:
  • stretch
  • letterbox
  • center_crop
• 幾何学的関係は ComputeFrameTransform() で統一的に計算され、出力スケーリングとAIボックスマッピングの再利用が容易です

3. AI推論の拡張

• RKNN エントリは src/ai/yolov8_engine.cpp
• 前処理は RGA を優先
• 検出結果は DetectionFrame キャッシュに入り、その後AIブランチが PTS マッチングに基づいてオーバーレイします

4. ログとデバッグ

• デフォルトでは起動時サマリーのみ出力
• 詳細なランタイムログは --detail-info で有効化
• ロガーは include/rk3576_yolo_demo/common/logger.hpp に配置

デプロイ推奨事項

• 本番環境へのデプロイでは、/dev/rga、ビデオデバイス、および関連するランタイムライブラリに対して適切な権限を設定してください
• モデル、ランタイムライブラリ、設定は install/ にまとめてパッケージ化することを推奨します
• RTSP入力は libavformat を優先し、古い環境では自動的に ffmpeg pipe にフォールバックします
• 長期安定運用には、systemdやsupervisorによるデーモン化と再起動管理を推奨します

既知の制限事項

• camera_ai の矩形描画とウォーターマークオーバーレイでは、依然として一部のCPU負荷が発生します
• e2e は完全なフルリンク遅延ではなく、ブランチ内での処理時間のみを表します
• localvideo は現在、圧縮ストリーム読み取り経路に基づいており、主にオフライン検証やループ推論に使用されます

将来の開発提案

1. camera_ai のOSDによるCPU負荷を継続的に低減し、タイルキャッシュやより効率的なブレンドパスを導入する可能性を検討
2. 現在のブランチ e2e とは異なる、真のフルリンク pipeline_e2e メトリクスを追加
3. localvideo シナリオでの再生ペース制御を改善し、リアルタイムソースに近づける
4. メインストリーム/サブストリームに対して、独立したエンコードパラメータ設定機能をさらに追加
5. より複雑な入力タイプが必要になった場合、source 抽象化レイヤの拡張を継続