KUNIN/single-mouse-webrtc-pose

单鼠姿态检测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: 自动部署 (推荐)

# 进入项目目录
cd single_mouse_webrtc_project

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

方法2: 手动部署

# 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

测试验证

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

📡 API使用示例

WebSocket实时流处理

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单帧处理

// 处理单张图像
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. 模型加载失败

   # 检查模型文件
   ls -la models/
   python check_model.py
   

2. 端口占用

   # 检查端口使用情况
   lsof -i :7860
   lsof -i :8765
   

3. 依赖缺失

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

4. GPU不可用

   # 检查CUDA环境
   python -c "import torch; print(torch.cuda.is_available())"
   

调试模式

# 启用详细日志
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