planet/docs/plans/earth-motion-gesture-interaction-v2-plan.md

Earth Motion Gesture Interaction V2 Plan

状态：已实现主体交互，并按实测调整。当前浏览器识别保留右手导航、头部切目标、左手上下切动捕图层、双手张开/收拢缩放；双手上举确认暂时关闭。Motion 目标展示已改为 CruiseSequencer + PresentationController 的 persistent 展示。

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 时仍兼容。