posefind/AGENTS.md

# 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. 考虑添加错误处理和用户友好的提示信息