6.4 KiB

Raw Permalink Blame History

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 助手上下文指南

构建和运行

环境准备

# 安装依赖
pip install -r requirements.txt

# 如遇网络问题，可使用国内镜像源
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

运行命令

摄像头实时检测

python pose_detector.py

自动打开默认摄像头（索引 0）
实时显示姿态检测结果
按 q 键退出

图片检测

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 主要优化单人检测
静态模式下可以尝试检测多个人物
每个人物使用不同颜色区分（绿、红、蓝、黄、紫、青）
对于复杂多人场景，检测结果可能不完整

常见问题处理

摄像头无法打开: 检查摄像头占用，尝试修改索引（0, 1, 2...）
检测效果不佳: 确保光线充足、人物完整可见、避免复杂背景
依赖安装失败: 使用国内镜像源安装
多人检测不准确: 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/)

注意事项

MediaPipe 局限性: MediaPipe Pose 模型主要针对单人优化，多人检测能力有限
模型文件: 项目中包含 yolov8s.onnx 文件，但当前代码未使用，可能是未来的扩展方向
中文环境: 项目文档和注释使用中文，维护时保持一致性
跨平台: 代码支持 Windows/Linux/macOS，但摄像头索引可能因系统而异
资源管理: 使用 try-finally 确保摄像头和窗口正确释放

开发工具

可用工具

Python (需在虚拟环境中运行)
Git (版本 2.45.1.windows.1)
FFmpeg (已安装，可用于视频处理)
curl (已安装)

不可用工具

rg (ripgrep) - 使用 search_file_content 工具替代
gh (GitHub CLI)
wget - 使用 curl 替代

Python 执行

注意：当前环境中 python 命令不可用，需要在虚拟环境中运行。项目使用 .venv 虚拟环境（已忽略）。

维护指南

修改代码时

保持中文注释和文档字符串的一致性
遵循现有的类和方法命名规范
确保资源正确释放（摄像头、窗口）
添加功能时更新相关文档（USAGE.md）

添加新依赖时

在 requirements.txt 中添加具体版本号
测试在不同平台上的兼容性
更新 USAGE.md 中的环境要求部分

修复 Bug 时

先在 USAGE.md 的"常见问题"部分记录
如涉及核心逻辑，更新相关方法文档
考虑添加错误处理和用户友好的提示信息

6.4 KiB Raw Permalink Blame History Unescape Escape