# PP-YOLO-E 台球专用检测模型<div align="center">**基于PaddleDetection的台球专用目标检测模型（SOD优化版）**开源项目连接(https://aistudio.baidu.com/projectdetail/9774059)</div>---## 📖 模型简介**PP-YOLO-E Billiard SOD** 是一个专门针对台球场景优化的目标检测模型，基于百度PaddleDetection的PP-YOLO-E架构，采用小目标检测优化（SOD - Small Object Detection）技术，实现了对台球场景中16类目标的高精度实时检测。### 🎯 核心特性- **台球场景专用**: 针对台球桌面场景深度优化，支持母球+15个彩球的精准识别- **小目标优化**: 采用SOD技术，显著提升台球等小目标的检测精度- **实时性能**: 在Jetson Nano上可达45 FPS，桌面GPU可达100+ FPS- **高精度**: mAP@0.5可达89%+，满足实际应用需求- **即插即用**: 提供完整的模型权重、配置文件和推理代码### 📊 模型信息| 属性 | 值 ||------|-----|| 框架 | PaddlePaddle 2.6.0 / PaddleDetection 2.7.0 || 基础架构 | PP-YOLO-E || Backbone | CSPResNet (depth_mult=1.0, width_mult=1.0) || Neck | CustomCSPPAN (SPP + 4层特征融合) || 输入尺寸 | 640×640 || 模型大小 | ~177 MB || 参数量 | ~52M || 类别数量 | 16类 (1个母球 + 15个彩球) || 训练数据 | 3183张台球场景图像 |---## 🎱 支持的类别模型支持检测以下16类台球目标：| ID | 类别名称 | 颜色 | 说明 ||----|---------|------|------|| 0 | cue_ball | 白色 | 母球 || 1 | ball_1 | 黄色 | 1号球 (全色) || 2 | ball_2 | 蓝色 | 2号球 (全色) || 3 | ball_3 | 红色 | 3号球 (全色) || 4 | ball_4 | 紫色 | 4号球 (全色) || 5 | ball_5 | 橙色 | 5号球 (全色) || 6 | ball_6 | 绿色 | 6号球 (全色) || 7 | ball_7 | 棕色 | 7号球 (全色) || 8 | ball_8 | 黑色 | 8号球 (全色) || 9 | ball_9 | 黄白 | 9号球 (半色) || 10 | ball_10 | 蓝白 | 10号球 (半色) || 11 | ball_11 | 红白 | 11号球 (半色) || 12 | ball_12 | 紫白 | 12号球 (半色) || 13 | ball_13 | 橙白 | 13号球 (半色) || 14 | ball_14 | 绿白 | 14号球 (半色) || 15 | ball_15 | 棕白 | 15号球 (半色) |---## 📁 文件说明```ppyoloe/├── ppyoloe_billiard_sod.pdparams # 模型权重文件 (177MB)├── ppyoloe_billiard_sod.pdopt # 优化器状态 (用于继续训练)├── ppyoloe_billiard_sod.yml # 模型配置文件└── README.md # 本文档```### 文件详情- **ppyoloe_billiard_sod.pdparams**: 训练好的模型权重，用于推理和迁移学习- **ppyoloe_billiard_sod.pdopt**: 优化器状态，用于断点续训（可选）- **ppyoloe_billiard_sod.yml**: 完整的模型配置，包含网络结构、训练参数、数据增强策略等---## 📈 性能指标### 检测精度| 指标 | 值 | 说明 ||------|-----|------|| mAP@0.5 | 89%+ | IoU阈值0.5时的平均精度 || mAP@0.5:0.95 | 75%+ | COCO标准评估指标 || AP (small) | 82%+ | 小目标检测精度 || Precision | 91%+ | 精确率 || Recall | 88%+ | 召回率 |### 推理速度| 硬件平台 | 输入尺寸 | FPS | 延迟 ||---------|---------|-----|------|| NVIDIA RTX 3090 | 640×640 | 120+ | ~8ms || NVIDIA GTX 1060 | 640×640 | 60+ | ~16ms || Jetson Nano (FP16) | 640×640 | 45 | ~22ms || Jetson Nano (TensorRT) | 640×640 | 80+ | ~12ms || CPU (i7-10700) | 640×640 | 15 | ~66ms |---## 🚀 快速开始### 环境要求- Python 3.8+- PaddlePaddle 2.6.0+- PaddleDetection 2.7.0+- CUDA 11.2+ (GPU推理)### 安装依赖```bash# 安装PaddlePaddle (GPU版本)pip install paddlepaddle-gpu==2.6.0# 或CPU版本pip install paddlepaddle==2.6.0# 安装PaddleDetectiongit clone https://github.com/PaddlePaddle/PaddleDetection.gitcd PaddleDetectionpip install -r requirements.txtpython setup.py install```### 推理示例#### 1. 使用Python API```pythonimport paddlefrom ppdet.core.workspace import load_config, merge_configfrom ppdet.engine import Trainerfrom ppdet.utils.check import check_gpu, check_versionimport cv2# 加载配置和模型config_path = 'ppyoloe_billiard_sod.yml'cfg = load_config(config_path)# 创建预测器trainer = Trainer(cfg, mode='test')trainer.load_weights('ppyoloe_billiard_sod.pdparams')# 读取图像image = cv2.imread('test_image.jpg')# 执行推理results = trainer.predict([image])# 解析结果for result in results: for det in result['bbox']: class_id = int(det[0]) score = det[1] bbox = det[2:6] # [x1, y1, x2, y2] print(f"Class: {class_id}, Score: {score:.2f}, BBox: {bbox}")```#### 2. 使用命令行工具```bash# 单张图像推理python tools/infer.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --infer_img=test_image.jpg \ --output_dir=output/# 视频推理python tools/infer.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --video_file=test_video.mp4 \ --output_dir=output/# 批量推理python tools/infer.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --infer_dir=test_images/ \ --output_dir=output/```#### 3. 集成到项目中```pythonfrom core.detection.ppyoloe_ball_detector import PPYOLOEBallDetector# 初始化检测器detector = PPYOLOEBallDetector( config_path="models/ppyoloe/ppyoloe_billiard_sod.yml", weights_path="models/ppyoloe/ppyoloe_billiard_sod.pdparams", device="gpu:0", # 或 "cpu" threshold=0.5)# 检测图像import cv2image = cv2.imread("billiards.jpg")detections = detector.detect(image)# 处理结果for det in detections: class_name = det['class_name'] confidence = det['confidence'] bbox = det['bbox'] # [x1, y1, x2, y2] print(f"{class_name}: {confidence:.2f} at {bbox}")```---## 🎯 应用场景### 1. 智能台球训练系统- **实时目标检测**: 跟踪台球位置和运动轨迹- **击打分析**: 分析击球路径和结果- **智能辅助**: 提供最优击球路线建议### 2. 台球赛事分析- **自动比分统计**: 识别进球和球局变化- **战术分析**: 记录选手击球策略- **高光时刻捕捉**: 自动识别精彩球局### 3. 台球游戏开发- **AR增强现实**: 虚拟台球与真实场景结合- **动作捕捉**: 将真实台球桌映射到游戏中- **智能裁判**: 自动判断犯规和得分### 4. 教学与培训- **技术分析**: 录制并分析学员击球过程- **远程教学**: 通过视频实时指导- **进度跟踪**: 记录训练数据和进步曲线---## 🔧 模型优化### TensorRT加速```python# 导出为ONNXpython tools/export_model.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --output_dir=output_inference# 转换为TensorRT (FP16)trtexec --onnx=model.onnx \ --saveEngine=model_fp16.trt \ --fp16```### 量化部署```python# INT8量化 (需要校准数据集)python tools/post_quant.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --quant_batch_size=10 \ --quant_batch_num=10```### 模型裁剪```python# 剪枝以减小模型大小python tools/prune.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams \ --pruned_ratio=0.3```---## 📚 训练自己的模型### 1. 准备数据集确保数据集采用COCO格式：```dataset/├── annotations/│ ├── instances_train.json│ └── instances_val.json└── images/ ├── train/ └── val/```### 2. 修改配置文件编辑 `ppyoloe_billiard_sod.yml`：```yamlEvalDataset: dataset_dir: /path/to/your/dataset anno_path: annotations/instances_val.json image_dir: valTrainDataset: dataset_dir: /path/to/your/dataset anno_path: annotations/instances_train.json image_dir: train```### 3. 开始训练```bash# 单GPU训练python tools/train.py -c ppyoloe_billiard_sod.yml# 多GPU训练python -m paddle.distributed.launch \ --gpus 0,1,2,3 \ tools/train.py -c ppyoloe_billiard_sod.yml# 断点续训python tools/train.py \ -c ppyoloe_billiard_sod.yml \ -r output/ppyoloe_billiard_sod/best_model```### 4. 评估模型```bashpython tools/eval.py \ -c ppyoloe_billiard_sod.yml \ -o weights=ppyoloe_billiard_sod.pdparams```---## 🛠️ 技术细节### 网络架构```输入图像 (640×640×3) ↓CSPResNet Backbone ├─ Stage1: 64 channels, 3 layers ├─ Stage2: 128 channels, 6 layers → P2 ├─ Stage3: 256 channels, 6 layers → P3 └─ Stage4: 512 channels, 3 layers → P4 ↓CustomCSPPAN Neck (with SPP) ├─ C5 (1024 ch) + SPP ├─ P5 → C4 → P4 (768 ch) ├─ P4 → C3 → P3 (384 ch) └─ P3 → C2 → P2 (192 ch) ↓Detection Head (3个尺度) ├─ Large objects (20×20) ├─ Medium objects (40×40) └─ Small objects (80×80) ← SOD优化 ↓输出: 16类目标的bbox + 置信度```### SOD优化策略1. **多尺度特征增强**: 保留更多浅层特征用于小目标检测2. **Anchor优化**: 针对台球尺寸调整anchor boxes3. **数据增强**: Mosaic、MixUp、RandomFlip、RandomBrightness4. **损失函数**: VFLoss + GIoULoss组合5. **后处理**: 多尺度测试 + 软NMS### 训练配置```yaml训练周期: 270 epochs优化器: AdamW基础学习率: 0.001学习率策略: Cosine AnnealingBatch Size: 8 × 4 GPUs = 32输入尺寸: 640×640权重衰减: 0.0001Warmup: 5 epochs数据增强: Mosaic + MixUp + ColorJitter```---## 📊 评估结果### 各类别AP (mAP@0.5)| 类别 | AP | 说明 ||------|-----|------|| cue_ball | 94.2% | 母球（白色） || ball_1 | 91.5% | 1号黄球 || ball_2 | 89.8% | 2号蓝球 || ball_3 | 92.1% | 3号红球 || ball_4 | 88.3% | 4号紫球 || ball_5 | 90.7% | 5号橙球 || ball_6 | 89.2% | 6号绿球 || ball_7 | 87.9% | 7号棕球 || ball_8 | 93.6% | 8号黑球 || ball_9-15 | 85-90% | 半色球 |---## 🔗 相关资源- **训练数据集**: [COCO Billiard Dataset](https://aistudio.baidu.com/dataset/detail/361590/file)- **PaddleDetection**: https://github.com/PaddlePaddle/PaddleDetection- **项目主页**: [球域灵眸 AI台球训练系统](https://aistudio.baidu.com/project/edit/9774059)---## 📝 引用如果您在研究或项目中使用了本模型，请引用：```bibtex@misc{ppyoloe_billiard_sod_2025, title={PP-YOLO-E Billiard SOD: A Specialized Detection Model for Billiards}, author={bluse鑫}, year={2025}, publisher={aistudio}, howpublished={https://aistudio.baidu.com/modelsdetail/40012/space}}}```---## 📧 联系方式- **问题反馈**: 请通过email提交- **商业合作**: bluse713@yeah.net- **技术交流**: 欢迎Fork和Star本项目---## 📜 许可证本模型基于 [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) 开源。**注意事项**:- ✅ 允许商业使用- ✅ 允许修改和分发- ✅ 允许私有使用- ⚠️ 需保留版权声明和许可证- ⚠️ 不提供任何明示或暗示的担保---## 🎉 致谢- 感谢 PaddlePaddle 团队提供的优秀深度学习框架- 感谢所有为台球数据集标注做出贡献的朋友们- 感谢开源社区的支持与反馈---## 📅 更新日志### v1.0 (2025-11-21)- 🎉 初始版本发布- ✅ 支持16类台球目标检测- ✅ mAP@0.5 达到89%+- ✅ 提供完整的模型权重和配置文件- ✅ 优化Jetson Nano部署性能---<div align="center">**⭐ 如果觉得有用，请给个Star支持一下！⭐**Made with ❤️ for Billiards AI Training System</div>