跳至主要内容
版本：3.5.x

导航

“导航”模块允许Inverse3 移动应用程序的 工作区——这有时被称为速率控制移动或“类似手柄的漂移”。 光标在物理工作区边缘不会撞上坚硬的墙壁， 而是进入一个柔性区域，在此区域内，光标与虚拟中心的距离会被映射为 一种速度，从而带动整个工作区滑动。光标推得越远， 场景滚动得越快。

其主要（也是目前唯一的）行为是气泡导航。气泡 的形状是通过SDF 基元定义的——有关该概念，请参阅 “什么是 SDF？”。

气泡导航 — 概念​

一个虚拟气泡以设备安装空间中的中心点为锚点。光标会经历三个同心区域：

┌──────────────────────────────────────────┐
│              WALL ZONE                   │  cursor beyond outer shell
│  ┌────────────────────────────────────┐  │
│  │         VELOCITY ZONE              │  │  soft shell → scene moves
│  │  ┌──────────────────────────────┐  │  │
│  │  │       DEAD ZONE (inside)     │  │  │  no scene movement
│  │  │                              │  │  │
│  │  │         ● centre             │  │  │
│  │  │                              │  │  │
│  │  └──────────────────────────────┘  │  │
│  │       bubble surface               │  │
│  └────────────────────────────────────┘  │
│       outer boundary                     │
└──────────────────────────────────────────┘
区域光标位置行为
死区泡沫之中无导航。光线衰减。您可以自由操作场景。
限速区在表面与外边界之间“距离→速度”曲线会将工作区沿光标方向移动。
墙面区域越过外围边界一个强力弹簧将光标推回原位，导航速度达到饱和。

弹簧阻尼式触觉力作用于所有三个区域——你能感受到 表面、漂移壳体以及外壁。

快速入门 — 启用气泡导航​

导航配置是持久的、一次性配置——只需发送一次，它就会保持 有效，直到您明确停止它、重启服务或关闭会话。

开始（简约版——默认大小的球形气泡）​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "bubble" }
      }
    }
  ]
}

停止​

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": { "mode": "disabled" }
      }
    }
  ]
}

其他 HTTP 路由​

方法路径目的
GET/{type}/{id}/config/navigation?session=<expr>当前导航配置 + 状态
POST/{type}/{id}/config/navigation?session=<expr>开始或更新导航
DELETE/{type}/{id}/config/navigation?session=<expr>停止导航

气泡形状目录​

气泡的禁入区由一个带符号距离函数（SDF）形状描述。 不同的形状会带来不同的导航体验——球体用于各向同性的漂移， 椭球体或立方体用于强调特定轴向，胶囊体则适用于走廊。

球体（默认）​

{
  "shape": {
    "primitive": "sphere",
    "parameters": { "r": 0.05 }
  }
}

椭球体——X/Z方向比Y方向更宽​

当横向漂移应比纵向漂移更松散时使用：

{
  "shape": {
    "primitive": "ellipsoid",
    "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
  }
}

圆角矩形框——带有圆角的矩形禁用区域​

{
  "shape": {
    "primitive": "rounded_box",
    "parameters": { "b": { "x": 0.04, "y": 0.02, "z": 0.04 }, "r": 0.008 }
  }
}

胶囊 — 狭长的走廊​

两个端点 a/b 加上半径 r:

{
  "shape": {
    "primitive": "capsule",
    "parameters": {
      "a": { "x": 0.0, "y": -0.03, "z": 0.0 },
      "b": { "x": 0.0, "y": 0.03, "z": 0.0 },
      "r": 0.04
    }
  }
}

包含自定义尺寸和动态效果的完整示例：

{
  "inverse3": [
    {
      "device_id": "04C3",
      "configure": {
        "navigation": {
          "mode": "bubble",
          "bubble": {
            "shape": {
              "primitive": "ellipsoid",
              "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } }
            },
            "velocity_zone_width": 0.025,
            "max_velocity": 1.0,
            "velocity_ease": "quadratic_in",
            "workspace_bounded": true
          }
        }
      }
    }
  ]
}

速度曲线​

速度-区域距离会通过缓动曲线进行映射，然后 转换为工作区速度。请选择与您期望的 场景加速方式相匹配的缓动曲线，以反映用户向壳体内部深入时的加速效果。

velocity_ease感受何时使用
linear恒定斜坡可预见的、不错的默认选项
quadratic_in开局缓慢，后劲十足近表面处精准，长行程快速
cubic_in开局非常缓慢非常精准，长行程渐进式提升
sine_out起步平稳迅速，接近外圈时速度趋于平稳响应式，大写字母柔和
quadratic_out起步迅猛，长途舒适敏捷灵动，舒适从容
{ "velocity_ease": "quadratic_in", "max_velocity": 1.5 }

中心模式​

气泡的中心可以跟随光标移动、对齐光标，或固定在坐标系中。

center_mode行为用例
auto_follow (默认)缓缓漂向光标处 center_drift_speed 当光标位于气泡内时通用导航——在两次点击之间，中心会“回弹”至光标下方
fixed中心位置不会自动移动以特定参考点为基准的锚定导航
track_cursor每次跳动时，中心点都会对准光标传送式移动——光标始终位于气泡中心
{ "center_mode": "fixed" }

在所有模式下：如果光标越过外边界，中心会跟踪 光标，以保持气泡包围光标，并防止光标逸出。

工作区边界​

大多数设备的物理覆盖范围有限。当 workspace_bounded 一旦设置完成， 气泡中心将始终位于设备的物理工作区内，因此 由此产生的导航操作不会将光标移出其可访问范围。

{ "workspace_bounded": true }

如果初始中心点位于工作区之外，该模块会随时间推移将其平滑地移回 工作区内（workspace_transition_speed / workspace_transition_ease) 而非突然跳转——避免启动时产生触觉上的突兀感。

化身边界​

当 avatar_boundary_enabled 一旦设置，最终 角色在世界中的位置 (工作区 + 光标) 被限制在任意 SDF 形状内。这有助于 将用户限制在房间、走廊、车辆驾驶舱等区域内，而无需 编写针对每个轴的限制脚本。

{
  "avatar_boundary_enabled": true,
  "avatar_boundary": {
    "primitive": "box",
    "parameters": { "b": { "x": 5.0, "y": 3.0, "z": 5.0 } }
  }
}

"(《世界人权宣言》) avatar_boundary 该形状支持与气泡形状相同的基元 (sphere, ellipsoid, rounded_box, capsule, box, ...)。

碰撞响应​

当外部光标施加的力超过 collision_threshold:

  • 该速度区域暂时 膨胀 （最多 collision_inflate_scale 次 velocity_zone_width) 以便用户有更大的空间绕过 障碍物。
  • 使用 stop_at_collision, 气泡中心不会朝 碰撞力的方向偏移，从而防止用户将 工作区拖拽到坚硬的墙壁上。
{ "stop_at_collision": true, "collision_threshold": 0.5, "collision_inflate_scale": 2.0 }

参数参考​

最常调的​

参数默认说明
shape{sphere, r=0.05}定义死区的SDF形状
velocity_zone_width0.03 m速控壳的厚度
max_velocity1.0 m/s最大航行速度
velocity_ease"linear"距离 → 速度缓动曲线
center_mode"auto_follow"该中心如何追踪光标
workspace_boundedfalse将夹具中心对准设备的物理工作空间

完整参数列表​

现场类型默认说明
centervec3(0,0,0)坐标系中的初始气泡中心
shape形状{sphere, r=0.05}死区 SDF 形状
velocity_zone_widthfloat0.03流量控制壳体的宽度（米）
max_velocityfloat1.0最大航行速度（米/秒）
velocity_ease字符串"linear"距离→速度缓动
reset_velocity_on_entrybooltrue当光标再次进入速度区域时，将累积速度归零
bump_widthfloat0.003表面凸起（米）
bump_stiffnessfloat500.0表面凸起弹簧常数
spring_innerfloat4.0气泡中心的春天
spring_surfacefloat7.0地表的春天
spring_outerfloat12.0外缘的春天
wall_stiffnessfloat700.0硬壁弹簧越过外边界
damping_innerfloat0.2中心处的阻尼
damping_surfacefloat0.7表面阻尼
damping_outerfloat5.0外边界处的阻尼
rotation_enabledboolfalse将工作空间旋转应用于导航方向
scale_enabledboolfalse将工作区缩放比例应用于导航速度
center_modeenum"auto_follow""auto_follow" / "fixed" / "track_cursor"
center_drift_speedfloat0.03漂移速度为 auto_follow 风速 (米/秒)
workspace_boundedboolfalse将气泡中心固定在设备工作区
workspace_transition_speedfloat1.2初始夹紧过渡速度
workspace_transition_ease字符串"quadratic_in_out"初始夹紧过渡的缓和
stop_at_collisionboolfalse在碰撞方向上阻挡导航
collision_thresholdfloat0.001检测碰撞的外力阈值（N）
collision_inflate_scalefloat2.0碰撞期间速度区宽度的倍数
avatar_boundary_enabledboolfalse启用角色边界限制
avatar_boundary形状{sphere, r=0.1}用于头像位置约束的SDF形状

验证规则​

  • velocity_zone_width > 0
  • 0 ≤ bump_width < velocity_zone_width
  • max_velocity > 0
  • spring_inner ≤ spring_surface ≤ spring_outer
  • damping_inner ≤ damping_surface ≤ damping_outer
  • collision_threshold > 0, collision_inflate_scale ≥ 1.0
  • 所有速度值均为非负数

A POST 或 configure.navigation 包含无效参数的请求将被拒绝，并返回一个 invalid-value 事件被触发；之前的配置仍保持有效。

活动​

活动名称何时被解雇
navigation-started设备上已启用导航功能
navigation-updated导航配置在已激活状态下被更新
navigation-stopped导航已停止（显式禁用， DELETE（或会话结束）
invalid-value导航配置在验证过程中被拒绝

已知限制​

  • 非均匀缩放 + 旋转: 当两者都 rotation_enabled 和 scale_enabled 启用时，速度方向会略有偏差——坐标轴未应用旋转。
  • 工作区边界过渡：平滑的回弹过渡仅在初始化时运行。如果在正常使用过程中气泡中心漂移到了工作区之外，回弹会立即发生，且不带缓动效果。
  • 按设备调整大小：气泡大小（半径、区域宽度）不会根据设备的物理缩放比例进行调整Minverse Inverse3 相同的绝对尺寸，因此在不同设备上显示效果可能有所不同。