YOLOv8 real-time inferentie CPP-project met reComputer RK3576

基于 RK3576 / RKNN / MPP / RGA / ZLMediaKit 的多源输入、多流输出 YOLOv8 实时推理项目。

当前项目支持：

• V4L2 摄像头输入
• RTSP 网络视频流输入
• localvideo 本地视频文件循环输入
• 三路 RTSP 输出流：主流 / 子流 / AI 调试流
• YOLOv8 RKNN 推理、边界框叠加、类别标签、时间与 FPS 叠加显示
• 优先使用 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 可同时输出任意单路、双路或三路全部流

• 分辨率策略

• camera 主流：等比缩放 + 填充（无拉伸）

• camera_sub 子流：等比缩放 + 中心裁剪（无拉伸）

• camera_ai AI 调试流：等比缩放 + 填充（无拉伸）

• AI 推理

• 固定输入 640x640

• 优先使用 RGA letterbox 进行预处理

• 支持检测缓存、PTS 匹配、AI 叠加

部署指南

依赖项

• RK3576 开发板运行时环境
• RKNN Runtime
• 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>：性能输出周期
• --detail-info：启用详细日志
• --help：打印帮助信息

性能指标含义

• 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
• 当前支持三种几何策略：
  • 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. 添加真正的全链路 pipeline_e2e 指标，与当前分支 e2e 区分开
3. 改进 localvideo 场景下的播放节奏控制，使其更接近实时源
4. 为主/子码流添加更多独立的编码参数配置能力
5. 如需更复杂的输入类型，继续扩展 source 抽象层