diff --git a/sprint2/sprint2.md b/sprint2/sprint2.md new file mode 100644 index 0000000..3dd7b08 --- /dev/null +++ b/sprint2/sprint2.md @@ -0,0 +1,120 @@ +## 一、本轮迭代目标 + +本 Sprint 主要目标是完成 **基于浏览器端的手势控制系统雏形**,实现如下基础功能: + +- 搭建前端 Web 应用结构与 UI 页面 +- 集成 MediaPipe 手势识别模型,完成实时手势检测 +- 映射部分手势为系统控制行为(鼠标移动、点击等) +- 搭建基础手势处理逻辑与组件封装结构 +- 支持语音识别指令发送流程(准备后端对接) + +------ + +## 二、本轮主要完成内容 + +| 类别 | 工作内容 | +| -------- | ------------------------------------------------------------ | +| 前端搭建 | 基于 Vite + Vue 3 + TypeScript 完成项目结构、模块划分、页面初始化 | +| 手势识别 | 集成 Google MediaPipe WASM 模型,完成实时检测与渲染 | +| 控制逻辑 | 封装 `GestureHandler`、`TriggerAction`,实现手势到系统操作的映射 | +| UI设计 | 完成仪表盘式主界面设计,支持响应式、自定义手势预览等 | +| 模型结构 | 初步梳理 `Detector` 识别流程,统一封装初始化与推理逻辑 | +| 后端准备 | 初始化 Python 接口 WebSocket 构建,支持语音识别交互 | + + + +------ + +## 三、系统结构设计 + +``` +[用户摄像头] + ↓ +[VideoDetector.vue] → 捕捉视频帧,传入检测器 + ↓ +[Detector.ts] → 调用 MediaPipe 识别手势 + ↓ +[GestureHandler.ts] → 映射行为(鼠标/键盘/语音) + ↓ +[TriggerAction.ts] → 向后端/系统发出控制指令 + ↓ +[Python 后端](语音识别/扩展指令) ← WebSocket 接入 +``` + +------ + +## 四、核心技术栈与理由 + +| 技术 | 用途 | 原因 | +| ---------------- | -------------------- | ------------------------------------------ | +| Vue 3 + Vite | 前端框架 + 构建工具 | 快速开发,热更新快,Composition API 更灵活 | +| TypeScript | 增强类型约束 | 减少运行时错误,提升可维护性 | +| MediaPipe Tasks | 手势识别模型 | 体积小,支持浏览器部署,准确率高 | +| WebSocket | 前后端实时通信 | 保持实时交互流畅 | +| Python + FastAPI | 后端扩展接口(语音) | 快速搭建接口,后续支持 Py 模型运行 | + + + +------ + +## 五、主要功能点与说明 + +### 1. Detector 类封装 + +- 初始化 WASM 模型与识别器 +- 封装 `detect()` 每帧调用逻辑 +- 支持获取 `landmarks`, `gestures`, `handedness` + +### 2. 手势识别与映射 + +- 仅识别食指 → 鼠标移动 +- 食指 + 中指 → 鼠标点击 +- 食指 + 拇指捏合 → 滚动 +- 四指竖起 → 发送快捷键 +- 小指+拇指 → 启动语音识别(前端 WebSocket) + +### 3. UI 界面模块 + +- 实时视频预览窗口 +- 子窗口:手势反馈 / 执行动作提示 +- 配置面板:开关检测 / 配置行为映射 + +------ + +## 六、识别代码示例(关键手势) + +```ts +if (gesture === HandGesture.ONLY_INDEX_UP) { + this.triggerAction.moveMouse(x, y) +} +if (gesture === HandGesture.INDEX_AND_THUMB_UP) { + this.triggerAction.scrollUp() +} +``` + +- 每种手势匹配后,调用封装的 WebSocket + 系统接口发送动作 +- `TriggerAction` 支持复用 + +------ + +## 七、问题与解决方案 + +| 问题描述 | 解决方法 | +| --------------------------------- | ---------------------------------------------------- | +| WebSocket 连接后反复断开 | 增加连接状态判断 `readyState !== OPEN`,避免提前发送 | +| Tauri 插件调用 `invoke undefined` | 使用 `npm run tauri dev` 启动,而非普通浏览器启动 | +| 页面刷新后路由丢失(404) | Vue Router 改为 `createWebHashHistory()` 模式 | +| 模型未加载或报错提示 | 增加 loading 控制,捕捉初始化异常 | + + + +------ + +## 八、未来规划(Sprint 2 预告) + +| 方向 | 说明 | +| ----------------- | --------------------------------------------------- | +| 多手势拓展 | 三指滚动、多指触发多功能、多手联合判断 | +| 自定义 .task 模型 | 支持用户采集数据,自定义模型替换现有 MediaPipe 模型 | +| 后端语音指令集成 | Vosk 模型识别语音,触发系统控制 | +| 设置项管理 | 实现用户自定义快捷键、手势配置界面 |