69 lines
4.7 KiB
Markdown
69 lines
4.7 KiB
Markdown
# Earth Motion Gesture Interaction V2 Plan
|
||
|
||
**状态**：已实现主体交互，并按实测调整。当前浏览器识别保留右手导航、头部切目标、左手上下切动捕图层、双手张开/收拢缩放；双手上举确认暂时关闭。Motion 目标展示已改为 `CruiseSequencer` + `PresentationController` 的 persistent 展示。
|
||
|
||
> Update: Agent-side bidirectional commands, UE/Web shared device control, dual-camera redundant fusion, and future calibrated 3D mode are tracked in [Motion Agent v2 Control Protocol And 3D Calibration Roadmap](/home/ray/dev/linkong/planet/docs/plans/motion-agent-v2-control-protocol-plan.md).
|
||
|
||
## Summary
|
||
|
||
把动捕从“几个单点手势触发函数”升级为一套更像大屏遥控器的交互层：右手负责地球导航，头部负责候选切换，左手上下切换动捕候选图层，双手负责缩放，调试面板支持“只显示骨骼”和暂停匹配。进入动捕模式后，Earth 自动软选中屏幕中心附近的正面可交互目标；确认动作预留为把目标升级为锁定，并用巡航/引导线式详情打开，不再模拟鼠标点击。
|
||
|
||
## Key Changes
|
||
|
||
- 手势语义 v1 固定为稳健小集：
|
||
- 修正当前左右挥手语义反向问题：手势名以用户感知方向为准，provider 层输出正确 `rotate_left` / `rotate_right`。
|
||
- 右手左/右/上/下挥控制地球水平/垂直旋转，新增 `rotate_up`、`rotate_down`。
|
||
- 双手张开/靠近明确映射为 `zoom_in` / `zoom_out`。
|
||
- 头往左/右歪新增 `focus_prev` / `focus_next`，在当前自动候选目标之间切换。
|
||
- 左手上/下挥新增 `layer_prev` / `layer_next`，切换当前动捕候选图层并聚焦该图层最近目标。
|
||
- 双手确认手势暂时关闭，避免与缩放和站姿误触混淆；协议仍保留 `confirm`。
|
||
|
||
- Motion Provider / Protocol：
|
||
- 扩展 `MOTION_GESTURES`，新增 `rotate_up`、`rotate_down`、`focus_prev`、`focus_next`、`layer_prev`、`layer_next`。
|
||
- Browser Camera provider 扩展 pose joints，保留肩/肘/腕，增加头部关键点，用于判断头歪。
|
||
- 右手作为导航手；左手独立控制动捕候选图层。
|
||
- 每类手势使用独立阈值和 cooldown，避免缩放/确认/旋转互相误触。
|
||
|
||
- Earth 交互层：
|
||
- Motion adapter 支持水平/垂直旋转和 focus 切换 callback。
|
||
- 进入动捕模式后，周期性从可交互对象中选出屏幕中心最近、位于地球正面的候选。
|
||
- 软选中目标独立于 `lockedObject`，用 hover/linked 视觉态展示，不立即打开详情。
|
||
- `focus_prev` / `focus_next` 在候选列表中切换；列表按屏幕中心距离、正面可见性、当前图层可见性排序。
|
||
- `confirm` 预留为将软选中目标升级为 locked，并打开引导线详情；若没有候选，显示状态提示。
|
||
|
||
- 调试面板：
|
||
- 在动捕 HUD / drawer 内增加“只显示骨骼”开关。
|
||
- 增加“停止匹配动作”开关：暂停 gesture 执行，但不关闭摄像头预览或骨架绘制。
|
||
- 设置持久化到 `planet.earth.settings.v2.shared.motionDebugSkeletonOnly`。
|
||
- 开启后 canvas 不绘制视频帧，只绘制深色背景 + 红/绿骨骼线；摄像头仍继续用于识别。
|
||
|
||
## Test Plan
|
||
|
||
- Browser provider 单元测试：
|
||
- 右手左/右挥输出的 `rotate_left` / `rotate_right` 与用户语义一致。
|
||
- 右手上/下挥输出 `rotate_up` / `rotate_down`。
|
||
- 双手张开输出 `zoom_in`，双手靠近输出 `zoom_out`。
|
||
- 头部左右倾斜输出 `focus_prev` / `focus_next`。
|
||
- 双手确认动作暂时不会触发。
|
||
|
||
- Motion adapter 测试：
|
||
- 新增 gesture 能通过 `normalizeGestureMessage`。
|
||
- `rotate_up/down` 调用垂直旋转逻辑。
|
||
- `focus_prev/focus_next` 调用候选切换 callback。
|
||
- `confirm` 在协议层保持兼容；浏览器 provider 当前不主动发出。
|
||
|
||
- Earth 前端验证：
|
||
- 开启动捕模式后，屏幕中心附近正面目标自动软选中。
|
||
- 头歪能在候选之间切换。
|
||
- 左手上下切换图层后会在新图层中选择最近目标并展示 persistent 引导线详情。
|
||
- 右手上下挥能旋转到南北方向目标。
|
||
- “只显示骨骼”开关持久化，刷新后状态保持。
|
||
- `bun --check` 覆盖新增/修改 Earth JS 模块，现有 motion tests 全绿。
|
||
|
||
## Assumptions
|
||
|
||
- v1 采用“右手导航、头部切候选、左手切图层、双手缩放”的交互模型；确认手势保留协议但暂时关闭浏览器识别。
|
||
- 自动选中是 soft focus，不覆盖现有 mouse locked selection；只有 `confirm` 才真正锁定目标。
|
||
- 骨骼-only 只影响调试画面，不关闭摄像头、不影响识别。
|
||
- Motion Agent 协议可以接收新增 gesture 名；旧 agent 只发旧 gesture 时仍兼容。
|