README.md

# 单鼠姿态检测WebRTC实时处理系统

## 🎯 项目简介

这是一个基于YOLOv8的单鼠姿态检测WebRTC实时处理系统，支持8个关键点检测，提供完整的WebSocket和REST API接口，专为实时视频流处理和前端集成设计。

### 🌟 核心特性

- ✅ **实时姿态检测**: 8个关键点精准识别 (鼻子、左耳、右耳、躯干、左腿、右腿、尾巴根部、尾巴尖)
- ✅ **WebRTC流处理**: 支持30+ FPS实时视频流处理
- ✅ **双服务架构**: Gradio可视化界面 + FastAPI RESTful服务
- ✅ **多客户端支持**: WebSocket连接管理，支持并发处理
- ✅ **完整API**: REST API + WebSocket + 批量处理
- ✅ **GPU/CPU自适应**: 自动检测和使用最佳计算设备
- ✅ **前端友好**: 标准协议，易于集成各种前端框架

## 📁 项目结构

```
single_mouse_webrtc_project/
├── README.md                      # 项目主文档
├── API对接文档.md                  # 详细API对接文档
├── README_Gradio_WebRTC.md         # WebRTC技术文档
├── PROJECT_CHECKLIST.md            # 部署检查清单
├── requirements_gradio_webrtc.txt  # Python依赖文件
├── deploy.sh                       # 自动部署脚本
├── start_gradio_webrtc.py          # 服务启动管理器
├── gradio_webrtc_server.py         # Gradio WebRTC服务器
├── gradio_webrtc_api.py            # FastAPI REST服务器
├── test_gradio_webrtc_client.py    # 完整测试客户端
├── check_model.py                  # 模型检查脚本
├── inspect_model.py                # 模型详细检查脚本
├── create_test_image.py            # 测试图像生成脚本
├── test_mouse.jpg                  # 测试用小鼠图像
└── models/                         # 模型文件目录
    └── kunin-mice-pose.v0.1.5n.pt  # YOLOv8姿态检测模型
```

## 🚀 快速启动

### 方法1: 自动部署 (推荐)

```bash
# 进入项目目录
cd single_mouse_webrtc_project

# 运行自动部署脚本
./deploy.sh
```

### 方法2: 手动部署

```bash
# 1. 创建Python虚拟环境
conda create -n mouse-webrtc python=3.11
conda activate mouse-webrtc

# 2. 安装依赖
pip install -r requirements_gradio_webrtc.txt

# 3. 检查模型
python check_model.py

# 4. 启动服务
python start_gradio_webrtc.py
```

### 服务地址

启动成功后，您将看到以下服务地址：

- **Gradio界面**: http://localhost:7860
- **API服务**: http://localhost:8765
- **WebSocket流**: ws://localhost:8765/ws/stream
- **API文档**: http://localhost:8765/docs

### 测试验证

```bash
# 运行完整测试套件
python test_gradio_webrtc_client.py
```

## 📡 API使用示例

### WebSocket实时流处理

```javascript
const ws = new WebSocket('ws://localhost:8765/ws/stream');

ws.onopen = () => console.log('WebSocket连接成功');

// 发送图像帧
function sendFrame(imageBase64) {
    const frameData = {
        image: imageBase64,
        conf_threshold: 0.3,
        frame_id: Date.now(),
        timestamp: Date.now() / 1000
    };
    ws.send(JSON.stringify(frameData));
}

// 接收检测结果
ws.onmessage = (event) => {
    const result = JSON.parse(event.data);
    if (result.success && result.mouse_detected) {
        console.log('检测到小鼠:', result.keypoints.length, '个关键点');
        // 处理检测结果...
    }
};
```

### REST API单帧处理

```javascript
// 处理单张图像
fetch('http://localhost:8765/api/process_frame', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        image: imageBase64,
        conf_threshold: 0.3
    })
})
.then(response => response.json())
.then(result => {
    console.log('检测结果:', result);
});
```

## 🎯 关键点说明

系统检测8个关键点：

| 索引 | 名称 | 描述 |
|------|------|------|
| 0 | nose | 鼻子 |
| 1 | left_ear | 左耳 |
| 2 | right_ear | 右耳 |
| 3 | torso | 躯干 |
| 4 | left_leg | 左腿 |
| 5 | right_leg | 右腿 |
| 6 | tail_base | 尾巴根部 |
| 7 | tail_tip | 尾巴尖 |

## 📊 性能指标

- **处理速度**: 30+ FPS (GPU) / 6-15 FPS (CPU)
- **检测精度**: 置信度阈值可调 (默认0.3)
- **延迟**: < 50ms (本地处理)
- **并发连接**: 支持多客户端同时连接
- **内存占用**: ~2GB (GPU) / ~1GB (CPU)

## 🛠️ 故障排除

### 常见问题

1. **模型加载失败**
   ```bash
   # 检查模型文件
   ls -la models/
   python check_model.py
   ```

2. **端口占用**
   ```bash
   # 检查端口使用情况
   lsof -i :7860
   lsof -i :8765
   ```

3. **依赖缺失**
   ```bash
   # 重新安装依赖
   pip install -r requirements_gradio_webrtc.txt
   ```

4. **GPU不可用**
   ```bash
   # 检查CUDA环境
   python -c "import torch; print(torch.cuda.is_available())"
   ```

### 调试模式

```bash
# 启用详细日志
export LOG_LEVEL=DEBUG
python start_gradio_webrtc.py
```

## 📚 文档说明

- **README.md**: 项目总体介绍和快速开始
- **API对接文档.md**: 详细的API使用指南，包含完整示例
- **README_Gradio_WebRTC.md**: WebRTC技术实现细节
- **PROJECT_CHECKLIST.md**: 部署检查清单

## 🔗 集成指南

### 前端集成

本系统专为前端集成设计，支持：

- **纯HTML/JavaScript**: 直接使用WebSocket连接
- **React.js/Vue.js**: 组件化集成
- **移动端**: 支持WebRTC标准协议
- **桌面应用**: Electron等框架兼容

详细集成示例请参考 `API对接文档.md`。

### 后端集成

- **Python**: 使用`websockets`库连接
- **Node.js**: 使用`ws`模块
- **其他语言**: 支持标准WebSocket协议

## 📄 许可证

本项目为内部使用，请确保模型文件和代码的合规使用。

## 🤝 技术支持

如遇到问题或需要技术支持，请：

1. 首先查看故障排除部分
2. 运行完整测试验证环境
3. 查看详细的API对接文档
4. 联系项目维护者

---

**项目版本**: 1.0.0  
**最后更新**: 2025-06-05  
**兼容性**: Python 3.11+, 支持GPU/CPU