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

**Repository Path**: ye-ccc/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-05-20
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MediaPipe 手势识别 PPT 控制系统

## 概述

基于 MediaPipe Hands 的实时手势识别系统，通过摄像头捕捉手部动作，将手势映射为 PPT 控制命令（翻页、黑屏、数字跳转等），并通过 PyQt5 图形界面实时反馈识别结果。

**主要功能**

- 实时手部 21 个关键点检测与骨骼可视化
- 11 种手势识别（握拳/张开/数字1\~5/上下左右滑动/拇指竖起）
- 手势→PPT 按键映射（PageDown/PageUp/B/F5 等）
- PyQt5 图形界面（视频画面 + 手势信息 + 操作日志）
- 防抖控制与 FPS 监控

**版本**：1.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_Work/
├── main.py                          # 程序入口（项目集成）
├── hand_detector/                   # 手部检测模块
│   ├── __init__.py
│   ├── detector.py
│   ├── README.md
│   └── tests/
│       └── test_detector.py
├── gesture_recognizer/              # 手势识别模块
│   ├── __init__.py
│   ├── recognizer.py
│   ├── README.md
│   └── tests/
│       └── test_recognizer.py
├── controller/                      # 控制与系统集成模块
│   ├── __init__.py
│   ├── controller.py
│   ├── README.md
│   └── tests/
│       └── test_controller.py
├── gui/                             # 用户界面模块
│   ├── __init__.py
│   ├── gui.py
│   ├── README.md
│   └── tests/
│       └── test_gui.py
├── mp_venv/                         # Python 虚拟环境
├── 环境配置说明.md                   # 详细环境配置指南
└── tests/                           # 集成测试
    └── test_gesture_and_controller.py
```

***

## 模块与分工

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

***

## 安装

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

```bash
# 1. 创建虚拟环境
python -m venv mp_venv

# 2. 激活虚拟环境
.\mp_venv\Scripts\activate

# 3. 安装依赖
pip install numpy==1.26.4
pip install mediapipe==0.10.21
pip install opencv-python==4.13.0.92
pip install PyQt5==5.15.11
pip install pyautogui==0.9.54
```

***

## 快速开始

```bash
# 激活虚拟环境
.\mp_venv\Scripts\activate

# 运行主程序
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, ...}
```

| 手势           | 值               | PPT 映射   |
| ------------ | --------------- | -------- |
| FIST         | `"FIST"`        | B（黑屏）    |
| OPEN         | `"OPEN"`        | F5（放映）   |
| SWIPE\_RIGHT | `"SWIPE_RIGHT"` | PageDown |
| SWIPE\_LEFT  | `"SWIPE_LEFT"`  | PageUp   |

### 3. Controller（控制器）

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

```python
ctrl.execute_by_gesture("SWIPE_RIGHT") -> (True, "pagedown")
```

### 4. MainWindow（主窗口）

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

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

***

## 数据流

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

***

## 运行测试

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

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

***

## 手势映射表

| 手势                      | 按键       | PPT 操作 |
| ----------------------- | -------- | ------ |
| SWIPE\_RIGHT            | PageDown | 下一页    |
| SWIPE\_LEFT / SWIPE\_UP | PageUp   | 上一页    |
| FIST                    | B        | 黑屏/恢复  |
| OPEN                    | F5       | 从头放映   |
| ONE                     | 1        | 第 1 页  |
| TWO                     | 2        | 第 2 页  |
| THREE                   | 3        | 第 3 页  |

***

## 注意事项

1. 运行前确保摄像头未被其他程序占用
2. 手势识别需在光线充足、背景简洁的环境中进行
3. 如遇 DLL 错误，请参考 [环境配置说明.md](环境配置说明.md)
4. 退出程序时自动释放摄像头和模型资源