基于 reComputer RK3576 的 YOLOv8 实时推理 C++ 项目

基于 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 运行时库或命令行工具

构建步骤

bash

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

运行前设置

bash

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

模型放置

将 RKNN 模型放置在：

text

model/
  yolov8n_rk3576.rknn
  yolov8s_rk3576.rknn
  yolov8m_rk3576.rknn

如果未显式提供 --model，程序将按以下顺序自动选择现有模型：

model/yolov8n_rk3576.rknn
model/yolov8s_rk3576.rknn
model/yolov8m_rk3576.rknn

使用方法

V4L2 摄像头输入

bash

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 输入

bash

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

本地视频循环输入

bash

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

详细日志

默认只打印启动摘要；要打印详细的运行时日志，请添加：

bash

--detail-info

导出 NPU 输入帧

bash

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

启用特定输出流

bash

--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

查看帮助

bash

./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：通过挂钟统计窗口计算的实际分支吞吐量

项目结构概览

text

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 当前基于压缩流读取链路，主要用于离线验证与循环推理

未来开发建议

继续降低 camera_ai 的 OSD CPU 开销，可考虑引入图块缓存或更高效的混合路径
添加真正的全链路 pipeline_e2e 指标，与当前分支 e2e 相区分
改进 localvideo 场景下的播放节奏控制，使其更接近实时源
为主/子码流增加更多独立的编码参数配置能力
若需要更复杂的输入类型，继续扩展 source 抽象层