WaveControl/README.md

WaveControl 手势识别测试模块

本目录为主项目的手势检测与识别子系统测试环境，用于独立调试、验证基于 MediaPipe 的手部 landmark 检测与自定义手势逻辑的正确性。

---

模块结构

wavecontrol-test/
├── public/               # 静态资源
├── src/                  # 前端源代码（Vue3 + TS）
│   ├── components/       # UI组件（如 VideoDetector）
│   ├── hand_landmark/    # 核心手势识别模块（detector.ts、gesture_handler.ts）
│   └── locales/          # 多语言支持（如有）
├── src-py/               # Python 辅助测试脚本（如 test_mouse.py）
├── index.html            # 主入口页面
├── main.ts               # 启动脚本
├── vite.config.ts        # 前端构建配置
├── tsconfig*.json        # TypeScript 配置
└── README.md             # 本文件

---

功能说明

本模块聚焦手部关键点检测 + 自定义手势识别逻辑的单元验证，具备如下能力：

功能点	描述
摄像头接入	调用浏览器摄像头，获取实时图像流
MediaPipe 集成	通过 detector.ts 接入 Google 手部识别模型，输出 21 个关键点数据
手势判断	通过 gesture_handler.ts 识别特定手势，如拇指上扬、握拳、转动角度等
可视化展示	VideoDetector.vue 渲染摄像头画面 + landmark 点位，辅助调试
控制台输出	打印每帧检测结果（landmark 坐标、识别状态、FPS）
Python 模拟测试	test_mouse.py 用于鼠标控制测试，独立于前端进行快速逻辑验证

实现手势功能一览

模块共识别并支持 15种核心手势动作，覆盖通用控制、游戏互动、音乐控制等多种场景，现阶段已完成如下识别逻辑与事件映射：

主控制系统

序号	手势名称	动作说明	所属类型
01	光标控制	竖起食指滑动控制光标位置	通用控制
02	鼠标左键点击	食指 + 拇指上举触发点击事件	通用控制
03	滚动控制	okay 手势（食指+拇指捏合）上下移动控制页面滚动	通用控制
04	全屏控制	四指并拢向上 → 触发设定键（默认 F 键）	通用控制
05	退格	特定手势触发退格键	通用控制
06	开始语音识别	六指（含小指）手势启动语音识别	通用控制
07	结束语音识别	握拳触发语音识别终止	通用控制
08	暂停/继续	单手张开静止 1.5 秒，触发系统暂停或继续识别	通用控制

游戏控制

序号	手势名称	动作说明	所属类型
09	向右移动	拇指上抬，其余手指收回 → 控制游戏角色向右走	游戏控制
10	跳跃	食指 + 中指上举，触发跳跃操作	游戏控制
11	右跳跃	拇指 + 食指 + 中指上举，触发右跳跃组合动作	游戏控制

音乐控制

序号	手势名称	动作说明	所属类型
12	上一首	拇指向左摆动，控制播放器切换至上一首	音乐控制
13	下一首	拇指向右摆动，切换到下一首音乐	音乐控制
14	暂停/播放	比耶手势（✌️ / 🤘）控制音乐播放或暂停	音乐控制

模式切换

序号	手势名称	动作说明	所属类型
15	切换音乐模式	rock 手势（🤘）触发音乐控制模式与普通模式的切换	模式切换

📌 说明：

• 所有手势动作识别基于 MediaPipe 提供的 21 关键点；
• 每个手势映射事件已封装在 gesture_handler.ts 中；
• 可通过修改 gesture_map 动态扩展或调整触发逻辑；
• 模块支持平滑滤波、多帧确认机制，显著减少误识别。

快速启动（开发模式）

cd wavecontrol-test
npm install
npm run dev

默认运行在 http://localhost:5173，页面为空白属正常现象，请使用浏览器开发者工具调试。

---

调试指南

• 打开开发者工具（F12）：
  • Console：查看关键日志（手势判断结果、识别帧率等）
  • Network：确认资源加载是否成功（如 MediaPipe 模型）
  • Elements：手动挂载 VideoDetector 测试组件进行可视化验证

此模块未接入主 UI 路由体系，可作为“独立沙箱”运行，便于开发期间快速验证识别效果。

---

典型用例

• ✅ 验证 gesture_handler.ts 中的规则逻辑是否准确
• ✅ 查看 landmark 点是否能稳定输出（避免帧丢失）
• ✅ 测试新手势添加逻辑的正确性
• ✅ 结合 Python 脚本快速验证控制指令映射逻辑