# 基于 Mediapipe 与虚拟手柄实现的沉浸式赛车游戏交互系统

------

## 一、项目简介

本项目基于 Google 的 MediaPipe 手部追踪系统，结合自定义几何规则与信号滤波算法，实现了无需物理手柄的赛车游戏操作方式。用户通过简单自然的手势（如拇指上扬、手掌倾斜等），即可完成加速、刹车、转向等核心动作，实现“举手即控”，打造更**自然流畅、沉浸感强**的赛车体验。

系统已成功应用于 Steam 游戏 **《Rush Rally Origins》**，在实机演示中展现出流畅、精准的控制体验，广泛适用于支持 Xbox 手柄输入的竞速类游戏。

------

## 二、核心功能亮点

为提升可视性与操作便利性，系统配套开发了基于 PySide2 的图形界面，集成摄像头画面、手势识别反馈、指令图标展示与灵敏度调节等功能，支持完整的交互闭环。

**主要功能：**

| 功能项       | 实现细节                                             |
| ------------ | ---------------------------------------------------- |
| 实时画面展示 | OpenCV 摄像头采集 + QImage 渲染窗口                  |
| 手势图标反馈 | 根据识别结果在界面中央展示代表性图标（如加速、左转） |
| 文本提示     | 显示当前识别出的指令（如“加速”、“左转”）             |
| 灵敏度调节   | 滑动条实时控制手势判断敏感度（用于调试与个性化）     |
| 平滑识别     | Kalman Filter + Sigmoid 映射，过滤角度抖动与误判     |
| 虚拟控制输出 | 手势状态映射为 Xbox 指令，传递至 `vgamepad` 接口     |

**稳定机制：**

- 采用手势状态组合（如 `"left_up"`、`"unknown_bark"`）构建指令队列；
- 取历史 N 次指令中出现频率最高的结果作为最终决策；
- 实现多帧确认机制，避免“瞬时误识别”导致错误控制。

**部分功能：**

- 👋 中心图标实时展示当前识别手势
- 📷 窗口左上角显示摄像头原始图像流
- 🎚️ 窗口底部滑动条调整灵敏度
- 🔘 “退出”按钮关闭程序

> 项目整体已形成：摄像头采集 → 手势识别 → 稳定判断 → 图像反馈 → 虚拟控制 的完整闭环。

------

## 三、 技术栈一览

| 模块     | 技术方案               |
| -------- | ---------------------- |
| 图像处理 | OpenCV                 |
| 手势识别 | Mediapipe（21点追踪）  |
| 虚拟手柄 | vgamepad（XInput模拟） |
| UI界面   | PySide2（Qt5框架）     |
| 数据滤波 | Kalman Filter          |



------

## 四、安装与运行

1. 建议使用 Python 3.8（推荐 Anaconda 创建虚拟环境）
2. 安装依赖库：

```
pip install -r requirements.txt
```

3. 运行主程序：

```
python main.py
```

>  请确保电脑已连接摄像头，并支持 DirectShow 接口访问

------

## 五、使用说明

- 启动程序后将自动弹出窗口，显示摄像头画面与实时识别状态
- 系统识别以下手势并映射对应游戏操作：

| 手势           | 游戏行为 |
| -------------- | -------- |
| 👍 右手拇指上扬 | 加速     |
| 👍 左手拇指上扬 | 刹车     |
| ✋ 手掌向左倾斜 | 左转     |
| ✋ 手掌向右倾斜 | 右转     |



------

## 六、项目演示

### 1. 虚拟手柄控制演示

展示从摄像头采集 → 手势识别 → 指令生成 → 虚拟手柄控制的全过程，含实时反馈 UI 和多种手势切换效果：

<img src="./img/手柄控制.gif" alt="手柄控制演示" width="600"/>

------

### 2. 游戏实录：手势驾驶《Rush Rally Origins》

[🔗 B站视频链接（游戏实录完整版）](https://www.bilibili.com/video/BV1H5gLzsEn8?vd_source=46a0e2ec60dfb8a247c96905ee47d378)

 说明：展示项目在真实竞速游戏中的使用效果，包括自然过弯、加速等场景。
 项目已实现较高精度识别 + 流畅操作体验，证明可作为真实控制手段用于轻量竞速类游戏。
