AI-Powered Volleyball Training System
一个基于人工智能的排球垫球动作识别与训练系统，帮助排球爱好者提升技术水平。
- 智能姿态识别: 基于MediaPipe的33点人体姿态检测
- 多维度评分: 手臂姿态、身体重心、触球位置、整体稳定性4个维度全面评估
- 双模式分析:
- 单帧快速分析：提取关键帧，3秒出结果
- 连续帧深度分析：完整动作序列，流畅度、完整性、一致性多维评估
- 智能反馈: AI精准定位问题，提供个性化改进建议
- 游戏化关卡: 初级(50分)、中级(70分)、高级(85分)循序渐进
- 骨架叠加: 在原视频上叠加姿态骨架
- 纯骨架动画: 白色背景抽象骨架展示
- 左右对比: 原视频与骨架并排对比
- 轨迹追踪: 实时绘制关键点运动路径
- 前后端分离: 清晰的模块化设计
- 三层架构: API层、服务层、核心层
- 易于扩展: 组件化开发，便于维护和升级
💡 提示：以下步骤适用于本地开发环境。如需部署到服务器，请查看 部署指南。
- Python 3.8+
- pip
- 克隆项目
git clone <repository-url>
cd VolleyGo- 安装依赖
pip install -r requirements.txt-
配置环境变量
项目使用环境变量管理 API Key，避免敏感信息泄露。
# 复制配置模板 cp .env.example .env # 编辑 .env 文件，填入您的 API Key # Windows: notepad .env # Linux/Mac: nano .env
在
.env文件中设置：OPENAI_API_KEY=your_api_key_here OPENAI_BASE_URL=https://api.chatanywhere.tech
📖 详细配置说明请查看 配置指南
-
启动应用
# Flask API 服务器（推荐）
python run_flask.py-
访问系统
打开浏览器访问
http://localhost:5000
已自动配置：前端使用相对路径 /api，自动适配当前域名。
- ✅ 本地开发：
http://localhost:5000→ API:http://localhost:5000/api - ✅ 服务器部署：
http://your-server.com→ API:http://your-server.com/api
无需手动配置，自动适配！
VolleyGo/
│
├── app.py # Streamlit主应用入口
├── requirements.txt # 项目依赖
├── README.md # 项目文档
│
├── backend/ # 后端代码
│ ├── __init__.py
│ ├── api/ # API接口层
│ │ ├── __init__.py
│ │ └── volleyball_api.py # 对外API接口
│ ├── core/ # 核心功能模块
│ │ ├── __init__.py
│ │ ├── pose_detector.py # 姿态检测
│ │ ├── video_processor.py # 视频处理
│ │ ├── scorer.py # 评分算法
│ │ ├── sequence_analyzer.py # 序列分析
│ │ ├── trajectory_visualizer.py # 轨迹可视化
│ │ └── video_generator.py # 视频生成
│ ├── services/ # 业务逻辑层
│ │ ├── __init__.py
│ │ └── volleyball_service.py # 业务服务
│ ├── models/ # 数据模型
│ └── utils/ # 工具函数
│
├── frontend/ # 前端代码
│ ├── __init__.py
│ ├── components/ # UI组件
│ │ ├── __init__.py
│ │ ├── header.py # 页面头部
│ │ ├── score_card.py # 评分卡片
│ │ └── video_uploader.py # 视频上传
│ ├── pages/ # 页面
│ └── assets/ # 静态资源
│
├── config/ # 配置文件
│ ├── __init__.py
│ └── settings.py # 系统配置
│
├── data/ # 数据目录
│ ├── models/ # 模型文件
│ └── templates/ # 动作模板
│ └── default_template.json
│
├── output/ # 输出文件
│ └── (生成的视频等)
│
└── tests/ # 测试代码
├── unit/ # 单元测试
└── integration/ # 集成测试
- 支持格式: MP4, AVI, MOV, MKV
- 文件大小: ≤ 50MB
- 视频时长: 3-10秒最佳
- 🎯 单帧分析（快速）: 提取关键帧快速评估，适合初学者
- 🎬 连续帧分析（详细）: 完整动作序列深度分析，提供流畅度等指标
- 总分及分项得分
- 雷达图可视化
- 关卡等级评定
- 个性化改进建议
- 上传原始视频
- 选择可视化类型:
- 🎥 骨架叠加（推荐）
- 🦴 纯骨架动画
- 📊 左右对比
- 📈 轨迹追踪
- 点击生成按钮
- 下载生成的视频
- 角度: 正面拍摄，相机与人平行
- 距离: 全身入镜，从头到脚完整显示
- 光线: 充足且均匀，避免逆光
- 背景: 简洁清爽，避免杂乱
- 稳定: 使用三脚架或稳定设备
- 穿着贴身运动服
- 避免过于宽松的衣物
- 颜色与背景有对比度
| 维度 | 分值 | 评分标准 |
|---|---|---|
| 手臂姿态 | 40分 | 双臂伸直(165°)，夹角<30°，水平对称 |
| 身体重心 | 30分 | 膝盖弯曲60-90°，重心下沉稳定 |
| 触球位置 | 20分 | 接触点在腰腹前方，高度适中(45%身高) |
| 整体稳定 | 10分 | 动作流畅连贯，姿态置信度高 |
- 🌱 初级: ≥50分 - 基础动作掌握
- 🌟 中级: ≥70分 - 标准动作规范
- 🏆 高级: ≥85分 - 专业级别水准
- MediaPipe Pose: 实时姿态检测（33个关键点）
- OpenCV: 视频处理与帧提取
- NumPy & SciPy: 数值计算与信号处理
- Python 3.8+: 主要开发语言
- 原生 JavaScript: 纯前端实现，无需构建工具
- HTML5 & CSS3: 现代化UI样式
- 相对路径API: 自动适配本地开发或服务器部署
┌─────────────────┐
│ Frontend (HTML) │ ← 前端展示层（使用相对路径API）
└────────┬────────┘
│
┌────────▼────────┐
│ Flask API │ ← API接口层（RESTful）
└────────┬────────┘
│
┌────────▼────────┐
│ Service Layer │ ← 业务逻辑层
└────────┬────────┘
│
┌────────▼────────┐
│ Core Modules │ ← 核心功能层
│ (Pose, Video, │
│ Score, etc.) │
└─────────────────┘
- 排球初学者: 学习标准动作，建立正确基础
- 业余爱好者: 自我训练，提升技术水平
- 体育教练: 辅助教学，量化评估学员
- 学生研究者: 姿态识别研究，运动分析
- 个人训练辅助
- 线上教学工具
- 训练营评估系统
- 体育科研项目
- ✨ 全新架构：前后端分离，模块化设计
- 🎨 现代化UI：全新Streamlit界面，参考专业设计
- 📦 三层架构：API层、服务层、核心层清晰分离
- 📚 完整文档：详细的使用指南和技术文档
- 🔧 易于维护：组件化开发，便于扩展和调试
- 🎥 新增4种动态视频可视化模式
- 📈 改进轨迹追踪算法
- 🎬 新增连续帧分析功能
- 📊 流畅度、完整性、一致性评估
- 🎯 基础姿态识别与评分功能
💡 提示：部署到服务器前，请先完成快速开始中的基础配置（克隆项目、安装依赖、配置环境变量）。
按照快速开始部分完成：
- ✅ 克隆项目到服务器
- ✅ 安装依赖（
pip install -r requirements.txt） - ✅ 配置
.env文件（设置 API Key）
根据您的需求选择启动方式：
方式 1：直接运行（简单测试）
python run_flask.py方式 2：使用 Gunicorn（生产环境，推荐）
# 安装 Gunicorn
pip install gunicorn
# 启动服务（4个工作进程）
gunicorn -w 4 -b 0.0.0.0:5000 "run_flask:app"方式 3：使用 Nginx + Gunicorn（生产环境，最佳实践）
- 启动 Gunicorn（后台运行）：
gunicorn -w 4 -b 127.0.0.1:5000 "run_flask:app" --daemon- 配置 Nginx 反向代理：
创建 Nginx 配置文件（如 /etc/nginx/sites-available/volleyball）：
server {
listen 80;
server_name your-domain.com; # 替换为您的域名
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持（如果需要）
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}- 启用配置并重启 Nginx：
sudo ln -s /etc/nginx/sites-available/volleyball /etc/nginx/sites-enabled/
sudo nginx -t # 测试配置
sudo systemctl restart nginx-
访问服务
- 如果使用方式1/2：访问
http://your-server-ip:5000 - 如果使用方式3：访问
http://your-domain.com
- 如果使用方式1/2：访问
-
检查 API 连接
- 打开浏览器开发者工具（F12）
- 查看 Network 标签页
- 确认 API 请求发送到正确地址（如
http://your-server.com/api/health） - 检查请求是否成功（状态码 200）
-
验证功能
- 测试视频上传和分析功能
- 测试 AI 教练功能
- 检查控制台是否有错误信息
A: 这是典型的 API 地址配置问题。已解决：
- ✅ 前端已改为相对路径
/api - ✅ 自动适配当前域名
- ✅ 无需手动配置
如果仍有问题，检查：
- 后端服务是否正常运行
- 浏览器控制台是否有 CORS 错误
- 网络请求是否发送到正确的地址
A: 打开浏览器开发者工具（F12）：
- 查看 Network 标签页
- 找到 API 请求（如
/api/health） - 确认请求地址为：
http://your-server.com/api/...（而不是http://localhost:5000/api/...）
A:
- ✅ 无需修改前端代码（已使用相对路径）
- ✅ 只需配置
.env文件中的 API Key - ✅ 后端路由无需修改（已正确配置）
pip install -r requirements.txt# 单元测试
pytest tests/unit/
# 集成测试
pytest tests/integration/- 遵循PEP 8规范
- 使用类型注解
- 添加文档字符串
- 保持模块独立性
- 在
backend/core/添加核心功能模块 - 在
backend/services/扩展业务逻辑 - 在
backend/api/暴露API接口 - 在
frontend/components/创建UI组件 - 在
app.py中集成到主应用
欢迎提交Issue和Pull Request！
- Fork本项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启Pull Request
本项目采用 MIT 许可证。详见 LICENSE 文件。
如有问题或建议，欢迎联系：
- 📧 Email: 1037783681@qq.com
- 💬 Issues: GitHub Issues
💖 Made with passion for volleyball training
🌟 如果这个项目对你有帮助，请给个Star！