192 lines
6.4 KiB
Markdown
192 lines
6.4 KiB
Markdown
# PoseFind 项目上下文指南
|
||
|
||
## 项目概述
|
||
|
||
PoseFind 是一个基于 MediaPipe 的人像姿态识别项目，专注于实现人体姿态估计和可视化。项目使用 Python 开发，主要面向计算机视觉和人机交互应用场景。
|
||
|
||
### 主要功能
|
||
- 摄像头实时姿态检测
|
||
- 图片单张/多人姿态识别
|
||
- 33个全身姿态关键点检测
|
||
- 姿态骨架可视化绘制
|
||
|
||
### 技术栈
|
||
- **语言**: Python 3.7+
|
||
- **核心框架**: MediaPipe (Google 开源的姿态估计库)
|
||
- **图像处理**: OpenCV (opencv-python)
|
||
- **图像操作**: Pillow
|
||
- **许可证**: Apache License 2.0
|
||
|
||
### 架构设计
|
||
项目采用面向对象设计，核心类为 `PoseDetector`，包含以下关键组件：
|
||
- 双检测器模式：静态检测器（用于多人检测）和流式检测器（用于实时视频）
|
||
- 姿态检测与绘制功能分离
|
||
- 支持单人和多人姿态信息提取
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
posefind/
|
||
├── pose_detector.py # 主程序文件，包含 PoseDetector 类和主函数
|
||
├── requirements.txt # Python 依赖列表
|
||
├── README.md # 项目简介和快速开始指南
|
||
├── USAGE.md # 详细使用说明文档
|
||
├── LICENSE # Apache 2.0 许可证
|
||
├── test.webp # 测试图片
|
||
├── yolov8s.onnx # YOLOv8 模型文件（当前未使用）
|
||
├── .gitignore # Git 忽略规则（标准 Python 项目配置）
|
||
└── AGENTS.md # 本文件，AI 助手上下文指南
|
||
```
|
||
|
||
## 构建和运行
|
||
|
||
### 环境准备
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 如遇网络问题，可使用国内镜像源
|
||
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
|
||
```
|
||
|
||
### 运行命令
|
||
|
||
#### 摄像头实时检测
|
||
```bash
|
||
python pose_detector.py
|
||
```
|
||
- 自动打开默认摄像头（索引 0）
|
||
- 实时显示姿态检测结果
|
||
- 按 `q` 键退出
|
||
|
||
#### 图片检测
|
||
```bash
|
||
python pose_detector.py <图片路径>
|
||
```
|
||
- 示例：`python pose_detector.py test.webp`
|
||
- 显示带有姿态骨架的图片
|
||
- 打印姿态关键点坐标信息
|
||
- 按任意键关闭窗口
|
||
|
||
### 测试说明
|
||
- 项目使用 `test.webp` 作为示例测试图片
|
||
- 暂无自动化测试脚本，需手动测试功能
|
||
|
||
## 开发约定
|
||
|
||
### 代码风格
|
||
- **注释语言**: 中文（项目主要面向中文用户）
|
||
- **文档字符串**: 使用 Google 风格的 docstring
|
||
- **类和函数命名**: 遵循 PEP 8 规范，使用驼峰命名法（类名）和下划线命名法（函数/变量）
|
||
- **代码组织**: 将核心逻辑封装在类中，功能模块化
|
||
|
||
### 关键类和方法
|
||
|
||
#### PoseDetector 类
|
||
**位置**: `pose_detector.py`
|
||
|
||
核心方法：
|
||
- `__init__()`: 初始化两个 MediaPipe Pose 检测器（静态和流式）
|
||
- `detect_pose(image)`: 单人姿态检测（流式模式，用于视频）
|
||
- `detect_poses(image)`: 多人姿态检测（静态模式，用于图片）
|
||
- `draw_pose(image, results, color)`: 绘制单个姿态骨架
|
||
- `draw_poses(image, pose_results)`: 绘制多个姿态骨架（不同颜色）
|
||
- `get_pose_info(results)`: 获取单人姿态信息
|
||
- `get_poses_info(pose_results)`: 获取多人姿态信息
|
||
|
||
**配置参数**:
|
||
- `model_complexity=1`: 中等复杂度模型
|
||
- `min_detection_confidence=0.5`: 最小检测置信度
|
||
- `min_tracking_confidence=0.5`: 最小追踪置信度
|
||
|
||
#### 主函数
|
||
- `run_webcam()`: 摄像头检测模式的主循环
|
||
- `run_image(image_path)`: 图片检测模式
|
||
- `main()`: 程序入口，根据命令行参数选择运行模式
|
||
|
||
### 依赖版本
|
||
```
|
||
opencv-python==4.8.1.78
|
||
mediapipe==0.10.8
|
||
Pillow==10.1.0
|
||
```
|
||
|
||
### 多人检测说明
|
||
- MediaPipe Pose 主要优化单人检测
|
||
- 静态模式下可以尝试检测多个人物
|
||
- 每个人物使用不同颜色区分（绿、红、蓝、黄、紫、青）
|
||
- 对于复杂多人场景，检测结果可能不完整
|
||
|
||
### 常见问题处理
|
||
1. **摄像头无法打开**: 检查摄像头占用，尝试修改索引（0, 1, 2...）
|
||
2. **检测效果不佳**: 确保光线充足、人物完整可见、避免复杂背景
|
||
3. **依赖安装失败**: 使用国内镜像源安装
|
||
4. **多人检测不准确**: MediaPipe 局限性，可考虑集成 YOLO 等目标检测器
|
||
|
||
### 扩展方向建议
|
||
- 添加姿态识别功能（站立、坐着、举手等）
|
||
- 支持视频文件输入
|
||
- 姿态数据保存和加载
|
||
- 集成目标检测器实现更精确的多人检测
|
||
- 姿态异常检测
|
||
- 姿态轨迹跟踪
|
||
|
||
## Git 工作流
|
||
|
||
### 分支信息
|
||
- **当前分支**: main
|
||
- **远程仓库**: http://47.107.61.133:3000/lirh/posefind.git
|
||
|
||
### 提交规范
|
||
- 提交信息应简洁明确，说明"为什么"而非"是什么"
|
||
- 示例：`Add pose detector implementation with YOLOv8 and supporting files`
|
||
|
||
### 忽略规则
|
||
项目使用标准 Python `.gitignore`，忽略以下内容：
|
||
- Python 编译文件 (`__pycache__/`, `*.pyc`)
|
||
- 虚拟环境 (`.venv/`, `venv/`)
|
||
- IDE 配置 (`.idea/`, `.vscode/`)
|
||
- 构建产物 (`dist/`, `build/`)
|
||
- 测试覆盖率文件 (`.coverage`, `htmlcov/`)
|
||
|
||
## 注意事项
|
||
|
||
1. **MediaPipe 局限性**: MediaPipe Pose 模型主要针对单人优化，多人检测能力有限
|
||
2. **模型文件**: 项目中包含 `yolov8s.onnx` 文件，但当前代码未使用，可能是未来的扩展方向
|
||
3. **中文环境**: 项目文档和注释使用中文，维护时保持一致性
|
||
4. **跨平台**: 代码支持 Windows/Linux/macOS，但摄像头索引可能因系统而异
|
||
5. **资源管理**: 使用 `try-finally` 确保摄像头和窗口正确释放
|
||
|
||
## 开发工具
|
||
|
||
### 可用工具
|
||
- Python (需在虚拟环境中运行)
|
||
- Git (版本 2.45.1.windows.1)
|
||
- FFmpeg (已安装，可用于视频处理)
|
||
- curl (已安装)
|
||
|
||
### 不可用工具
|
||
- `rg` (ripgrep) - 使用 `search_file_content` 工具替代
|
||
- `gh` (GitHub CLI)
|
||
- `wget` - 使用 `curl` 替代
|
||
|
||
### Python 执行
|
||
注意：当前环境中 `python` 命令不可用，需要在虚拟环境中运行。项目使用 `.venv` 虚拟环境（已忽略）。
|
||
|
||
## 维护指南
|
||
|
||
### 修改代码时
|
||
1. 保持中文注释和文档字符串的一致性
|
||
2. 遵循现有的类和方法命名规范
|
||
3. 确保资源正确释放（摄像头、窗口）
|
||
4. 添加功能时更新相关文档（USAGE.md）
|
||
|
||
### 添加新依赖时
|
||
1. 在 `requirements.txt` 中添加具体版本号
|
||
2. 测试在不同平台上的兼容性
|
||
3. 更新 USAGE.md 中的环境要求部分
|
||
|
||
### 修复 Bug 时
|
||
1. 先在 USAGE.md 的"常见问题"部分记录
|
||
2. 如涉及核心逻辑，更新相关方法文档
|
||
3. 考虑添加错误处理和用户友好的提示信息 |