跳转至主要内容

导航

“导航”模块允许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 路径​

方法Chemin角色
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 } }
  }
}

Capsule — 狭长山沟​

两个端点 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《Sensation》何时使用
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 et center_drift_speed.

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

中心锚点​

position et relative 在激活时控制中心点的初始位置：

relative语义学 position
true (默认)position 是 相对于光标的偏移量 — 初始中心是 cursor + position. 使用默认值 (0, 0, 0), 气泡会精确地出现在光标位置。
falseposition 是 应用空间中的绝对点 — 它在输入端被转换为装载空间，在输出端又被转换回应用程序空间，因此经过一次往返处理后的值是相符的。

中心后续位移​

follow et speed 在气泡激活后，在每个周期中控制其行为：

followspeed行为之前的等效值
false (默认)被忽略中心保持在初始位置——固定中心。center_mode: "fixed"
true> 0中心以该速度向光标方向漂移 speed (m/s) 只要光标位于该区域内。center_mode: "auto_follow" (avec center_drift_speed)
true0.0中心点在每个周期都会对准光标——这是一种传送效果。center_mode: "track_cursor"
在 3.5 版中修改了默认值

该中心的默认行为现为 fixe (follow = false). 早期版本 会默认切换到光标（auto_follow). 设置 center.follow = true 以恢复原有的漂移行为，并调整 center.speed 以匹配旧的值 为 center_drift_speed.

当……时 follow = true 当光标越过外边界时，中心 会跟随光标移动，无论其值是多少 speed, 以便保持他周围的气泡，并 防止光标逃脱。

对碰撞的响应​

气泡会对作用在滑块上的、超过 collision_detection.force_threshold :

  • 限速区 s'élargit 暂时（直至 collision_detection.inflate_ratio fois velocity_zone_width) 以便给用户留出更大的回旋余地来绕过障碍。
  • 当……时 collision_detection.enabled vaut简体中文（大陆） 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_width0.03 m速度控制下的船体厚度
max_velocity0.5 m/s最高航行速度
velocity_ease"quadratic_in"距离到速度的过渡曲线
center.followfalse请指出中心点是否跟随光标移动
center.speed0.02 m/s漂移速度当 follow = true

参数完整列表​

冠军类型默认值说明
center.positionvec3(0, 0, 0)中心初始值——相对于光标的偏移量，当 relative = true, 当……时，该映射空间的绝对点 false
center.relativebooltruetrue : position 是相对于光标的偏移量。 false : 映射空间的绝对点，在边界处转换为组装空间
center.followboolfalsefalse : 中心点保持在初始位置。 true : 中心随光标移动
center.speedfloat0.02当……时的漂移速度（m/s） follow = true ; 0.0 每个周期将中心对准光标
shape形状{rounded_box, r=0.01, b=(0.05,0.02,0.03)}死区中的SDF形式
velocity_zone_widthfloat0.03速度控制壳体的厚度（米）
max_velocityfloat0.5最大航行速度（米/秒）
velocity_ease字符串"quadratic_in"从距离到速度的转换
reset_velocity_on_entrybooltrue当光标再次进入速度区域时，将累积速度重置为零
bump_widthfloat0.005表面触感凸起（m）
bump_stiffnessfloat200.0表面凸起处的弹簧刚度系数
spring_innerfloat0.0气泡中心的弹簧
spring_surfacefloat10.0浮出水面
spring_outerfloat15.0外部边境的恢复
wall_stiffnessfloat700.0刚性墙弹簧在超过外边界后的刚度
damping_innerfloat0.1中心摊销
damping_surfacefloat4.0面积摊销
damping_outerfloat7.0外部边境折旧
rotation_enabledboolfalse将工作区旋转应用于导航方向
scale_enabledboolfalse将工作区比例尺应用于导航速度
collision_detection.enabledbooltrue阻止朝向碰撞方向的行驶
collision_detection.force_thresholdfloat1.0发生碰撞所需的外力大小（N）
collision_detection.inflate_ratiofloat2.0碰撞时速度区域宽度的倍数（必须≥1.0）
collision_detection.exit_ratiofloat0.7滞后比——只要……就保持碰撞状态 |ext_force| < force_threshold × exit_ratio. Plage (0, 1] ; 1.0 禁用迟滞
3.5版中的隐藏冠军

JSON 3.5 规范中遗漏了两组功能，而其 实现正在为 3.6 版本进行重构：

  • 阿凡达边境的掠夺 : 字段 avatar_boundary_enabled, avatar_boundary et avatar_boundary_hysteresis.
  • 工作空间的划分 : 字段 workspace_bounded, workspace_transition_speed et 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 et spring_inner ≤ spring_surface ≤ spring_outer
  • wall_stiffness ≥ 0
  • damping_inner ≥ 0 et damping_inner ≤ damping_surface ≤ damping_outer
  • collision_detection.force_threshold > 0
  • collision_detection.inflate_ratio ≥ 1.0
  • collision_detection.exit_ratio dans (0, 1]
  • center.speed ≥ 0

Un POST ou configure.navigation 包含无效参数的请求将被拒绝，并触发一个事件 invalid-value 已发出；之前的配置仍然有效。

活动​

活动名称在以下情况下触发：
navigation-started该设备已启用导航功能
navigation-updated导航配置正在更新，而它此时已处于活动状态
navigation-stopped导航已停止（明确停用， DELETE （或注销）
invalid-value某导航配置在验证过程中被拒绝

已知限制​

  • 在 3.5 版本中，工作区边界和虚拟角色边界被隐藏：这两组功能在 JSON 架构中均未出现，因为它们正在为 3.6 版本进行重构。请参阅上文“参数参考”部分中的说明。
  • 非均匀缩放 + 旋转 : 当……时 rotation_enabled et scale_enabled 当两者均启用时，速度方向会略有偏差，因为旋转操作并未应用于缩放轴。
  • 按设备进行尺寸缩放：气泡的尺寸（半径、区域宽度）不会根据设备的物理缩放因子进行缩放；MInverse 和Inverse3 使用相同的绝对尺寸，因此它们在各自设备上的显示可能看起来有所不同。