# 手势识别智能PPT控制系统

**Repository Path**: XMwumang/GRIP

## Basic Information

- **Project Name**: 手势识别智能PPT控制系统
- **Description**: Gesture Recognition Intelligent PPT Control System，即手势识别智能PPT控制系统，通过手势控制PPT翻页与交互，适用于演讲与会议，提升演示体验。
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-04-22
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MediaPipe 手势识别 PPT 控制系统

## 概述

基于 MediaPipe Hands 的实时手势识别系统。采用**修饰键手势模式**：先五指张开 (OPEN) 进入准备态，再切换手势触发 PPT 控制命令。通过 PyQt5 图形界面实时反馈识别结果。

**主要功能**

- 实时手部 21 个关键点检测与骨骼可视化
- 修饰键手势模式（OPEN 作为修饰键，防误触）
- 5 组 OPEN + 手势 → PPT 按键映射
- pyautogui 键盘模拟（翻页、放映、黑屏、退出）
- PyQt5 图形界面（视频画面 + 手势信息 + 操作日志 + 状态栏）
- 防抖控制与 FPS 监控

**版本**：2.0
**Python 要求**：≥ 3.8
**依赖**：opencv-python==4.13.0.92、mediapipe==0.10.21、pyautogui==0.9.54、PyQt5==5.15.11、numpy==1.26.4

***

## 项目结构

```
GRIP/
├── main.py                          # 程序入口（项目集成）
├── demo.py                          # 独立演示程序
├── CONTEXT.md                       # 领域术语表
├── docs/
│   └── adr/
│       └── 0001-modifier-gesture-pattern.md
├── hand_detector/                   # 手部检测模块
│   ├── detector.py
│   ├── README.md
│   └── tests/
├── gesture_recognizer/              # 手势识别模块
│   ├── gesture_recognizer.py
│   ├── README.md
│   └── tests/
├── controller/                      # 控制与系统集成模块
│   ├── controller.py
│   ├── README.md
│   └── tests/
├── gui/                             # 用户界面模块
│   ├── gui.py
│   ├── README.md
│   └── tests/
└── tests/                           # 集成测试
    └── test_gesture_and_controller.py
```

***

## 模块与分工

| 模块                   | 核心类                 | 说明                                 |
| -------------------- | ------------------- | ---------------------------------- |
| `hand_detector`      | `HandDetector`      | 摄像头管理、MediaPipe Hands 关键点提取、FPS 监控 |
| `gesture_recognizer` | `GestureRecognizer` | 手指计数、滑动检测、手势分类                     |
| `controller`         | `Controller`        | 修饰键模式状态机、手势→按键映射、pyautogui 模拟、防抖日志 |
| `gui`                | `MainWindow`        | PyQt5 界面、视频显示、信息面板、状态栏             |
| `main.py`            | —                   | 项目集成入口，组装所有模块，支持 GUI/控制台两种模式      |

## 安装

### 使用 uv（推荐）

```bash
# 同步依赖（自动创建虚拟环境）
uv sync

# 或仅安装核心依赖
uv pip install numpy==1.26.4 mediapipe==0.10.21 opencv-python==4.13.0.92 PyQt5==5.15.11 pyautogui==0.9.54
```

### 使用 pip

参见 [环境配置说明.md](环境配置说明.md)

```bash
python -m venv mp_venv
.\mp_venv\Scripts\activate
pip install -r requirements.txt
```

## 快速开始

```bash
# 以管理员权限运行（pyautogui 模拟按键需要）
uv run python main.py
```

***

## 核心接口

### 1. HandDetector（手部检测器）

**模块路径**：`hand_detector.HandDetector`

| 方法                                | 说明        |
| --------------------------------- | --------- |
| `open_camera() -> bool`           | 打开摄像头     |
| `read_frame() -> (bool, ndarray)` | 读取一帧图像    |
| `process_frame(frame)`            | 执行手部关键点检测 |
| `get_landmarks_list() -> List`    | 获取所有手部关键点 |
| `draw_landmarks(frame)`           | 绘制关键点与骨骼  |
| `get_fps() -> float`              | 获取当前帧率    |

### 2. GestureRecognizer（手势识别器）

**模块路径**：`gesture_recognizer.GestureRecognizer`

```python
recognizer.recognize(landmarks_list) -> dict
# 返回: {"gesture": "FIST", "fingers": [...], "total_fingers": 0, ...}
```

返回的 `gesture` 值已去除内部 `GESTURE_` 前缀。

### 3. Controller（控制器）

**模块路径**：`controller.Controller`

采用修饰键手势模式：`OPEN`（五指张开）作为修饰键，进入准备态后再切换手势触发命令。

```python
ctrl.execute_by_gesture("FIST") -> (True, "escape")
```

### 4. MainWindow（主窗口）

**模块路径**：`gui.MainWindow`

```python
window.set_hand_detector(detector)
window.set_gesture_recognizer(recognizer)
window.set_controller(controller)
```

状态栏显示 IDLE / READY / COOLDOWN 三种状态。

***

## 数据流

```
摄像头 → HandDetector → GestureRecognizer → Controller → pyautogui → PPT
            ↓                ↓                ↓
          MainWindow ← 显示手势/手指/日志 ←
```

***

## 运行测试

```bash
# 运行全部模块测试
uv run python -m unittest discover -s hand_detector/tests -v
uv run python -m unittest discover -s gesture_recognizer/tests -v
uv run python -m unittest discover -s controller/tests -v
uv run python -m unittest discover -s gui/tests -v

# 运行集成测试
uv run python -m unittest tests.test_gesture_and_controller -v
```

## 手势命令映射

| 修饰手势 | 操作手势 | 按键 | PPT 功能 |
|----------|----------|------|----------|
| OPEN（五指张开） | FIST（握拳） | Esc | 结束放映 |
| OPEN（五指张开） | SWIPE_LEFT（左滑） | PageUp | 上一页 |
| OPEN（五指张开） | SWIPE_RIGHT（右滑） | PageDown | 下一页 |
| OPEN（五指张开） | SWIPE_UP（上滑） | F5 | 开始放映 |
| OPEN（五指张开） | SWIPE_DOWN（下滑） | B | 黑屏/恢复 |

### 使用方式

1. 🖐 **五指张开**保持 0.5 秒 → 状态栏显示"准备态"
2. 在 2 秒内切换到目标手势（握拳/滑动）
3. 目标手势保持 0.3 秒 → 触发对应按键
4. 执行后有 0.8 秒冷却

## 注意事项

1. 运行前确保摄像头未被其他程序占用
2. 手势识别需在光线充足、背景简洁的环境中进行
3. **必须以管理员权限运行**，否则 pyautogui 无法模拟按键
4. 如遇 DLL 错误，请参考 [环境配置说明.md](环境配置说明.md)
5. 退出程序时自动释放摄像头和模型资源
6. 更多设计细节参见 [CONTEXT.md](CONTEXT.md) 和 [docs/adr/](docs/adr/)