# yolo_pose

**Repository Path**: futurelei/yolo_pose

## Basic Information

- **Project Name**: yolo_pose
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# YOLO 手势和姿态识别跟踪系统

基于 YOLOv8 的实时人体姿态估计、手势识别和多目标跟踪系统。

## 功能特性

- **人体姿态估计** - 使用 YOLOv8-pose 模型检测 17 个人体关键点
- **手势识别** - 基于关键点识别常见手势（举手、挥手等）
- **多目标跟踪** - 支持 ID 跟踪，每个目标分配唯一 ID
- **实时可视化** - 显示边界框、骨骼连接、关键点、ID 和手势信息
- **多种输入源** - 支持摄像头和视频文件输入
- **输出保存** - 支持将结果保存为视频文件

## 项目结构

```
pose/
├── src/
│   └── yolo_pose/
│       ├── __init__.py          # 包入口
│       ├── __main__.py          # CLI 入口
│       ├── detector.py          # YOLO 检测器模块
│       ├── tracker.py           # 跟踪器模块（Kalman Filter + Hungarian Algorithm）
│       ├── visualize.py         # 可视化工具模块
│       ├── config.py            # 配置文件
│       └── main.py              # 主程序入口
├── tests/
│   ├── __init__.py
│   └── test_tracker.py          # 跟踪器测试
├── main.py                      # CLI 入口
├── pyproject.toml               # 项目配置
└── requirements.txt              # 依赖列表
```

## 安装

### 使用 uv（推荐）

```bash
# 1. 进入项目目录
cd d:\Documents\win-dev\uv\yolo-cam\pose

# 2. 安装依赖
uv sync
```

### 使用 pip

```bash
# 1. 进入项目目录
cd d:\Documents\win-dev\uv\yolo-cam\pose

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

## 快速开始

### 使用 uv 运行（推荐）

```bash
# 使用摄像头
uv run python main.py --source webcam

# 处理视频文件
uv run python main.py --source video.mp4

# 保存结果
uv run python main.py --source webcam --output result.mp4
```

### 使用系统 Python 运行

```bash
# 使用摄像头
python main.py --source webcam

# 处理视频文件
python main.py --source video.mp4

# 保存结果
python main.py --source webcam --output result.mp4
```

## 命令行参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--source` | str | webcam | 输入源：'webcam' 或视频文件路径 |
| `--camera-id` | int | 0 | 摄像头 ID |
| `--model` | str | yolov8n-pose.pt | YOLO 模型名称 |
| `--conf` | float | 0.5 | 置信度阈值 |
| `--iou` | float | 0.3 | IOU 阈值 |
| `--max-age` | int | 30 | 跟踪器最大保留帧数 |
| `--min-hits` | int | 3 | 确认跟踪所需最小命中数 |
| `--device` | str | None | 设备（如 'cuda:0', 'cpu'） |
| `--output` | str | None | 输出视频文件路径 |
| `--no-skeleton` | flag | - | 不显示骨骼 |
| `--no-keypoints` | flag | - | 不显示关键点 |

## 运行时控制

| 按键 | 功能 |
|------|------|
| `q` | 退出程序 |
| `r` | 重置跟踪器 |
| `s` | 切换骨骼显示 |
| `k` | 切换关键点显示 |
| `Space` | 暂停/继续（仅视频模式） |

## 模块说明

### detector.py - YOLO 检测器

```python
from yolo_pose import YOLODetector

detector = YOLODetector(
    model_name="yolov8n-pose.pt",
    conf_threshold=0.5,
    device="cuda:0"
)

result = detector.detect(frame)
for detection in result.detections:
    bbox = detection.bbox
    keypoints = detection.keypoints
    gesture_name, gesture_id = detector.recognize_gesture(keypoints, confidences)
```

### tracker.py - 多目标跟踪器

```python
from yolo_pose import Tracker

tracker = Tracker(
    max_age=30,
    min_hits=3,
    iou_threshold=0.3
)

active_tracks = tracker.update(detections)
for track in active_tracks:
    track_id = track.track_id
    bbox = track.bbox
    gesture = track.gesture_name
```

### visualize.py - 可视化工具

```python
from yolo_pose import draw_tracks, draw_info

frame = draw_tracks(frame, tracks, draw_skeleton_flag=True)
frame = draw_info(frame, frame_id, fps, track_count)
```

## 支持的手势

| 手势 ID | 手势名称 | 描述 |
|---------|----------|------|
| 0 | unknown | 未知手势 |
| 1 | standing | 站立 |
| 2 | raising_hand | 举手 |
| 3 | waving | 挥手 |
| 4 | pointing | 指向 |
| 5 | sitting | 坐着 |

## 关键点定义

模型检测 17 个人体关键点：

```
0: nose          5: left_shoulder    10: right_wrist    15: left_ankle
1: left_eye      6: right_shoulder   11: left_hip       16: right_ankle
2: right_eye     7: left_elbow       12: right_hip
3: left_ear      8: right_elbow      13: left_knee
4: right_ear     9: left_wrist       14: right_knee
```

## 性能优化建议

### 高性能配置（GPU）

```bash
python main.py --model yolov8m-pose.pt --device cuda:0 --conf 0.6
```

### 低资源配置（CPU）

```bash
python main.py --model yolov8n-pose.pt --device cpu --conf 0.4
```

## 可用的 YOLOv8-pose 模型

| 模型 | 参数量 | 速度 | 精度 |
|------|--------|------|------|
| yolov8n-pose.pt | 3.3M | 最快 | 较低 |
| yolov8s-pose.pt | 11.6M | 快 | 中等 |
| yolov8m-pose.pt | 26.4M | 中等 | 较高 |
| yolov8l-pose.pt | 44.4M | 慢 | 高 |
| yolov8x-pose.pt | 69.4M | 最慢 | 最高 |

首次运行时会自动下载模型文件。

## 依赖项

- ultralytics >= 8.0.0
- opencv-python >= 4.8.0
- numpy >= 1.24.0
- scipy >= 1.10.0
- filterpy >= 1.4.5

## 许可证

MIT License