# billiards_edge

**Repository Path**: oftenlin/billiards_edge

## Basic Information

- **Project Name**: billiards_edge
- **Description**: 球准猩AI 台球端侧应用程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-25
- **Last Updated**: 2026-01-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 台球边缘设备系统

## 项目概述

本项目是一个基于边缘计算的AI台球识别与分析系统，专为D-Robotics RDK平台设计。系统通过双摄像头（俯视+斜视）实时采集台球桌数据，利用YOLOv5目标检测和DeepSORT多目标跟踪技术，实现台球的自动检测、跟踪、进球判定、犯规识别等功能，并支持精彩进球视频的自动剪辑。

## 系统架构

### 核心模块结构

```
billiards_edge/
├── billiards_core/          # 核心算法模块
│   ├── detection/           # 目标检测（YOLOv5）
│   ├── tracking/            # 多目标跟踪（DeepSORT）
│   └── utils/               # 工具函数
├── ros_ws/                  # ROS2 子系统
│   ├── src/
│   │   ├── billiards_camera/           # 相机节点
│   │   ├── billiards_detection_cpp/    # C++检测节点
│   │   ├── billiards_tracking/         # 跟踪节点
│   │   ├── billiards_game_start_recog/ # 球局识别
│   │   ├── billiards_video_processing/ # 视频处理
│   │   ├── billiards_data_upload/      # 数据上传
│   │   ├── billiards_visualization/    # 可视化界面
│   │   └── billiards_video_player/     # 视频回放
│   ├── run_realtime_system.sh          # 生产环境启动脚本
│   └── run_playback_system.sh          # 离线回灌脚本
├── tests/                   # 单元测试
│   ├── camera/              # 相机测试
│   ├── unit/                # 单元测试
│   └── yolo/                # YOLO模型测试
├── config/                  # 配置文件
├── weights/                 # 模型权重文件
└── scripts/                 # 辅助脚本
```

## 核心功能

### 1. 双摄像头数据采集
- **俯视相机**：用于台球AI计算，提供全局视角
- **斜视相机**：用于录像，提供比赛视角

### 2. 目标检测与跟踪
- **YOLOv5检测**：实时检测16种台球（0-15号球）
- **DeepSORT跟踪**：多目标跟踪，保持球体ID一致性
- **BPU硬件加速**：利用地平线BPU进行模型推理加速

### 3. 台球业务逻辑
- **击球过程判定**：识别击球动作和球体运动
- **进球判定**：自动识别进球事件
- **犯规判定**：检测犯规行为
- **球局状态管理**：跟踪比赛进程

### 4. 练习模式数据统计
- **连杆数统计**：记录连续进球次数
- **进球率分析**：计算命中率和成功率
- **击球轨迹分析**：分析击球路径和角度
- **练习数据可视化**：实时显示练习进度和统计数据

### 5. 对战模式功能
- **自动计分系统**：实时记录双方得分
- **球局状态识别**：识别开球、击球、犯规等状态
- **比赛规则判定**：根据台球规则自动判定胜负
- **比赛数据记录**：保存完整的比赛过程数据

### 6. 视频处理与回放
- **自动视频剪辑**：基于关键事件时间参数剪辑精彩进球
- **争议球回放**：提供关键争议球的慢动作回放
- **精彩视频集锦**：自动生成比赛精彩瞬间集锦
- **实时录制**：支持RTSP流录制
- **离线回灌**：支持视频文件回放分析

### 7. 数据上传与管理
- **结构化数据上传**：将检测结果、比赛数据等结构化信息上传
- **视频文件上传**：自动上传剪辑后的精彩视频
- **数据统计分析**：云端数据分析和可视化展示

### 8. 可视化界面
- **桌面应用**：实时显示检测结果和比赛状态
- **Web界面**：远程访问和监控
- **实时数据展示**：显示比赛进度、得分、统计数据等

## 快速开始

### 生产环境启动

```bash
# 进入ROS工作空间
cd ~/workspace/billiards_edge/ros_ws

# 启动实时系统
./run_realtime_system.sh
```

### 离线回灌测试

```bash
# 使用默认视频文件回放
./run_playback_system.sh

# 指定视频文件回放
./run_playback_system.sh /path/to/video.mp4

# 启用实时功能进行回放
./run_playback_system.sh /path/to/video.mp4 true
```

### 核心算法测试

```bash
# 批量推理测试
python tests/yolo/inference_batch.py <model_path> <images_dir>

# 跟踪算法测试
python tests/unit/track/test_tracker.py

# 相机测试
python tests/camera/test_camera.py
```

## 系统节点说明

### 实时系统节点
- **top_camera**：俯视相机数据采集
- **side_camera**：斜视相机RTSP录制
- **ball_detector**：台球检测节点
- **ball_tracker**：台球跟踪节点
- **game_start_recog**：球局开局识别
- **video_clip**：视频剪辑处理
- **data_upload**：数据上传服务
- **desktop_app/web_app**：可视化界面

### 配置说明

#### 模型文件
- 检测模型：`weights/detection/bin/billiards_number_detect_640x640_bayese_nv12.bin`
- 特征提取模型：`weights/tracking/ball_classifier.onnx`
- 球局识别模型：`weights/ball_game_recog/ball_game_recog_model_resnet50.onnx`

#### 配置文件
- `config/tracker_config.yaml`：跟踪器配置
- `config/game_rules.yaml`：比赛规则配置
- `config/init_ball_positions.yaml`：初始球位配置

## 开发指南

### 环境要求
- Ubuntu 20.04+
- ROS2 Humble
- Python 3.8+
- 地平线BPU开发环境

### 安装依赖

```bash
# 安装Python依赖
pip install -e .

# 安装ROS2依赖
cd ros_ws
colcon build --symlink-install
```

### 核心算法模块

```python
from billiards_core.detection.ball_detector_bpu import BallDetectorBpu
from billiards_core.tracking.game_tracker.chinese_9ball_tracker import Chinese9BallTracker

# 初始化检测器
detector = BallDetectorBpu("path/to/model.bin")

# 初始化跟踪器
tracker = Chinese9BallTracker()

# 检测和跟踪
image = cv2.imread("test.jpg")
detections = detector.detect(image)
tracks = tracker.update(detections)
```

## 测试验证

### 单元测试
```bash
# 运行所有测试
cd tests
python -m pytest

# 运行特定测试
python -m pytest tests/unit/detect/
python -m pytest tests/unit/track/
```

### 性能测试
- 检测精度：mAP@0.5 > 0.95
- 跟踪精度：MOTA > 0.90
- 实时性能：> 30 FPS

## 部署说明

### 开机自启动
系统已配置为开机自启动服务，通过systemd管理：

```bash
# 查看服务状态
sudo systemctl status billiards-edge

# 启动服务
sudo systemctl start billiards-edge

# 停止服务
sudo systemctl stop billiards-edge
```

### 日志管理
- 日志目录：`ros_ws/logs/`
- 日志备份：`ros_ws/logs_backup/`
- 实时查看：`tail -f ros_ws/logs/ball_detector.log`

## 故障排除

### 常见问题
1. **模型文件缺失**：检查weights目录下的模型文件是否存在
2. **相机连接失败**：检查相机设备权限和连接状态
3. **BPU初始化失败**：检查BPU驱动和环境变量
4. **ROS节点启动失败**：检查ROS2环境配置

### 调试工具
```bash
# 查看节点状态
ros2 node list
ros2 topic list

# 查看特定话题
ros2 topic echo /ball_detections
ros2 topic echo /ball_tracks
```

## 版本信息

### v1.0 已发布功能
- ✅ 核心检测与跟踪算法
- ✅ 练习模式数据统计
- ✅ 基础对战模式
- ✅ 视频自动剪辑
- ✅ 数据上传功能
- ✅ 可视化界面

### 后续开发计划

详细的开发计划和任务跟踪请参考 [TODO.md](./TODO.md) 文件。

#### v1.1 对战模式增强
- 🔄 **中式八球对战模式**
  - 中式八球规则判定
  - 开局摆球识别
  - 花色和全色球区分
  - 黑八最后击打判定

- 🔄 **九球对战模式**
  - 九球比赛规则
  - 按顺序击球判定
  - 9号球特殊规则
  - 推杆判定

- 🔄 **四球对战模式**
  - 四球比赛规则
  - 多球同时进袋判定
  - 特殊得分规则

#### v1.2 高级功能
- 🔄 **智能分析系统**
  - 击球策略建议
  - 走位分析
  - 失误分析报告
  - 训练计划推荐

- 🔄 **社交功能**
  - 比赛排名系统
  - 玩家对战记录
  - 精彩瞬间分享
  - 社区比赛组织

#### v1.3 性能优化
- 🔄 **算法优化**
  - 检测精度提升
  - 跟踪稳定性增强
  - 实时性能优化
  - 多场景适应性

## 许可证

Apache License 2.0

## 贡献指南

欢迎提交Issue和Pull Request来改进本项目。

## 联系方式

如有问题请联系项目维护者。