# Software-Engineering

**Repository Path**: wydhhh/software-engineering

## Basic Information

- **Project Name**: Software-Engineering
- **Description**: WaveControl 隔空手势控制系统——一套融合手势识别与语音控制的非接触式人机交互系统，包含主控制平台、手语学习平台 WaveSign、赛车游戏控制模块三大子系统，致力于打造自然、高效、多场景适配的“举手即控”体验。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-07-01
- **Last Updated**: 2025-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 手势识别, 鼠标控制, 听障服务, 软件工程, 电脑桌面应用

## README

# 📡 WaveControl 隔空手势控制系统

> 一套融合**手势识别**与**语音控制**的非接触式人机交互系统，包含主控制平台、手语学习平台 WaveSign、赛车游戏控制模块三大子系统，致力于打造自然、高效、多场景适配的“举手即控”体验。

![Vue](https://img.shields.io/badge/frontend-vue3-brightgreen)
![Python](https://img.shields.io/badge/backend-django4-blue)
![MediaPipe](https://img.shields.io/badge/AI-MediaPipe-orange)
![VOSK](https://img.shields.io/badge/Voice-VOSK-red)
![Coverage](https://img.shields.io/badge/test--coverage-93%25-success)


## 一、项目介绍

### 1.1 项目简介

在厨房、医疗、演讲等“无法触控”或“不便触控”的环境中，传统鼠标/键盘交互模式效率低、操作受限。**WaveControl**以此为切入点，构建了一个基于摄像头识别的隔空控制系统，融合手势识别与语音识别，实现对系统级输入（键盘/鼠标）、手语教学以及游戏控制等功能。

项目采用模块化架构设计，包含三大子系统：

1. **主控制平台**：支持窗口操作、媒体控制、鼠标替代、游戏映射、语音增量输入等功能
2. **赛车游戏交互系统**：实现与《Rush Rally Origins》等赛车游戏的隔空手柄交互
3. **WaveSign 手语通**：面向听障人群的手语学习与社区互动平台

以及两个关联的扩展模块：

1. **google docs翻页插件**：支持特定左右手势对google docs中ppt的翻页的一款Chrome插件，支持跨设备使用等功能
2. **screenshot 手势截图工具**：支持通过手势绘制区域截图的一款独立窗口工具，支持多元摄像设备调用，自由绘制视界中的区域，以及传入录制视频流、代替实时传入视频等功能

### 1.2 项目愿景与背景动机

在厨房、医疗、演讲等“无法触控”或“不便触控”的场景中，传统鼠标/键盘交互方式往往效率低下、体验不便。我们旨在通过 WaveControl 实现：

- 🚫 摆脱物理接触的束缚
- 🤝 用动作和声音控制数字世界
- 🧩 打造可适配多种实际场景的通用交互平台


### 1.3 项目需求分析文档 📄

> 项目需求结构已为 WaveSign 平台提供完备需求文档支持，作为本项目落地实践的一个商业化案例；其余模块以功能设计表+迭代日志形式覆盖，以多元交互的“工具箱”的形式体现，的实用保证开发结构完整性。

📃 **WaveSign 子系统需求文档**

> 该文档详细描述了 WaveSign 的目标用户、核心功能模块、用例图、界面流程、评分逻辑与生活服务设计等内容。

- 🧑‍🦯 适用对象：听障用户与学习手语人群
- 🧩 覆盖模块：手语评分系统 / 社区模块 / 日程提醒 / 出行服务等
- 🗺️ 工具支持：draw.io 流程图 + Markdown 编写
- 📎 文档链接：[查看 WaveSign 项目需求文档](https://gitee.com/wydhhh/software-engineering/blob/wavesign/WaveSign%E9%9C%80%E6%B1%82%E5%88%86%E6%9E%90%E6%96%87%E6%A1%A3.md)


## 二、系统架构与技术实现

### 2.1 系统模块组成

WaveControl 采用前后端分离 + 多模态融合设计，整体模块划分如下：

| 模块名称       | 描述                                                         |
| -------------- | ------------------------------------------------------------ |
| 🖥️ 主控制平台   | 手势控制系统级窗口、鼠标、媒体，支持语音辅助，界面直观、响应实时 |
| 🕹️ 游戏控制系统 | 手势转化为虚拟手柄操作，实现赛车游戏无设备操控               |
| 🧏 WaveSign     | 手语识别、评分、课程地图、社区互动与生活助手服务为一体的平台 |
| 🧩 插件扩展     | 包括 PPT 手势控制插件、手势截图工具、语音实时字幕扩展模块    |



### 2.2 🔧技术架构

| 层级         | 技术方案                                                     |
| ------------ | ------------------------------------------------------------ |
| 前端         | vue3 + TypeScript +HTML + CSS + Tailwind CSS + JavaScript + PySide2（Qt GUI） |
| 后端         | Django 4.x（主平台 + 手语通） + Python 脚本逻辑（游戏控制）  |
| 手势识别     | MediaPipe Hand Landmarker                                    |
| 虚拟设备控制 | 键盘鼠标模拟、vgamepad 虚拟手柄（XInput）                    |
| 数据处理     | Kalman Filter（手势抖动滤波）、SQLite3 数据库                |



### 2.3 🤖 技术亮点与新技术实践

- 🔍 **AI 模型集成**：
  - 手势识别：Google MediaPipe（实时关键点提取）
  - 语音识别：VOSK 脱网模型（本地语音转文本 + 多语言支持）
- 📦 **跨平台打包**：
  - Windows：PyInstaller
  - macOS：py2app
  - Linux：shell 启动包+Docker Compose
- 🧠 **自研逻辑**：
  - 手语评分：基于欧氏距离、轨迹匹配、节奏多维度分析
  - 滤波优化：Kalman Filter 平滑手势波动，提高游戏控制稳定性


## 三、项目功能模块

### 1️⃣ 主控制平台（WaveControl）

✌️ **功能特色**

- 多种预设手势操作（点击、滚动、后退等）
- 手势范围调节与自定义手势库
- 支持语音识别辅助控制
- 界面直观，状态反馈实时

🎯 **应用场景**

- 📺 沙发上追剧时，不再找遥控器，用手势暂停/快进
- 👨‍🏫 教学/演讲中，用手势控制 PPT 流畅翻页
- 🧑‍🍳 厨房做饭时，隔空查食谱不怕弄脏设备
- 🏥 医疗/无菌操作室中，非接触式操作电脑界面
- 🕹️ 游戏中挥手即控，沉浸感倍增

🖼️  **UI 示例**

- 控制主面板（准确率/响应时间/识别窗口）
- 手势管理面板（快捷操作映射设置）


### 2️⃣ 游戏控制模块

🔗 项目演示：[游戏控制项目演示视频](https://www.bilibili.com/video/BV1H5gLzsEn8?vd_source=46a0e2ec60dfb8a247c96905ee47d378)

🎮 目标：**无需实体手柄，通过摄像头即可玩赛车游戏！**

适配游戏：Steam平台《Rush Rally Origins》及支持 Xbox手柄的其他游戏

**实现要点：**

| 功能         | 技术说明                                                    |
| ------------ | ----------------------------------------------------------- |
| 摄像头识别   | OpenCV + MediaPipe                                          |
| 手势控制映射 | 👍右手拇指上扬 = 加速 👍左手 = 刹车 ✋左倾 = 左转，右倾 = 右转 |
| 虚拟手柄接口 | vgamepad + XInput                                           |
| 抖动滤除     | Kalman 滤波器平滑动作                                       |
| UI反馈       | PySide2 构建调试窗口                                        |



### 3️⃣ 手语通子项目：**WaveSign**

🔗 项目演示：[手语通项目演示视频](https://www.bilibili.com/video/BV1Fig5zHEhq?vd_source=46a0e2ec60dfb8a247c96905ee47d378)

项目定位：帮助听障人群及其家人朋友学习、练习、交流手语的综合平台

**功能模块：**

- ✅ **手语教学与评分系统**：上传视频或用摄像头练习手语动作，系统打分反馈
- 🗺️ **课程地图与互动练习**：任务式学习，配合卡片式巩固练习
- 👥 **社区交流**：发帖、评论、点赞、关注等功能
- 📅 **日程管理**：内置待办事项与日历，辅助学习安排
- 🧭 **生活服务**：
  - 出行导航（结合地图与实时提醒）
  - 辅助器具推荐
  - 就业信息推送
  - 无障碍亲子/技能活动预告

**技术实现：**

- Django + SQLite 构建用户系统与服务逻辑
- 使用 MediaPipe 实时评分用户手语表现
- 前端页面响应式 + 卡片式交互体验

### 4️⃣Chrome插件——google docs翻页支持

🌟 项目演示：详见PPT/下方视频演示

🎮 目标：**实现项目的多元部署方式，支持独立插件便捷安装的PPT翻页办公体验！**

| 功能         | 技术说明                                                     |
| ------------ | ------------------------------------------------------------ |
| 网页端       | 基于 React 和 TypeScript 开发，使用 CSS 进行样式管理，具备部署到 GitHub Pages 的配置 |
| 插件端       | 基于 React 和 TypeScript 构建界面与逻辑，Webpack 负责模块打包，CSS 处理样式，同时依托 Chrome Extension API 实现浏览器扩展功能 |
| 独立后台服务 | 采用 Python（基于 Flask 框架，通过 app.py 实现）作为后端开发语言，借助 Heroku 进行部署，并通过 requirements.txt 和 runtime.txt 管理项目依赖与运行时环境。 |


### 5️⃣ screenshot截图工具——手势绘图的区域截图体验

🌟 项目演示：详见PPT/下方视频演示

🎮 目标：**探索手势识别/硬件交互与调用的高级玩法，拓展项目的模块功能与应用边界！****

| 功能部分         | 实现说明                                                     |
| ---------------- | ------------------------------------------------------------ |
| 手势数据处理     | 通过`gesture_data.py`进行手势相关数据的存储、读取等操作      |
| 手势绘制         | 由`finger_drawer.py`运用 Python 图形库来实现手指绘制相关功能 |
| 手势处理         | 在`gesture_process.py`中对采集到的手势信息进行预处理等操作   |
| 手部手势整体处理 | `hand_gesture.py`整合各部分功能，实现对手部手势的综合处理    |
| 食指相关功能     | `index_finger.py`专注于与食指相关的特定功能开发              |
| 卡尔曼滤波       | `kalman_filter.py`实现卡尔曼滤波算法，用于对手势数据的滤波优化 |
| 模型相关操作     | `model.py`依靠模型库来使用模型                               |
| 图像预处理       | `process_images.py`使用图像处理库对图像进行相应处理操作      |
| 视频手势识别     | `video_recognition.py`使用视频处理库实现从传入视频流中识别手势的功能 |
| 图形用户界面     | `GUI.py`利用 Python 的 GUI 库（Tkinter）来创建可视化的用户交互界面，整合并启动我们的项目 |

### 4️⃣ 插件与增量功能

> “灵活轻量，拓展无限”

- 🧩 **PPT 手势控制插件**
   → 用左右滑手势控制演示翻页，适用于教师与演讲者
- 🖼️ **手势截图工具**
   → 隔空触发屏幕截图，便于反馈 Bug 或教学截图
- 🧠 **语音识别字幕条（VOSK 增量模型）**
   → 实时语音字幕提示，提升多模态交互反馈体验


## 四、测试体系与覆盖情况

本项目配套了完整的[测试文档](./项目测试文档.md)，涵盖以下子模块：

- ✅ **主控制系统测试程序**：手势识别 → 键盘鼠标映射 → 交互反馈
- ✅ **游戏控制测试程序**：手势实时识别 → 虚拟手柄信号发送 → 赛车游戏响应验证
- ✅ **手语识别与打分测试程序**：摄像头实时捕捉动作 → MediaPipe评分 → UI动画与文本反馈
- ✅ **用户交互测试**：社区发帖、点赞评论、任务管理、日程提醒等核心功能均有覆盖

测试方式支持浏览器调试 + 控制台运行日志追踪，若遇白屏可通过 Chrome DevTools 检查模块加载或路径引用情况。


## 五、Git 提交与迭代记录

> 本项目自立项以来经历多个重要版本阶段，总提交量超 **425 次**，涵盖主控制逻辑、游戏控制、手语通平台、插件工具等模块。采用多分支协作开发 + 持续集成测试 + 定期合并策略，确保系统稳定演进。

📊 本项目已使用 Gitee 进行协作开发，完整展示了：

- 分支管理（`branches`）
- 合并流程（`merges`）
- 任务分配（`issues`）
- 版本标记（`tags`）
- 提交频率追踪（`commits`）

🔗 仓库链接：[Gitee 地址](https://gitee.com/wydhhh/software-engineering)

### 5.1 Git 分支说明

| 分支名               | 描述                                                         | 跳转链接                                                     |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `master`             | 主分支，已完成整合，适用于演示与部署                         | [🔗 master 分支](https://gitee.com/wydhhh/software-engineering/tree/master/) |
| `finalv1`            | 前后端初步融合尝试，手势 → 页面响应逻辑测试阶段              | [🔗 finalv1](https://gitee.com/wydhhh/software-engineering/tree/finalv1/) |
| `finalv2`            | 完成手势识别与前端事件联动，页面按钮联动测试                 | [🔗 finalv2](https://gitee.com/wydhhh/software-engineering/tree/finalv2/) |
| `finalv3`            | 增加语音识别、手势控制切换、音乐控制、手语平台接入、各子系统联调优化 | [🔗 finalv3](https://gitee.com/wydhhh/software-engineering/tree/finalv3/) |
| `gesture`            | 手势识别逻辑独立开发模块                                     | [🔗 gesture](https://gitee.com/wydhhh/software-engineering/tree/gesture/) |
| `gesture_for_chrome` | 针对 Chrome 插件开发的手势控制方案（PPT翻页）                | [🔗 gesture_for_chrome](https://gitee.com/wydhhh/software-engineering/tree/gesture_for_chrome/) |
| `gesture-game`       | 初步游戏控制实验，控制小球移动                               | [🔗 gesture-game](https://gitee.com/wydhhh/software-engineering/tree/gesture-game/) |
| `game_control`       | 控制《Rush Rally Origins》赛车游戏，已支持加速转向等         | [🔗 game_control](https://gitee.com/wydhhh/software-engineering/tree/game_control/) |
| `wavesign`           | 手语通子系统开发主线，包括教学评分、社区、日程等             | [🔗 wavesign](https://gitee.com/wydhhh/software-engineering/tree/wavesign/) |
| `web`                | 最初的网页原型设计，UI 静态草稿                              | [🔗 web](https://gitee.com/wydhhh/software-engineering/tree/web/) |
| `screenshot`         | 手势控制截屏模块，用于快速抓取操作界面                       | [🔗 screenshot](https://gitee.com/wydhhh/software-engineering/tree/screenshot/) |
| `vosk_inc`           | 接入 VOSK 实现语音识别与实时字幕展示                         | [🔗 vosk_inc](https://gitee.com/wydhhh/software-engineering/tree/vosk_inc/) |


### 5.2 提交统计（截至 2025.7.23）

| 项目阶段           | 主要分支                        | 提交次数 | 关键词                           |
| ------------------ | ------------------------------- | -------- | -------------------------------- |
| 原型开发阶段（v1） | `gesture`、`web`                | ~60 次   | UI草图、MediaPipe接入、手势验证  |
| 系统整合阶段（v2） | `finalv1`                       | ~45 次   | 主控制系统框架、页面响应交互     |
| 功能扩展阶段（v3） | `finalv2`、`gesture_for_chrome` | ~70 次   | 语音控制、PPT插件、游戏交互实验  |
| 稳定优化阶段（v4） | `finalv3`、`game_control`       | ~80 次   | 虚拟手柄联调、滤波优化、语音字幕 |
| WaveSign构建阶段   | `wavesign`                      | ~45 次   | 手语评分系统、社区功能、日程管理 |
| 增量与插件阶段     | `vosk_inc`、`screenshot`        | ~25 次   | 字幕提示、截图控制模块           |

🔖 **总提交数**：约 **425+** 次


### 5.3 迭代亮点

- **第1轮迭代**：系统原型 + UI设计 + 手势识别框架
- **第2轮迭代**：主平台功能实现 + 手势控制实现
- **第3轮迭代**：打通语音识别 + 游戏交互控制 + 手语通平台初步实现
- **第4轮迭代**：赛车游戏交互实现 + 手语通平台完整搭建
- **第5轮迭代**：性能优化 + 测试覆盖 + 跨平台打包 + 用户调研反馈迭代

🧪 每个阶段均伴随高频提交、模块测试、可视化交互记录，体现完整的工程实现路径与开发严谨性。



### 5.4 Git 代码变更统计（截至 2025.7.23）

> 统计来源：命令行执行
>  `git log --shortstat --pretty="%H"` + `awk` 聚合分析

| 指标项         | 数值          |
| -------------- | ------------- |
| 提交次数总计   | **425 次**    |
| 新增代码行数   | **101013 行** |
| 删除代码行数   | **10721 行**  |
| 总代码变更行数 | **111734 行** |

📌 这些数字不仅展示了开发规模，也体现了每次功能更新、Bug修复、模块优化的背后都有实际代码支撑，真实体现项目复杂度与开发深度。


### 5.5 Git 问题追踪（Issue Tracking）

> 项目采用 **Gitee Issue 功能** 对开发中遇到的技术问题进行记录、分配、跟踪与关闭，反映团队问题处理能力与协作效率。

🧩 **已记录并解决的典型问题包括：**

| 问题类型          | 简要说明                                       | 状态     |
| ----------------- | ---------------------------------------------- | -------- |
| 模式切换 Bug      | music/normal 模式切换时逻辑冲突                | ✅ 已解决 |
| 播放异常          | 手势识别误触导致音频暂停与频繁切换             | ✅ 已解决 |
| 视频窗口刷新问题  | 游戏视频区域刷新逻辑缺陷                       | ✅ 已解决 |
| Kalman 报错       | PyKalman 导入异常，脚本退出                    | ✅ 已解决 |
| Wavesign 加载失败 | jsDelivr 资源 CDN 失败，影响平台页面加载       | ✅ 已解决 |
| Wavesign 报错     | SLCourse.js defaultOpen 引发 click 报错        | ✅ 已解决 |
| Tauri 打包失败    | 本地缺失安装权限导致 .exe/.msi 构建失败        | ✅ 已解决 |
| 手柄驱动适配问题  | vgamepad 驱动无法识别虚拟手柄（ViGEmBus 适配） | ✅ 已解决 |

🧾 共记录 `8+` 个核心问题，全部在发布前解决，提升了系统稳定性与最终体验。


### 5.6 Git 版本发布（Tags）

我们基于 Gitee 的 tag 功能进行了版本控制和里程碑标记，便于阶段性测试与发布。

| 标签版本 | 提交时间         | 描述                                     |
| -------- | ---------------- | ---------------------------------------- |
| `v1.0.1` | 2025-07-08 03:03 | 首个版本：基础功能完成                   |
| `v2.0.1` | 2025-07-14 04:43 | 第二版：手势控制可用于鼠标操作           |
| `v3.0.1` | 2025-07-23 00:44 | 最终整合版：集成所有子系统功能并完成打包 |

📌 各版本均已打包成可执行程序，支持 `下载 / 运行 / 回退` 等版本管理操作。


## 六、部署与运行方式

✅ 支持 macOS / Windows / Linux 跨平台运行

✅ 支持独立应用打包与安装/浏览器跨平台使用，支持拓展模块/工具的独立运行使用

📦 打包工具：py2app、PyInstaller、Docker Compose

⚙️ 配置方式：`.env` 环境变量统一管理数据库 & 密钥


## 七、项目功能现场演示亮点

我们已录制关键模块功能演示视频，覆盖：

- 🎮 赛车游戏隔空操作全过程（加速、转向、反馈）
- 📄 PPT 手势控制插件/手绘截图工具实际使用演示
- 🧏 手语学习与评分流程（练习 → 识别 → 动画打分）
- 🖱️ 手势替代鼠标主控制系统演示

📎 观看链接：

- 游戏控制：[视频链接](https://www.bilibili.com/video/BV1H5gLzsEn8)
- 手语通演示：[视频链接](https://www.bilibili.com/video/BV1Fig5zHEhq)
- 手势识别控制PPT切换演示：[视频链接](https://www.bilibili.com/video/BV1kTgpzVEPw/?spm_id_from=333.1387.homepage.video_card.click&vd_source=98aa00678b3622dbfb6d560d6576535b)

(部分未列举视频请参考答辩PPT上的短视频/动图)

## 八、项目价值与未来方向

我们相信 WaveControl 并非只是一个技术实验项目，它的意义远不止于此。

- 🌐 **新型交互方式探索者**：更贴近本能的人机交互体验
- 🧏 **无障碍公益平台践行者**：让技术温暖每个沟通受限的人
- 🕹️ **非侵入式游戏交互先锋**：挥手即控，沉浸增强
- 🩺 **非接触式交互落地者**：助力医疗、工业等场景降本提效


## 九、团队分工

我们采用职责明确、协同开发的模式推进本项目，各成员在系统架构、核心功能、测试部署等方面各有专长，形成高效协作闭环：

### 🌟 王云岱（队长）

- 📌 **项目统筹协调**：系统整体架构设计、任务分配与开发进度管理
- 🎤 **语音识别功能开发**：基于 VOSK 引擎的离线语音识别与字幕提示系统实现
- 🧠 **语言增量识别优化**：识别准确率提升方案设计与模型调优
- 📄 **插件开发**：PPT 手势控制插件（Chrome 插件形式）
- 🖼️ **截图模块实现**：手势截图工具功能开发与集成测试

### ✋ 朱子玥

- 🔍 **手势识别核心算法开发**：MediaPipe + 自研逻辑判断模块
- 🧩 **主控平台融合开发**：Python + Vue3 完成前后端功能对接与测试
- 🖥️ **打包部署**：使用 PyInstaller 构建 Windows 平台安装程序
- 🎮 **游戏控制系统实现**：赛车游戏模块中手势映射设计与逻辑验证
- 🤝 **协作开发 WaveSign 平台**：配合构建手语识别评分与交互逻辑

### 🧑‍🎨 杨嘉莉

- 🧱 **前端框架与 UI 搭建**：基于 Vue3 + ElementPlus 设计响应式前端界面
- 🧩 **平台融合协作**：协助主控平台功能联调与组件复用
- 🍎 **macOS 打包支持**：使用 py2app 适配 macOS 应用部署
- 📱 **WaveSign 平台开发**：前后端交互联调、UI界面优化与交互设计
- 💬 **平台反馈系统构建**：用户打分结果提示与互动逻辑测试验证