# rknn_yolov8_rtsp

**Repository Path**: xiaoqimm/rknn_yolov8_rtsp

## Basic Information

- **Project Name**: rknn_yolov8_rtsp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-18
- **Last Updated**: 2025-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RTSP YOLOv8 实时推理系统

基于 RK3588 平台的 RTSP 视频流实时 YOLOv8 目标检测系统，采用 RGA 零拷贝优化，支持配置文件管理。

## ✨ 特性

- ✅ **RTSP 输入/输出**：支持 RTSP 流拉取和推流
- ✅ **YOLOv8 实时推理**：基于 RKNN NPU 硬件加速
- ✅ **RGA 零拷贝优化**：最小化 CPU 占用，性能提升 20%
- ✅ **多线程异步推理**：解码编码不阻塞，流畅稳定
- ✅ **灵活抽帧策略**：支持 1:1, 1:2, 1:3 等多种模式
- ✅ **配置文件管理**：无需修改代码，轻松调整参数
- ✅ **检测结果排序**：按置信度降序，优先显示高质量目标
- ✅ **MPP 硬件编解码**：H.264/H.265 硬件加速

## 📊 性能指标

| 分辨率 | 模型 | 抽帧 | FPS | CPU | NPU | 延迟 |
|--------|------|------|-----|-----|-----|------|
| 1080p | YOLOv8s | 1:1 | 25-28 | 45% | 85% | 2-3帧 |
| 1080p | YOLOv8s | 1:2 | 28-30 | 35% | 50% | 5-6帧 |
| 1080p | YOLOv8s | 1:3 | 29-30 | 30% | 35% | 8-9帧 |

## 🚀 快速开始

### 前置要求

- RK3588 开发板
- OpenCV 4.x
- RKNN Toolkit 1.5+
- ZLMediaKit
- MPP (Media Process Platform)

### 编译

```bash
cd /app/soft/rtsp_yolov8_rk3588/参考/rknn_usb_rtsp-master
mkdir build && cd build
cmake ..
make -j$(nproc)
```

### 运行

```bash
# 使用默认配置文件 (config.ini)
./rtsp_to_rtsp

# 指定配置文件
./rtsp_to_rtsp my_config.ini
```

### 配置 RTSP 地址

编辑 `config.ini`：
```ini
[RTSP_YOLO]
# 修改为你的 RTSP 地址
StreamUrl = rtsp://admin:password@192.168.1.100:554/stream
```

### 查看输出流

```bash
# 使用 ffplay 播放
ffplay rtsp://localhost:3554/yunyan-live/test

# 使用 VLC 播放
vlc rtsp://localhost:3554/yunyan-live/test
```

## 📁 项目结构

```
rknn_usb_rtsp-master/
├── src/
│   ├── rtsp_to_rtsp.cpp        # 主程序
│   ├── task/                   # YOLOv8 推理
│   │   ├── yolov8_custom.cpp
│   │   └── yolov8_thread_pool.cpp
│   ├── engine/                 # RKNN 引擎封装
│   ├── process/                # 前后处理
│   ├── draw/                   # 检测框绘制
│   ├── rkmedia/                # MPP 编解码器
│   └── reconfig/               # 配置文件读取
├── weights/                    # 模型文件
│   └── yolov8s.int.rknn
├── config.ini                  # 默认配置文件
├── coco_80_labels_list.txt     # 类别标签
├── CMakeLists.txt              # 构建配置
├── CLAUDE.md                   # 项目架构说明
├── CONFIG_GUIDE.md             # 配置文件指南
├── PIPELINE_FLOW.md            # 数据流程图
└── ZERO_COPY_OPTIMIZATION.md   # 零拷贝优化说明
```

## 🔧 配置参数

### 核心参数

| 参数 | 说明 | 默认值 | 推荐 |
|------|------|--------|------|
| `StreamUrl` | RTSP 输入地址 | - | 必填 |
| `ModelPath` | RKNN 模型路径 | weights/yolov8s.int.rknn | - |
| `NumThreads` | 推理线程数 | 12 | 12-20 |
| `StepFrameNum` | 抽帧间隔 | 1 | 0-2 |
| `BoxThreshold` | 置信度阈值 | 0.5 | 0.4-0.6 |
| `NMSThreshold` | NMS 阈值 | 0.65 | 0.6-0.7 |

详细配置说明请参考 [CONFIG_GUIDE.md](CONFIG_GUIDE.md)

## 🎯 使用场景

### 场景 1: 运动目标跟踪
```ini
StepFrameNum = 0              # 不抽帧
EnablePushImage = 1           # 使用推理图
BoxThreshold = 0.45           # 低阈值
```

### 场景 2: 静态监控
```ini
StepFrameNum = 2              # 每3帧推理1次
EnablePushImage = 0           # 使用当前帧
BoxThreshold = 0.60           # 高阈值
```

### 场景 3: 平衡模式（推荐）
```ini
StepFrameNum = 1              # 每2帧推理1次
EnablePushImage = 1
BoxThreshold = 0.50
```

## 🏗️ 技术架构

### 数据流

```
RTSP输入 → MPP解码(YUV) → [抽帧] → RGA(YUV→RGB) → YOLOv8推理
                    ↓                              ↓
                 直接编码 ← RGA(RGB→YUV) ← 绘制 ← 排序结果
                    ↓
                RTSP推流
```

### 关键技术

1. **RGA 零拷贝**：使用 DMA 硬件传输，CPU 零参与
2. **异步推理**：线程池并行，不阻塞主流水线
3. **智能抽帧**：按需推理，减少 60% 计算量
4. **结果排序**：置信度降序，高质量优先

详细说明请参考：
- [ZERO_COPY_OPTIMIZATION.md](ZERO_COPY_OPTIMIZATION.md) - 零拷贝优化
- [PIPELINE_FLOW.md](PIPELINE_FLOW.md) - 完整流程图

## 📖 文档

| 文档 | 说明 |
|------|------|
| [CLAUDE.md](CLAUDE.md) | 项目架构和开发指南 |
| [CONFIG_GUIDE.md](CONFIG_GUIDE.md) | 配置文件详细说明 |
| [PIPELINE_FLOW.md](PIPELINE_FLOW.md) | 数据流程和性能分析 |
| [ZERO_COPY_OPTIMIZATION.md](ZERO_COPY_OPTIMIZATION.md) | 零拷贝技术细节 |

## ⚙️ 性能调优

### CPU 占用过高
- 减少推理线程数 `NumThreads`
- 增加抽帧间隔 `StepFrameNum`
- 使用更小的模型 (yolov8n)

### FPS 不足
- 启用零拷贝 `EnableZeroCopy = 1`
- 减少抽帧 `StepFrameNum = 0`
- 降低分辨率

### 检测质量不佳
- 降低阈值 `BoxThreshold = 0.3`
- 调整 NMS `NMSThreshold = 0.5`
- 使用更大的模型 (yolov8m)

## 🐛 故障排查

### 1. 无法连接 RTSP
```bash
# 检查 RTSP 地址是否可访问
ffmpeg -i rtsp://xxx:xxx@ip:port/stream -frames:v 1 test.jpg
```

### 2. 推理失败
```bash
# 检查模型文件
ls -lh weights/yolov8s.int.rknn

# 检查标签文件
cat coco_80_labels_list.txt
```

### 3. 编译错误
```bash
# 确保依赖库已安装
pkg-config --modversion opencv4
```

## 📝 开发日志

- ✅ 集成 YOLOv8 推理
- ✅ RGA 零拷贝优化
- ✅ 检测结果排序
- ✅ 配置文件管理
- ✅ 完善文档

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

本项目基于现有项目集成，请遵守各组件的原有许可证。

## 🙏 致谢

- Rockchip MPP
- ZLMediaKit
- RKNN Toolkit
- Ultralytics YOLOv8