导航

“导航”模块允许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                     │
└──────────────────────────────────────────┘

区域	光标位置	行为
死区	泡沫之中	无导航。光线衰减。您可以自由操作场景。
限速区	在表面与外边界之间	“距离→速度”曲线会将工作区沿光标方向移动。
墙面区域	越过外围边界	一个强力弹簧将光标推回原位，导航速度达到饱和。

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

---

快速入门 — 启用气泡导航

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

开始（简约版 — 默认带圆角的方框气泡）

WebSocket

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

超文本传输协定

curl -X POST "http://localhost:10001/inverse3/04C3/config/navigation?session=:0" \
     -H "Content-Type: application/json" \
     -d '{"mode": "bubble"}'

停止

WebSocket

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

超文本传输协定

curl -X DELETE "http://localhost:10001/inverse3/04C3/config/navigation?session=:0"

其他 HTTP 路由

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

---

气泡形状目录

气泡的死区由一个带符号距离函数（SDF）形状描述。 不同的形状会带来不同的导航体验——圆角矩形（默认） 可形成舒适的矩形休息区，球体适用于各向同性的漂移， 椭球体则侧重特定轴向，而胶囊形状则适用于走廊。

圆角框（默认）

默认的死区是一个平坦、高度略大于深度的体积——经过调校， 在Inverse3 MInverse 模式下都能带来舒适的手感：

{
  "shape": {
    "primitive": "rounded_box",
    "parameters": { "b": { "x": 0.05, "y": 0.02, "z": 0.03 }, "r": 0.01 }
  }
}

球体 — 各向同性漂移

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

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

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

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

胶囊 — 狭长的走廊

两个端点 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"
          }
        }
      }
    }
  ]
}

---

速度曲线

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

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

{ "velocity_ease": "quadratic_in", "max_velocity": 1.5 }

---

中心行为

气泡的中心是通过嵌套结构配置的 center 一个包含四个 字段的对象 — position, relative, follow, speed — 取代了旧的平面 布局，该布局由 center, center_enabled, center_mode和 center_drift_speed.

{
  "center": {
    "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
    "relative": true,
    "follow":   false,
    "speed":    0.02
  }
}

重心所在之处

position 和 relative 控制激活时的初始中心位置：

relative	《语义学》 position
true (默认)	position 是 相对于光标的偏移量 — 初始中心是 cursor + position. 使用默认设置 (0, 0, 0)，气泡会精确地出现在光标位置。
false	position 是 应用空间中的绝对点 — 它在进入时被转换为挂载空间，在退出时又被转换回应用程序空间，因此往返的数值保持一致。

中心随后如何行动

follow 和 speed 在气泡激活后控制每次帧的行为：

follow	speed	行为	之前的等效内容
false (默认)	被忽略	中心保持在初始化时的位置——固定中心。	center_mode: "fixed"
true	> 0	中心向光标方向偏移 speed 当光标位于其中时，按 m/s 键。	center_mode: "auto_follow" （附 center_drift_speed)
true	0.0	每次点击，中心都会瞬间对准光标——如同瞬移般。	center_mode: "track_cursor"

3.5 版本中默认设置已更改

默认的居中行为现在是 已修复 (follow = false). 早期版本 默认会向光标方向偏移 (auto_follow). 设置 center.follow = true 以恢复旧版漂移行为，并进行调整 center.speed 与旧值 匹配 center_drift_speed.

当 follow = true 当光标越过外边界时，中心 会跟随光标移动，无论 speed，以保持其周围的圆圈，并 防止光标逸出。

---

碰撞响应

当外部光标施加的力超过 collision_detection.force_threshold:

• 该速度区域暂时 膨胀 （最多 collision_detection.inflate_ratio 次 velocity_zone_width) 以便为用户提供更多绕过障碍物的操作空间。
• 当 collision_detection.enabled 是 true （默认设置），气泡中心 不会朝碰撞力的方向漂移，从而防止 用户将工作区拖拽到坚硬的墙壁上。

碰撞检测的应用 滞后 为避免阈值附近的闪烁： 一旦碰撞生效，它将保持生效状态，直到 |ext_force| 跌破 该产品 collision_detection.force_threshold × collision_detection.exit_ratio. 放下 exit_ratio 以扩大滞后带（使碰撞更具粘性）；将其设置为 1.0 禁用滞后效应并使用单一阈值。

{
  "collision_detection": {
    "enabled":         true,
    "force_threshold": 0.5,
    "inflate_ratio":   2.0,
    "exit_ratio":      0.7
  }
}

---

参数参考

最常调的

参数	默认	说明
shape	{rounded_box, r=0.01, b=(0.05,0.02,0.03)}	定义死区的SDF形状
velocity_zone_width	0.03 m	速控壳的厚度
max_velocity	0.5 m/s	最大航行速度
velocity_ease	"quadratic_in"	距离 → 速度缓动曲线
center.follow	false	中心是否跟踪光标
center.speed	0.02 m/s	漂移速率当 follow = true

完整参数列表

现场	类型	默认	说明
center.position	vec3	(0, 0, 0)	初始中心 — 光标偏移量当 relative = true, 应用程序空间中的绝对坐标点，当 false
center.relative	bool	true	true: position 是相对于光标的偏移量。 false：绝对应用空间坐标，转换为边界处的挂载空间坐标
center.follow	bool	false	false: 中心保持在初始位置。 true: 将光标居中
center.speed	float	0.02	漂移速度（米/秒）当 follow = true; 0.0 每帧自动对齐光标
shape	形状	{rounded_box, r=0.01, b=(0.05,0.02,0.03)}	死区 SDF 形状
velocity_zone_width	float	0.03	流量控制壳体的宽度（米）
max_velocity	float	0.5	最大航行速度（米/秒）
velocity_ease	字符串	"quadratic_in"	距离 → 速度缓动
reset_velocity_on_entry	bool	true	当光标再次进入速度区域时，将累积速度归零
bump_width	float	0.005	表面凸起（米）
bump_stiffness	float	200.0	表面凸起弹簧常数
spring_inner	float	0.0	气泡中心的春天
spring_surface	float	10.0	地表的春天
spring_outer	float	15.0	外缘的春天
wall_stiffness	float	700.0	硬壁弹簧越过外边界
damping_inner	float	0.1	中心处的阻尼
damping_surface	float	4.0	表面阻尼
damping_outer	float	7.0	外边界处的阻尼
rotation_enabled	bool	false	将工作空间旋转应用于导航方向
scale_enabled	bool	false	将工作区缩放比例应用于导航速度
collision_detection.enabled	bool	true	在碰撞方向上阻挡导航
collision_detection.force_threshold	float	1.0	进入碰撞所需的外部力大小（N）
collision_detection.inflate_ratio	float	2.0	碰撞期间速度区域宽度的倍数（必须≥1.0）
collision_detection.exit_ratio	float	0.7	滞后比 — 保持碰撞状态直至 |ext_force| < force_threshold × exit_ratio. 范围 (0, 1]; 1.0 禁用滞后效应

在 3.5 中隐藏的字段

3.5 版 JSON 模式中省略了两个功能组，而其 实现方案在 3.6 版中进行了调整：

• 化身边界钳位：字段 avatar_boundary_enabled, avatar_boundary和 avatar_boundary_hysteresis.
• 工作区边界：字段 workspace_bounded, workspace_transition_speed和 workspace_transition_ease.

使用默认设置时，该代码仍可编译并运行，但客户端无法通过 HTTP 或 WebSocket 读取或 写入这些字段。在 3.6 版本中，头像边界将 作为顶级 bounds 具有完整放置 变换的泡泡对象的同级对象；一旦中心抖动检测 结果确定，工作区边界将返回。

验证规则

• velocity_zone_width > 0
• 0 ≤ bump_width < velocity_zone_width
• max_velocity > 0
• bump_stiffness ≥ 0
• spring_inner ≥ 0 和 spring_inner ≤ spring_surface ≤ spring_outer
• wall_stiffness ≥ 0
• damping_inner ≥ 0 和 damping_inner ≤ damping_surface ≤ damping_outer
• collision_detection.force_threshold > 0
• collision_detection.inflate_ratio ≥ 1.0
• collision_detection.exit_ratio 在 (0, 1]
• center.speed ≥ 0

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

---

活动

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

---

已知限制

• 在 3.5 版本中，工作区边界和虚拟角色边界已被隐藏：这两个功能组在 JSON 模式中均不存在，但在 3.6 版本中已重新设计。请参阅上文“参数参考”部分中的说明。
• 非均匀缩放 + 旋转: 当两者都 rotation_enabled 和 scale_enabled 启用时，速度方向会略有偏差——坐标轴未应用旋转。
• 按设备调整大小：气泡大小（半径、区域宽度）不会根据设备的物理缩放比例进行调整MInverse Inverse3 相同的绝对尺寸，因此在不同设备上显示效果可能有所不同。