# web_detection

**Repository Path**: genvex/web_detection

## Basic Information

- **Project Name**: web_detection
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RDK X5 USB摄像头实时目标检测系统

基于RDK X5嵌入式AI平台的实时目标检测系统，使用YOLOv8模型进行目标检测，通过Web界面实时展示检测结果。

[![Python](https://img.shields.io/badge/Python-3.10-blue.svg)](https://www.python.org/)
[![RDK X5](https://img.shields.io/badge/Hardware-RDK%20X5-brightgreen.svg)](https://www.d-robotics.cc/)
[![YOLOv8](https://img.shields.io/badge/Model-YOLOv8n-orange.svg)](https://github.com/ultralytics/ultralytics)
[![FPS](https://img.shields.io/badge/Performance-100%2B%20FPS-success.svg)](https://www horizon.ai/)

---

## 📋 目录

- [项目概述](#项目概述)
- [功能特性](#功能特性)
- [系统要求](#系统要求)
- [快速开始](#快速开始)
- [详细使用说明](#详细使用说明)
- [技术架构](#技术架构)
- [性能指标](#性能指标)
- [常见问题](#常见问题)
- [项目结构](#项目结构)
- [许可证](#许可证)

---

## 🎯 项目概述

本项目是一个完整的边缘AI目标检测解决方案，展示了如何在RDK X5嵌入式平台上实现高性能的实时目标检测。系统采用YOLOv8n轻量级模型，利用BPU（Brain Processing Unit）硬件加速，实现了100+ FPS的实时检测能力。

### 核心亮点

- ⚡ **高性能**: 100+ FPS实时检测，远超CPU方案
- 🌐 **Web可视化**: 简洁美观的Web界面，支持多设备访问
- 🔧 **易于部署**: 一键启动脚本，开箱即用
- 📊 **完整文档**: 包含技术报告、实现原理、结果分析

---

## ✨ 功能特性

### 1. 实时目标检测
- 支持COCO数据集80个类别
- YOLOv8n模型，仅需3.5MB
- BPU硬件加速，推理延迟<11ms
- 自动保存检测结果图片

### 2. Web可视化界面
- 实时视频流显示
- FPS和目标数量统计
- 检测结果列表展示
- 每2秒自动刷新

### 3. 系统监控
- 内存占用监控
- CPU/BPU利用率显示
- 网络带宽统计
- 运行日志记录

### 4. 灵活配置
- 可调节置信度阈值
- 支持多种摄像头分辨率
- Web端口可自定义
- 输出路径可配置

---

## 💻 系统要求

### 硬件要求

| 组件 | 最低配置 | 推荐配置 |
|------|---------|---------|
| 开发板 | RDK X5 | RDK X5 (10TOPS BPU) |
| 摄像头 | USB摄像头 640x480 | USB HD Camera 640x480@30fps |
| 存储 | 4GB RAM | 8GB RAM |
| 网络 | 局域网连接 | 稳定网络连接 |

### 软件要求

```bash
# 操作系统
Ubuntu 22.04 LTS (ARM64)

# Python环境
Python 3.10
pip3 install opencv-python numpy scipy

# 必需库
hbm_runtime (Horizon BPU Runtime)
utils (预处理器工具包)
```

### 环境验证

```bash
# 检查Python版本
python3 --version  # 应显示 Python 3.10.x

# 检查摄像头设备
ls -l /dev/video*  # 应显示 /dev/video0, /dev/video1

# 检查BPU运行时
ls -la /usr/local/lib/python3.10/dist-packages/hbm_runtime.py
```

---

## 🚀 快速开始

### 第一步：克隆项目

```bash
# 克隆到本地
git clone https://github.com/yourusername/rdk-x5-web-detection.git
cd rdk-x5-web-detection

# 或使用内部GitLab
git clone http://gitee.com/genvex/rdk-x5-web-detection.git
cd rdk-x5-web-detection
```

### 第二步：安装依赖

```bash
# 进入项目目录
cd /home/sunrise/project/web_detection

# 设置环境变量
export PYTHONPATH=/usr/local/lib/python3.10/dist-packages:$PYTHONPATH

# 验证环境
python3 -c "import cv2, numpy, hbm_runtime; print('环境OK')"
```

### 第三步：启动服务

```bash
# 方法1：使用启动脚本（推荐）
./start.sh

# 方法2：直接运行
python3 main.py
```

### 第四步：访问界面

在浏览器中打开：
```
http://192.168.199.129:8080
```

### 第五步：测试检测

1. 打开摄像头盖子（如果有的话）
2. 走到摄像头前或挥动手臂
3. 观察Web界面显示检测结果
4. 查看保存的检测图片：`/tmp/web_detection/`

---

## 📖 详细使用说明

### 启动服务

```bash
# 启动服务
./start.sh

# 输出示例
======================================================================
🎯 RDK X5 USB摄像头实时目标检测系统 v1.2
======================================================================
📅 时间: 2026-08-24 18:50:00
======================================================================

📦 加载YOLOv8模型...
✅ 模型加载成功
   - 输入尺寸: 640x640
   - 模型大小: 3.45MB

📷 打开USB摄像头...
✅ 摄像头打开成功
   - 分辨率: 640x480

🚀 启动采集线程...
🌐 启动Web服务器...

======================================================================
✅ 系统就绪!
📱 Web界面: http://192.168.199.129:8080
📹 视频流:   http://192.168.199.129:8080/frame
======================================================================
💡 提示: 页面每2秒自动刷新，显示实时检测结果
```

### 访问接口

| 接口 | 说明 | 返回格式 |
|------|------|----------|
| `GET /` | Web界面主页 | HTML |
| `GET /frame` | 视频流 | JPEG图片 |
| `GET /info` | 检测数据 | JSON |
| `GET /stats` | 系统统计 | JSON |

### 检测数据格式

```json
{
  "fps": 107.96,
  "count": 2,
  "items": [
    {
      "class": "person",
      "class_id": 0,
      "score": 0.87,
      "box": [120, 50, 280, 420]
    },
    {
      "class": "chair",
      "class_id": 60,
      "score": 0.65,
      "box": [350, 200, 450, 380]
    }
  ],
  "time": "18:52:47"
}
```

### 停止服务

```bash
# 方法1：使用停止脚本
./stop.sh

# 方法2：手动停止
pkill -f "python.*main.py"

# 方法3：按Ctrl+C（如果在前台运行）
```

### 查看日志

```bash
# 查看运行日志
tail -f /tmp/web_detection.log

# 查看检测结果
ls -lh /tmp/web_detection/*.jpg

# 查看系统状态
curl -s http://localhost:8080/stats
```

---

## 🏗️ 技术架构

### 系统架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                        客户端 (浏览器)                               │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  HTML + CSS + JavaScript                                    │   │
│  │  ├─ 实时视频流显示                                           │   │
│  │  ├─ FPS和数据更新                                            │   │
│  │  └─ 自动刷新机制 (setInterval)                               │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                          │ HTTP请求                                 │
│                          ▼                                          │
├─────────────────────────────────────────────────────────────────────┤
│                        服务端 (RDK X5)                              │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    Web Server (HTTP)                          │   │
│  │  ├─ GET /           → HTML页面                               │   │
│  │  ├─ GET /frame      → JPEG视频流                             │   │
│  │  ├─ GET /info       → JSON检测数据                           │   │
│  │  └─ GET /stats      → 系统统计                               │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                          │                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    多线程处理层                                │   │
│  │  ├─ 采集线程 (Thread-1)                                       │   │
│  │  │   └─ cv2.VideoCapture读取摄像头帧                          │   │
│  │  ├─ 推理线程 (Thread-2)                                       │   │
│  │  │   └─ BPU执行YOLOv8模型推理                                 │   │
│  │  └─ Web线程 (Thread-3)                                        │   │
│  │      └─ 处理HTTP请求，返回数据                                 │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                          │                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    AI推理层                                   │   │
│  │  ├─ 预处理：BGR → NV12转换                                   │   │
│  │  ├─ 推理：HBM Runtime执行模型                                │   │
│  │  ├─ 后处理：网格格式解析，坐标转换                             │   │
│  │  └─ 可视化：绘制检测框、标签、统计信息                         │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                          │                                          │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                    硬件抽象层                                 │   │
│  │  ├─ V4L2 (Video4Linux2) - 摄像头驱动                          │   │
│  │  ├─ BPU Runtime - AI加速器接口                               │   │
│  │  └─ OpenCV - 图像处理库                                      │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
```

### 数据流程图

```
摄像头采集 → 图像预处理 → BPU推理 → 后处理 → 可视化 → Web推送
    │           │           │         │         │         │
    ▼           ▼           ▼         ▼         ▼         ▼
 640x480    640x640NV12   10ms     解析bbox   绘制框   HTTP响应
    │           │           │         │         │         │
    └───────────┴───────────┴─────────┴─────────┴─────────┘
                          循环处理
```

### 核心模块说明

#### 1. 摄像头采集模块 (`open_camera()`)
- 使用OpenCV的VideoCapture接口
- 支持V4L2摄像头设备
- 自动设置分辨率和帧率

#### 2. 图像预处理模块 (`preprocess_frame()`)
- 图像缩放至640x640
- BGR转NV12格式
- 内存优化处理

#### 3. AI推理模块 (`model.run()`)
- 使用Horizon BPU Runtime
- 模型加载到BPU内存
- 并行执行推理计算

#### 4. 后处理模块 (`postprocess_yolov8_grid()`)
- 解析网格格式输出
- 坐标转换和归一化
- 置信度过滤

#### 5. 可视化模块 (`process_frame()`)
- 绘制检测框
- 添加类别标签
- 显示统计信息

#### 6. Web服务模块 (`DetectionHandler`)
- 多线程HTTP服务器
- 实时视频流推送
- JSON数据接口

---

## 📊 性能指标

### 推理性能测试

```
┌─────────────────────────────────────────────────────────┐
│                   分辨率对比测试                          │
├──────────────┬──────────┬──────────┬──────────┤
│   分辨率      │ 推理时间  │   FPS    │ 适用场景  │
├──────────────┼──────────┼──────────┼──────────┤
│ 320x320      │  9.53ms  │ 104.9    │ 快速预览  │
│ 480x480      │  9.65ms  │ 103.6    │ 一般应用  │
│ 640x640      │ 10.32ms  │  96.9    │ 标准应用  │
│ 960x960      │  9.90ms  │ 101.0    │ 高性能    │
│ 1280x1280    │  9.97ms  │ 100.3    │ 高精度    │
└──────────────┴──────────┴──────────┴──────────┘
```

### 系统资源占用

```
┌─────────────────────────────────────────┐
│            资源占用统计                   │
├─────────────────────────────────────────┤
│  CPU占用:     < 15%                      │
│  内存占用:    ~100 MB                    │
│  BPU占用:     ~80%                       │
│  网络带宽:    < 200 Kbps                 │
│  存储占用:    3.5 MB (模型)              │
└─────────────────────────────────────────┘
```

### 与CPU方案对比

```
┌──────────────┬──────────┬──────────┬──────────┐
│    平台       │ 推理时间  │   FPS    │  功耗    │
├──────────────┼──────────┼──────────┼──────────┤
│  ARM CPU     │  175 ms  │   5.7    │   15W    │
│  BPU加速     │   11 ms  │  100+    │    5W    │
│  性能提升     │  16x     │  17x     │  3x      │
└──────────────┴──────────┴──────────┴──────────┘
```

---

## ❓ 常见问题

### Q1: 摄像头无法打开

**问题现象**: 启动时报错 `无法打开摄像头: /dev/video0`

**解决方案**:
```bash
# 1. 检查摄像头设备
ls -l /dev/video*

# 2. 检查摄像头权限
sudo chmod 666 /dev/video0

# 3. 重启摄像头驱动
sudo rmmod uvcvideo && sudo modprobe uvcvideo

# 4. 重新插拔摄像头
```

### Q2: 模型加载失败

**问题现象**: 启动时报错 `找不到模型文件`

**解决方案**:
```bash
# 1. 检查模型文件
ls -lh /opt/hobot/model/x5/basic/yolov8_640x640_nv12.bin

# 2. 检查Python路径
echo $PYTHONPATH
# 应包含: /usr/local/lib/python3.10/dist-packages

# 3. 重新设置环境变量
export PYTHONPATH=/usr/local/lib/python3.10/dist-packages:$PYTHONPATH
```

### Q3: Web界面无法访问

**问题现象**: 浏览器显示 `无法访问此网站`

**解决方案**:
```bash
# 1. 检查服务是否运行
ps aux | grep "python.*main.py"

# 2. 检查端口占用
netstat -tlnp | grep 8080

# 3. 检查防火墙
sudo iptables -L -n | grep 8080

# 4. 确认IP地址
ip addr show | grep "inet 192.168"
```

### Q4: 没有检测到目标

**问题现象**: 系统正常运行，但FPS显示0或检测数量为0

**原因分析**:
1. 摄像头盖子未打开
2. 画面中没有移动的人或物体
3. 检测阈值设置过高
4. 光照条件不佳

**解决方案**:
```python
# 1. 降低检测阈值
SCORE_THRESHOLD = 0.15  # 默认0.25

# 2. 检查摄像头画面
# 打开Web界面查看视频流是否正常

# 3. 确保有移动目标
# 走到摄像头前或挥动手臂
```

### Q5: 检测框不显示类别

**问题现象**: 只有检测框，没有类别标签

**解决方案**:
```bash
# 检查CLASS_NAMES列表是否完整
grep -A 20 "CLASS_NAMES" main.py

# 确保类别数量与模型输出匹配
```

### Q6: 性能下降

**问题现象**: FPS从100+下降到50以下

**解决方案**:
```bash
# 1. 检查系统负载
top -p $(pgrep -f main.py)

# 2. 检查温度
cat /sys/class/thermal/thermal_zone0/temp

# 3. 清理后台进程
pkill -f "other_process"

# 4. 重启服务
./stop.sh && ./start.sh
```

---

## 📂 项目结构

```
rdk-x5-web-detection/
│
├── web_detection/                    # 主程序目录
│   ├── main.py                       # 主程序（40KB）
│   ├── start.sh                      # 启动脚本
│   ├── stop.sh                       # 停止脚本
│   ├── test_performance.py           # 性能测试脚本
│   └── README.md                     # 使用说明
│
├── docs/                             # 技术文档目录
│   ├── technical_report.md          # 技术报告 (11KB)
│   ├── implementation.md            # 实现原理 (12KB)
│   ├── results_analysis.md          # 结果分析 (12KB)
│   └── SUMMARY.md                   # 项目总结
│
├── README.md                         # 本文件
├── LICENSE                           # 许可证
└── .gitignore                        # Git忽略文件
```

### 文件说明

| 文件 | 大小 | 说明 |
|------|------|------|
| `main.py` | 40KB | 主程序，包含所有核心功能 |
| `start.sh` | 1.2KB | 启动脚本，设置环境并运行 |
| `stop.sh` | 433B | 停止脚本，清理进程 |
| `test_performance.py` | 2.9KB | 性能测试，对比不同分辨率 |
| `technical_report.md` | 11KB | 完整技术报告 |
| `implementation.md` | 12KB | 实现原理详解 |
| `results_analysis.md` | 12KB | 测试结果分析 |

---

## 🔧 配置说明

### 主要配置项

编辑 `main.py` 文件，修改以下配置：

```python
# ==================== 配置 ====================
MODEL_PATH = '/opt/hobot/model/x5/basic/yolov8_640x640_nv12.bin'  # 模型路径
CAMERA_PATH = '/dev/video0'                                         # 摄像头设备
OUTPUT_DIR = '/tmp/web_detection'                                   # 输出目录
WEB_PORT = 8080                                                     # Web端口
SCORE_THRESHOLD = 0.25                                              # 检测阈值
```

### 环境变量

```bash
# Python路径（必需）
export PYTHONPATH=/usr/local/lib/python3.10/dist-packages:$PYTHONPATH

# 日志级别
export LOG_LEVEL=INFO

# 输出目录（可选）
export OUTPUT_DIR=/tmp/web_detection
```

---

## 🚀 高级用法

### 批量性能测试

```bash
# 运行性能测试
python3 test_performance.py

# 输出示例
======================================================================
RDK X5 性能测试 - 分辨率对比
======================================================================

测试 320x320... ✓ 104.9 FPS
测试 480x480... ✓ 103.6 FPS
测试 640x640... ✓ 96.9 FPS
...

======================================================================
性能测试结果:
分辨率             推理时间(ms)        FPS
----------------------------------------------------------------------
320x320         9.53            104.9
480x480         9.65            103.6
640x640         10.32           96.9
...
======================================================================
```

### 自定义检测类别

```python
# 修改CLASS_NAMES列表
CLASS_NAMES = [
    'person', 'car', 'dog', 'cat',  # 只保留需要的类别
    # ... 其他类别
]

# 修改模型输出解析
def postprocess_yolov8_grid(...):
    # 根据实际类别数量调整解析逻辑
    num_classes = len(CLASS_NAMES)
    ...
```

### 添加新的Web接口

```python
class DetectionHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        # 添加新接口
        if self.path.startswith('/custom'):
            self.send_response(200)
            self.send_header('Content-type', 'application/json')
            self.end_headers()
            self.wfile.write(json.dumps({'message': 'Custom endpoint'}).encode())
```

---

## 📚 相关资源

### 官方文档

- [RDK X5官方文档](https://wiki.d-robotics.com/)
- [Horizon BPU Runtime](https://developer.horizon.ai/)
- [YOLOv8官方仓库](https://github.com/ultralytics/ultralytics)

### 技术博客

- [边缘AI开发指南](https://zhuanlan.zhihu.com/p/...)
- [BPU加速原理](https://developer.horizon.ai/document/...)

---

## 👥 贡献指南

欢迎贡献代码、报告问题或提出建议！

### 贡献步骤

1. Fork本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建Pull Request

### 代码规范

- 使用PEP 8编码规范
- 添加必要的注释
- 保持代码简洁清晰
- 更新相关文档

---

## 📄 许可证

本项目采用MIT许可证 - 详见[LICENSE](LICENSE)文件。

---

## 🙏 致谢

- Horizon Robotics 提供的BPU开发板和技术支持
- Ultralytics 开源的YOLOv8模型
- D-Robotics 提供的硬件平台和文档

---

## 📮 联系方式

- 项目作者: Agnes AI
- 邮箱: agent@example.com
- GitHub: https://github.com/yourusername/rdk-x5-web-detection

---

**最后更新**: 2026-08-24  
**版本**: v1.2