planet/docs/plans/earth-motion-capture-gesture-control-plan.md

Earth Motion Capture Gesture Control Plan

Goal

为 Planet Earth 大屏和未来 3D 展示增加一套解耦的动作捕捉手势控制能力。实时输入分成两条路线：网页端可直接通过浏览器 getUserMedia 在本机识别；高级设备可继续使用本机 Motion Capture Edge Agent。两条路线都只输出轻量语义事件，客户端负责把“手势事件”映射到“具体交互函数”。

首版面向两颗 Logitech C1000 RGB 摄像头，但必须保持单摄像头兼容。后续任何 USB 摄像头、手机摄像头、RTSP/HTTP/WebRTC 视频源都应通过输入适配器接入，而不是改 Earth 渲染端。

Architecture

实时链路分两种 provider，但进入 Earth 后协议一致：

Browser camera -> browser-local recognizer -> Motion Provider events -> Earth control functions
Camera(s)/RTSP/HTTP -> Local Motion Capture Agent -> local WebSocket -> Motion Provider events -> Earth control functions

关键原则：

• 实时控制不经过 SaaS 云端。
• 实时控制不复用现有新闻、RSS、聚合数据接口。
• 浏览器 provider 和 Agent provider 都不向云端上传视频帧，只输出低带宽语义事件。
• Web/3D 客户端只消费统一事件并执行映射，不把具体输入源写进 Earth 交互逻辑。
• 双摄首版用于冗余和稳定性，不承诺完整 3D 姿态重建。

Motion Providers

Earth 使用统一 Motion Provider 抽象：

• browser_camera：默认 provider。使用 getUserMedia 获取摄像头，在浏览器本地加载 MediaPipe Tasks Vision，输出 gesture / skeleton / status 事件。适合 SaaS、WSL、Windows 浏览器、大屏演示和“不安装 app”的用户。
• motion_agent：连接本地 Agent WebSocket。适合双摄、USB index、RTSP/HTTP 视频源、边缘设备和客户端集成。

设置项保存在 planet.earth.settings.v2.shared.motionProvider。?motionProvider=browser 强制浏览器摄像头，?motionProvider=agent 或 ?motionAgent=ws://... 强制 Motion Agent。

Motion Capture Agent

Agent 是本地 Edge 服务，职责包括：

• 读取摄像头：默认 USB index，支持单摄、双摄和未来 URL 视频源。
• 运行识别：首版使用 OpenCV + MediaPipe；识别引擎藏在接口后，未来可替换为 ONNX、TensorRT、C++ 或 Rust worker。
• 输出事件：通过 WebSocket 推送 gesture、status、heartbeat。
• 控制节流：负责置信度阈值、防抖、冷却时间和连续手势限频。
• 健康状态：报告摄像头数量、当前模式、识别 FPS、最近手势和错误。
• 明确失败：缺少 CV 依赖、摄像头打不开、无可用输入时给出可读错误。

Python 不应成为性能瓶颈：重计算在 OpenCV/MediaPipe 原生代码中完成，Python 只做编排、状态机和事件推送。事件消息通常小于 1KB，频率不超过 20Hz。

Event Protocol

本地默认地址：

ws://127.0.0.1:8765/ws/gestures

事件类型：

• gesture
• status
• heartbeat

手势语义：

• rotate_left：左挥手，地球向左旋转。
• rotate_right：右挥手，地球向右旋转。
• zoom_in：双手张开，地球放大。
• zoom_out：双手合拢，地球缩小。
• confirm：握拳或确认动作，触发当前交互确认。

最小事件字段：

{
  "type": "gesture",
  "gesture": "rotate_left",
  "phase": "discrete",
  "confidence": 0.92,
  "intensity": 0.8,
  "timestamp_ms": 1770000000000,
  "seq": 42,
  "source": "motion-agent",
  "mode": "single",
  "payload": {}
}

Earth Client Integration

Earth 前端新增 motion-control adapter：

• 连接本地 Agent WebSocket。
• 处理断线、重连、心跳和状态。
• 过滤低置信度事件。
• 将手势映射到 Earth 控制函数。
• Agent 离线时不影响普通鼠标、触摸、巡航和图层交互。

Earth 端只暴露最小动作入口：

• applyMotionRotate(direction, intensity)
• applyMotionZoom(direction, intensity)
• applyMotionConfirm()

动作捕捉不直接操作 Three.js 内部对象，也不修改图层业务模块。

SaaS Strategy

未来网页端做成 SaaS 后，默认实时手势链路仍在浏览器本地完成，不走云端 RPC。高级现场设备可选本地 Agent：

Browser SaaS page -> getUserMedia -> browser-local recognizer
Browser SaaS page -> local secure bridge -> Local Motion Capture Agent (advanced)
Cloud SaaS -> config/auth/status only

原因：

• 云端 RPC 会增加网络 RTT 和抖动。
• 上传摄像头帧有隐私和带宽风险。
• 大屏交互需要稳定体感延迟，云端只适合做配置、授权、设备状态和审计。

浏览器摄像头要求 HTTPS 或 localhost。Agent 模式在本地部署可使用 ws://127.0.0.1:8765；生产 HTTPS SaaS 若要接 Agent，需要补 wss://127.0.0.1 或等价本地安全桥接，避免浏览器混合内容限制。

Latency Budget

目标体感延迟：

• 摄像头采集：16-33ms。
• 识别：8-25ms。
• 状态机：小于 2ms。
• 本地 WebSocket：1-5ms。
• 浏览器渲染：约 16ms。

实验室目标：从动作被识别到 Earth 响应 p95 小于 50ms；摄像头到画面响应端到端小于 120ms。

Implementation Milestones

1. 保存本计划并注册到 docs/plans/README.md。
2. 新增独立 motion agent 包，提供 CLI、配置、摄像头输入抽象、事件模型和 WebSocket server。
3. 新增手势状态机，支持阈值、防抖、冷却和限频。
4. 新增 Earth motion-control provider manager，默认接浏览器摄像头 provider，可切换到 Motion Agent provider。
5. 增加 Agent 单元测试、协议测试和前端 adapter 静态验证。
6. 更新中英文用户手册和 Earth 前端开发上下文。

Debug Mode Addition

当前状态：Browser Camera provider 会在调试面板中显示本地 <video> 预览并叠加骨架；只显示骨骼 可关闭视频底图。Motion Agent provider 仍只发送 skeleton 事件，不传原始摄像头帧。

Earth 设置中增加“动捕调试模式” switch，并增加“动捕输入源”选择。开启后，Earth 会启动当前 provider 并显示独立 HUD 调试面板。Browser Camera 模式下调试面板可以显示本机浏览器视频预览；Motion Agent 模式下只画归一化骨架点和关节连线，不传原始摄像头画面。

Motion Agent 增加 skeleton 事件：

{
  "type": "skeleton",
  "camera_id": "usb:0",
  "matched_gesture": "rotate_left",
  "confidence": 0.91,
  "joints": [{ "id": "left_wrist", "x": 0.42, "y": 0.61, "confidence": 0.98 }],
  "bones": [["left_shoulder", "left_elbow"]]
}

调试颜色约定：

• 未匹配动作：红色骨架。
• 已匹配动作：绿色骨架，并显示匹配到的动作名。

权限先预留 data-gatekeeper-permission="earth.motion_debug" 标记，后续由 Gatekeeper 决定 switch 是否可见/可用。

Test Plan

• Agent 单元测试：
  • 事件模型可序列化。
  • 低置信度手势被忽略。
  • 冷却期内重复手势被忽略。
  • 冷却后新手势可再次输出。
  • 无摄像头/缺依赖时错误可读。
• Agent 协议测试：
  • gesture、status、heartbeat 字段稳定。
  • WebSocket 广播只发送语义事件。
• Earth 前端验证：
  • motion-control provider manager 能消费浏览器 provider 和 Agent provider 的 mock 消息。
  • browser provider 在 mock getUserMedia 成功时进入 active 状态。
  • browser provider 在权限拒绝、无摄像头或非安全上下文时给出可读错误。
  • skeleton 事件能触发 earth:motion-debug-frame。
  • Agent 离线时不抛异常。
  • rotate_left/right、zoom_in/out、confirm 映射到 Earth 动作函数。
• 文档验证：
  • 计划文档存在。
  • docs/plans/README.md 有入口。
  • 中英文使用说明不互相矛盾。