posefind/USAGE.md

# 姿态识别Demo 使用说明

## 功能介绍

这是一个基于MediaPipe的人像姿态识别Demo，支持：
- **摄像头实时检测**：实时检测摄像头中的人像姿态
- **图片检测**：检测单张图片中的人像姿态
- **33个关键点检测**：全身姿态关键点识别
- **骨架可视化**：在图像上绘制姿态骨架
- **多人检测支持**：静态图片模式支持多个人物检测（不同颜色区分）

## 环境要求

- Python 3.7+
- Windows/Linux/macOS

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 1. 摄像头实时检测

直接运行程序，将自动打开摄像头进行实时姿态检测：

```bash
python pose_detector.py
```

**操作说明：**
- 程序会自动打开默认摄像头（索引0）
- 实时显示姿态检测结果
- 按 `q` 键退出程序

### 2. 图片检测

指定图片路径进行检测：

```bash
python pose_detector.py path/to/your/image.jpg
```

**示例：**
```bash
python pose_detector.py test.jpg
python pose_detector.py test.webp
```

**输出信息：**
- 显示带有姿态骨架的图片
- 打印每个人物的姿态关键点坐标信息
- 按任意键关闭窗口

## 姿态关键点说明

程序检测以下主要关键点（MediaPipe格式，共33个关键点）：

- **头部**：鼻子、左右眼、左右耳、嘴等
- **肩膀**：左肩、右肩
- **手臂**：左肘、右肘、左腕、右腕
- **躯干**：左臀、右臀
- **腿部**：左膝、右膝、左踝、右踝
- **手部**：左右手的21个关键点
- **脚部**：左右脚的详细关键点

## 代码结构

```
pose_detector.py
├── PoseDetector 类
│   ├── __init__()           # 初始化检测器（静态+流式）
│   ├── detect_pose()        # 单人姿态检测（流式模式）
│   ├── detect_poses()       # 多人姿态检测（静态模式）
│   ├── draw_pose()          # 绘制单个骨架
│   ├── draw_poses()         # 绘制多个骨架
│   ├── get_pose_info()      # 获取单人姿态信息
│   └── get_poses_info()     # 获取多人姿态信息
├── run_webcam()             # 摄像头检测模式
├── run_image()              # 图片检测模式（支持多人）
└── main()                   # 主函数
```

## 技术说明

- **MediaPipe Pose**：Google开源的姿态估计库
- **OpenCV**：图像处理和显示
- **双检测器设计**：
  - `pose_static`：用于静态图像，支持更好的多人检测
  - `pose_stream`：用于视频流，优化实时性能
- **模型复杂度**：使用中等复杂度模型（model_complexity=1）
- **检测置信度**：最小检测置信度0.5，最小追踪置信度0.5
- **颜色区分**：多人检测时使用不同颜色（绿、红、蓝、黄、紫、青）

## 多人检测说明

MediaPipe的Pose模型在静态模式下可以更好地检测姿态，但仍然倾向于检测最显著的人物。对于复杂的多人场景：

- 程序会尝试检测多个人物
- 每个人物会用不同颜色显示
- 如果需要更精确的多人检测，建议配合目标检测器（如YOLO）

## 常见问题

### 1. 摄像头无法打开
- 检查摄像头是否被其他程序占用
- 尝试修改代码中的摄像头索引（0, 1, 2...）

### 2. 检测效果不佳
- 确保光线充足
- 确保人物在画面中完整可见
- 避免遮挡和复杂背景

### 3. 依赖安装失败
- 使用国内镜像源安装：
  ```bash
  pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  ```

### 4. 多人检测不准确
- MediaPipe Pose主要优化单人检测
- 对于复杂多人场景，检测结果可能不完整
- 可以尝试调整人物位置或使用其他多人检测方案

## 扩展建议

- 添加姿态识别功能（如站立、坐着、举手等）
- 支持视频文件输入
- 添加姿态数据保存和加载功能
- 集成目标检测器实现更精确的多人检测
- 添加姿态异常检测功能
- 实现姿态轨迹跟踪

## 许可证

本项目遵循原项目LICENSE文件中的许可证规定。