跳至主要内容

安装与工作空间变换

有两种变换用于在应用空间中定位设备。理解 整个处理流程有助于你选择合适的变换。

坐标处理流程​

阶段作用设置方法是否会持久化？
基准重新映射坐标轴（例如 Z-up → Y-up）session.configure.basis — 参见 教程 08（HTTP 远程配置）是
安装转换设备的物理安装偏移（手臂位置、旋转、缩放）configure.mount 或 configure.preset — 参见 教程 08（HTTP 远程配置）是
工作空间变换相机/场景导航漂移commands.set_transform — 参见 教程 09（WebSocket 按周期流式传输）是（永久保存）

安装转换​

安装描述的是设备在物理空间中的实际位置——包括手臂偏移量、 朝向和缩放比例。它通常只需设置一次（或在用户更改物理设置时才设置），运行时很少更新。

预设（出厂设置）​

无需自行计算安装参数，只需选择一个命名预设：

预设原点位置手臂方向
defaults设备底座前向（手臂正面）
arm_front设备底座前向
arm_front_centered工作空间中心前向
led_front设备底座LED 一侧朝前
led_front_centered工作空间中心LED 一侧朝前
custom手动——自行设置安装参数—

预设将一次性设置安装变换、基准和工作空间原点。

直接设置安装参数​

{
  "inverse3": [{
    "device_id": "049D",
    "configure": {
      "mount": {
        "transform": {
          "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
          "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
          "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 }
        }
      }
    }
  }]
}
mount 与 preset 互斥

在同一条消息中同时发送这两者会导致歧义，服务会直接拒绝该请求。 二者择一：使用命名的 preset（由其为您设置安装参数），或使用显式的 mount 转换。

命令与快照的结构不对称

发送设置参数时，需要将转换包裹起来：{ "mount": { "transform": { … } } }。 从快照中读取安装参数时，其结构是扁平的：{ "mount": { "position": …, "rotation": …, "scale": … } }。 这是有意为之——命令使用统一的 command_data 包装器，而快照则直接序列化 core::transform。

工作空间变换​

工作空间变换是在安装变换之上叠加的运行时漂移。 其典型用途是场景导航——在设备物理位置保持不变的情况下，对应用程序的视图进行平移、旋转或缩放。

安装转换和工作区转换都是持久化的——服务会记住您最后发送的值。两者的区别在于用途和性能：

  • 安装配置的设计为“设置一次后保持不变”——它描述了物理安装情况，并针对低频更新进行了优化。
  • 工作空间变换的设计旨在以高频流式方式发送（例如在相机导航期间每帧发送一次）——其内部管道已针对该更新频率进行了优化。
{
  "inverse3": [{
    "device_id": "049D",
    "commands": {
      "set_transform": {
        "transform": {
          "position": { "x": 1.0, "y": 0.0, "z": 0.0 },
          "rotation": { "x": 0.0, "y": 0.0, "z": 0.0, "w": 1.0 },
          "scale":    { "x": 1.0, "y": 1.0, "z": 1.0 }
        }
      }
    }
  }]
}
缩放会影响输出效果——这通常正是您所期望的效果

缩放安装或工作空间会改变设备渲染的力，因为缩放会影响用于计算接触力的穿透深度。例如，2x 缩放会使穿透深度大致减半（相对于设备的行程，虚拟场景扩大了一倍），因此得到的力大约为 1x 时的一半。反之，0.5x 缩大会使力大致加倍。

这通常正是您所期望的行为：在触觉场景中缩小视图会自然地产生较弱的接触（相当于“距离更远”），而放大视图则会使接触更强。如果这不是您想要的效果——例如，您需要在用户缩放时保持刚度不变——可以通过反向缩放力增益来进行补偿。

使用导航模块实现自动漂移

如果您需要连续移动（气泡导航、速率控制漂移）， 请使用导航模块，而不是每个周期都手动进行流式发送 set_transform——它将为您处理物理计算、触觉反馈和工作空间边界。