458 lines
12 KiB
Markdown
458 lines
12 KiB
Markdown
# 身体平衡评估系统
|
||
|
||
一个基于多传感器融合技术的专业身体平衡评估与分析系统，为用户提供准确的平衡能力评估和康复指导。
|
||
|
||
## 系统特性
|
||
|
||
### 🎯 核心功能
|
||
- **实时姿态检测**: 基于MediaPipe的高精度人体姿态识别
|
||
- **多传感器融合**: 整合摄像头、IMU传感器和压力传感器数据
|
||
- **智能分析引擎**: 多维度平衡能力评估算法
|
||
- **实时视频流**: WebSocket实时视频传输和显示
|
||
- **检测数据采集**: 一键采集当前检测状态的数据快照
|
||
- **视频录制功能**: 支持检测过程的视频录制和回放
|
||
- **可视化报告**: 直观的数据图表和分析报告
|
||
- **历史数据管理**: 完整的检测记录存储和对比分析
|
||
|
||
### 🔧 技术特点
|
||
- **现代化架构**: Vue 3 + Python Flask 前后端分离
|
||
- **实时通信**: WebSocket 实时数据传输和视频流
|
||
- **多媒体支持**: 集成视频录制、截图和数据采集功能
|
||
- **跨平台支持**: Windows、macOS、Linux
|
||
- **模块化设计**: 清晰的目录结构，易于扩展和维护
|
||
- **数据安全**: 本地存储，保护用户隐私
|
||
- **开发友好**: 独立的前后端开发环境，支持热重载
|
||
- **部署简化**: 一键安装和启动脚本，降低部署复杂度
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
身体平衡评估系统/
|
||
├── backend/ # 后端服务
|
||
│ ├── main.py # 主启动脚本
|
||
│ ├── app.py # Flask 主应用
|
||
│ ├── database.py # 数据库管理
|
||
│ ├── device_manager.py # 设备管理
|
||
│ ├── detection_engine.py # 检测引擎
|
||
│ ├── data_processor.py # 数据处理
|
||
│ ├── utils.py # 工具函数
|
||
│ └── requirements.txt # Python 依赖
|
||
├── frontend/ # 前端应用
|
||
│ └── src/renderer/ # 前端源码
|
||
│ ├── src/
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ ├── stores/ # 状态管理
|
||
│ │ ├── services/ # API 服务
|
||
│ │ └── router/ # 路由配置
|
||
│ ├── package.json # Node.js 依赖
|
||
│ └── vite.config.js # 构建配置
|
||
├── data/ # 数据目录
|
||
├── logs/ # 日志目录
|
||
├── venv/ # Python 虚拟环境
|
||
├── install.bat # 安装脚本
|
||
├── start_dev.bat # 开发模式启动脚本
|
||
└── start_prod.bat # 生产模式启动脚本
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **Python**: 3.8 或更高版本
|
||
- **Node.js**: 16.0 或更高版本 (开发模式)
|
||
- **操作系统**: Windows 10/11, macOS 10.15+, Ubuntu 18.04+
|
||
|
||
### 安装步骤
|
||
|
||
#### 方式一：一键安装 (Windows 推荐)
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd BodyBalanceEvaluation
|
||
```
|
||
|
||
2. **运行安装脚本**
|
||
```bash
|
||
install.bat
|
||
```
|
||
|
||
安装脚本会自动完成：
|
||
- 检查 Python 和 Node.js 环境
|
||
- 创建 Python 虚拟环境
|
||
- 安装后端依赖
|
||
- 安装前端依赖
|
||
- 创建必要的目录结构
|
||
|
||
#### 方式二：手动安装
|
||
|
||
1. **克隆项目**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd BodyBalanceEvaluation
|
||
```
|
||
|
||
2. **创建虚拟环境**
|
||
```bash
|
||
python -m venv venv
|
||
venv\Scripts\activate # Windows
|
||
# source venv/bin/activate # macOS/Linux
|
||
```
|
||
|
||
3. **安装 Python 依赖**
|
||
```bash
|
||
pip install -r backend/requirements.txt
|
||
```
|
||
|
||
4. **安装前端依赖** (开发模式)
|
||
```bash
|
||
cd frontend/src/renderer
|
||
npm install
|
||
cd ../../..
|
||
```
|
||
|
||
### 启动应用程序
|
||
|
||
**Windows 用户 (推荐)**:
|
||
```bash
|
||
# 一键安装 (首次使用)
|
||
install.bat
|
||
|
||
# 开发模式
|
||
start_dev.bat
|
||
|
||
# 生产模式
|
||
start_prod.bat
|
||
```
|
||
|
||
**手动启动**:
|
||
```bash
|
||
# 激活虚拟环境
|
||
venv\Scripts\activate
|
||
|
||
# 进入后端目录
|
||
cd backend
|
||
|
||
# 开发模式
|
||
python main.py --mode development
|
||
|
||
# 生产模式
|
||
python main.py --mode production
|
||
```
|
||
|
||
### 命令行参数
|
||
|
||
```bash
|
||
cd backend
|
||
python main.py [选项]
|
||
|
||
选项:
|
||
--mode {development,production} 运行模式 (默认: development)
|
||
--host HOST 服务器主机 (默认: 127.0.0.1)
|
||
--port PORT 服务器端口 (默认: 5000)
|
||
--no-browser 不自动打开浏览器
|
||
--log-level {DEBUG,INFO,WARNING,ERROR} 日志级别 (默认: INFO)
|
||
```
|
||
|
||
## 使用指南
|
||
|
||
### 1. 系统设置
|
||
|
||
首次使用前，请进入「系统设置」页面配置：
|
||
|
||
- **设备配置**: 选择摄像头、配置串口设备
|
||
- **检测参数**: 设置默认检测时长、采样频率等
|
||
- **数据管理**: 配置数据存储路径和清理策略
|
||
|
||
### 2. 患者管理
|
||
|
||
- 添加患者基本信息（姓名、年龄、性别等）
|
||
- 记录患者病史和康复目标
|
||
- 管理患者档案和检测记录
|
||
|
||
### 3. 姿态检测
|
||
|
||
1. **选择患者**: 从患者列表中选择或新建患者
|
||
2. **设备准备**: 确保摄像头和传感器正常连接
|
||
3. **开始检测**: 点击开始按钮进行实时检测
|
||
4. **实时监控**: 通过实时视频流观察检测过程
|
||
5. **数据采集**: 在检测过程中点击"检测数据采集"按钮获取当前状态数据
|
||
6. **视频录制**: 使用"开始录制"/"停止录制"按钮记录检测过程
|
||
7. **停止检测**: 完成检测并自动计算检测时长
|
||
8. **查看结果**: 检测完成后查看分析结果和建议
|
||
|
||
### 4. 数据分析
|
||
|
||
- **单次分析**: 查看单次检测的详细数据和图表
|
||
- **对比分析**: 比较多次检测结果，观察变化趋势
|
||
- **报告生成**: 生成 PDF 格式的专业评估报告
|
||
- **数据导出**: 导出原始数据用于进一步分析
|
||
|
||
### 5. 历史记录
|
||
|
||
- 浏览所有历史检测记录
|
||
- 按患者、日期、状态等条件筛选
|
||
- 批量导出和删除操作
|
||
- 时间线视图查看检测历史
|
||
|
||
## 设备支持
|
||
|
||
### 摄像头
|
||
- USB 摄像头 (推荐 1080p 30fps)
|
||
- 内置摄像头
|
||
- 网络摄像头
|
||
|
||
### IMU 传感器
|
||
- 支持串口通信的 9 轴 IMU
|
||
- 波特率: 9600, 115200, 230400
|
||
- 数据格式: 加速度、陀螺仪、磁力计
|
||
|
||
### 压力传感器
|
||
- 多点压力传感器阵列
|
||
- 串口通信接口
|
||
- 支持 1-16 个传感器点
|
||
|
||
## 开发指南
|
||
|
||
### 后端开发
|
||
|
||
后端使用 Flask 框架，主要模块：
|
||
|
||
- `main.py`: 主启动脚本和进程管理
|
||
- `app.py`: 主应用和 API 路由
|
||
- `database.py`: SQLite 数据库操作
|
||
- `device_manager.py`: 硬件设备管理和视频流处理
|
||
- `detection_engine.py`: 检测算法引擎
|
||
- `data_processor.py`: 数据分析和处理
|
||
|
||
### 主要API端点
|
||
|
||
- `POST /api/detection/start`: 开始检测会话
|
||
- `POST /api/detection/{session_id}/stop`: 停止检测会话
|
||
- `POST /api/detection/{session_id}/collect`: 采集检测数据
|
||
- `WebSocket /ws`: 实时数据和视频流传输
|
||
|
||
### 前端开发
|
||
|
||
前端使用 Vue 3 + Element Plus，主要特性：
|
||
|
||
- **组合式 API**: 使用 Vue 3 Composition API
|
||
- **状态管理**: Pinia 状态管理库
|
||
- **UI 组件**: Element Plus 组件库
|
||
- **图表库**: ECharts 数据可视化
|
||
- **构建工具**: Vite 快速构建
|
||
|
||
### 添加新功能
|
||
|
||
1. **后端 API**:
|
||
```python
|
||
@app.route('/api/new-feature', methods=['POST'])
|
||
def new_feature():
|
||
# 实现新功能逻辑
|
||
return jsonify({'status': 'success'})
|
||
```
|
||
|
||
2. **前端服务**:
|
||
```javascript
|
||
// frontend/src/renderer/src/services/api.js
|
||
export const newFeatureAPI = {
|
||
doSomething: (data) => api.post('/new-feature', data)
|
||
}
|
||
```
|
||
|
||
3. **前端组件**:
|
||
```vue
|
||
<template>
|
||
<!-- 新功能界面 -->
|
||
</template>
|
||
|
||
<script setup>
|
||
import { newFeatureAPI } from '../services/api'
|
||
</script>
|
||
```
|
||
|
||
### 项目结构优势
|
||
|
||
新的项目结构带来以下优势：
|
||
|
||
1. **清晰分离**: 前后端代码完全分离，便于团队协作开发
|
||
2. **独立部署**: 前后端可以独立部署和扩展
|
||
3. **开发效率**: 前后端可以并行开发，提高开发效率
|
||
4. **维护性**: 模块化结构便于代码维护和功能扩展
|
||
5. **版本管理**: 前后端可以独立进行版本控制
|
||
6. **技术栈**: 前后端可以选择最适合的技术栈
|
||
|
||
### 开发环境配置
|
||
|
||
**后端开发**:
|
||
```bash
|
||
# 激活虚拟环境
|
||
venv\Scripts\activate
|
||
|
||
# 进入后端目录
|
||
cd backend
|
||
|
||
# 启动开发服务器
|
||
python main.py --mode development --log-level DEBUG
|
||
```
|
||
python debug_server.py
|
||
|
||
**前端开发**:
|
||
```bash
|
||
# 进入前端目录
|
||
cd frontend/src/renderer
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
```
|
||
|
||
**同时开发** (推荐):
|
||
```bash
|
||
# 使用开发脚本同时启动前后端
|
||
start_dev.bat
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
**Q: 摄像头无法识别**
|
||
A: 检查摄像头连接，确保没有被其他应用占用，在设备设置中刷新摄像头列表。
|
||
|
||
**Q: 传感器连接失败**
|
||
A: 确认串口设置正确，检查设备驱动是否安装，尝试不同的波特率设置。
|
||
|
||
**Q: 前端页面无法加载**
|
||
A: 检查后端服务是否正常启动，确认防火墙设置，查看浏览器控制台错误信息。
|
||
|
||
**Q: 检测结果不准确**
|
||
A: 确保设备已正确校准，检查环境光线条件，调整检测参数设置。
|
||
|
||
**Q: 视频录制失败**
|
||
A: 检查磁盘空间是否充足，确认录制权限设置，查看后端日志中的错误信息。
|
||
|
||
**Q: WebSocket连接断开**
|
||
A: 检查网络连接稳定性，确认防火墙未阻止WebSocket连接，尝试刷新页面重新连接。
|
||
|
||
### 日志查看
|
||
|
||
系统日志保存在 `logs/` 目录下：
|
||
|
||
- `app.log`: 应用程序主日志
|
||
- `device.log`: 设备管理日志
|
||
- `detection.log`: 检测引擎日志
|
||
- `error.log`: 错误日志
|
||
|
||
### 性能优化
|
||
|
||
1. **硬件要求**:
|
||
- CPU: Intel i5 或同等性能
|
||
- 内存: 8GB RAM
|
||
- 存储: 10GB 可用空间
|
||
|
||
2. **软件优化**:
|
||
- 关闭不必要的后台程序
|
||
- 使用 SSD 存储提高 I/O 性能
|
||
- 定期清理历史数据和日志
|
||
|
||
## 数据格式
|
||
|
||
### 检测数据结构
|
||
|
||
```json
|
||
{
|
||
"session_id": "uuid",
|
||
"patient_id": "patient_uuid",
|
||
"timestamp": "2024-01-01T12:00:00Z",
|
||
"duration": 60,
|
||
"data": {
|
||
"camera": {
|
||
"landmarks": [...],
|
||
"confidence": 0.95
|
||
},
|
||
"imu": {
|
||
"acceleration": [x, y, z],
|
||
"gyroscope": [x, y, z],
|
||
"magnetometer": [x, y, z]
|
||
},
|
||
"pressure": {
|
||
"sensors": [p1, p2, p3, p4],
|
||
"center_of_pressure": [x, y]
|
||
}
|
||
},
|
||
"recording": {
|
||
"video_path": "path/to/video.mp4",
|
||
"screenshots": ["path/to/screenshot1.png"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分析结果格式
|
||
|
||
```json
|
||
{
|
||
"session_id": "uuid",
|
||
"analysis_time": "2024-01-01T12:01:00Z",
|
||
"overall_assessment": "good",
|
||
"balance_score": 85,
|
||
"posture_score": 78,
|
||
"metrics": {
|
||
"sway_area": 2.5,
|
||
"sway_velocity": 1.2,
|
||
"postural_stability": 0.85
|
||
},
|
||
"recommendations": [
|
||
"建议加强核心肌群训练",
|
||
"注意保持正确站姿"
|
||
]
|
||
}
|
||
```
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎贡献代码！请遵循以下步骤：
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 开启 Pull Request
|
||
|
||
## 支持
|
||
|
||
如果您遇到问题或有建议，请：
|
||
|
||
- 查看 [FAQ](docs/FAQ.md)
|
||
- 提交 [Issue](issues)
|
||
- 发送邮件至: support@example.com
|
||
|
||
## 更新日志
|
||
|
||
### v1.2.0 (2024-01-20)
|
||
- **检测功能增强**: 新增检测数据采集功能，支持实时数据快照
|
||
- **视频录制**: 集成视频录制功能，支持检测过程的完整记录
|
||
- **实时视频流**: 优化WebSocket视频传输，提供流畅的实时监控
|
||
- **API优化**: 重构检测相关API，使用RESTful设计模式
|
||
- **用户体验**: 改进检测界面，添加录制控制和数据采集按钮
|
||
- **生命周期管理**: 完善组件生命周期处理，确保资源正确释放
|
||
|
||
### v1.1.0 (2024-01-15)
|
||
- **项目重构**: 前后端完全分离，优化项目结构
|
||
- **新增脚本**: 添加一键安装和启动脚本 (install.bat, start_dev.bat, start_prod.bat)
|
||
- **开发体验**: 改进开发环境配置，支持独立的前后端开发
|
||
- **文档更新**: 完善 README 文档，添加详细的安装和使用说明
|
||
- **路径优化**: 统一使用虚拟环境，规范化依赖管理
|
||
|
||
### v1.0.0 (2024-01-01)
|
||
- 初始版本发布
|
||
- 基础检测功能
|
||
- 患者管理系统
|
||
- 数据分析和报告生成
|
||
|
||
---
|
||
|
||
**身体平衡评估系统** - 专业的平衡能力评估解决方案 |