前置条件

请把 FastSim 和 Isaac Lab provider 安装到同一个环境。本 Run 以可见模式启动 Isaac Lab 3.0 / Isaac Sim 6.0。

逐项理解配置

yaml
schema: fastsim/2               # FastSim vNext Run 配置规范。
name: demo-planning-geometry    # 稳定的 Run 名称。
backend: isaaclab               # 选择楔块的 Isaac Lab USD 变体。

runtime:
  launch_profile: visible       # 打开仿真器原生窗口。
  physics_hz: 60                # 物理积分频率。
  control_hz: 60                # 控制帧接收频率。
  seed: 43                      # 可复现的 reset 随机种子。

scenario:
  scene:
    objects:
      wedge:                    # 别名；规范实体 ID 为 objects.wedge。
        use: object://fastsim/demo-mesh-wedge
        pose:
          xyz_m: [0.0, 0.0, 0.2] # 世界坐标系根位置，单位米。
          quat_xyzw: [0.0, 0.0, 0.0, 1.0]

组件指向 ../../_shared/assets/mesh_wedge.usda。其碰撞体是使用三角网格近似的 UsdGeom.Mesh，所以 provider 必须发布资源型 Mesh，而不是内联 box 或 sphere。

逐行理解 Python

  1. Docstring 明确目标：解析资源型碰撞几何。
  2. asyncio 运行应用 API，hashlib 验证内容，math 拒绝非有限变换；Path 找到相邻 Run，fastsim 是公共 facade。
  3. RUN_FILE 和 VISIBLE_HOLD_SECONDS 分别定义输入和短暂的可视停留时间。
  4. main() 定义异步流程。
  5. fastsim.app(..., planning_reads=True) 必不可少。规划发布默认关闭，因此不用规划 数据的应用不会承担持续开销。
  6. async with 持有应用及其所有 provider 资源。
  7. start() 构建真实 Isaac Lab 世界；pause() 固定一致的几何变换边界。
  8. geometry.capabilities() 声明支持的 representation、存储模式、大小上限和 delta 能力；调用方应查询能力，而不是自行假设。
  9. geometry.catalog() 返回不包含后端路径的结构化碰撞事实和不可变资源身份，不会 把 Mesh buffer 复制进 WorldState。
  10. geometry.transforms() 在独立的已提交快照中返回当前轻量世界变换。
  11. 选择逻辑要求 objects.wedge 恰好有一个资源型几何，验证其为 triangle_mesh，并确认 provider 声明了该 representation；不匹配时返回非零。
  12. geometry.resolve(id, representation) 针对指定 Catalog 条目打开 provider 持有的 只读租约。
  13. async with resource 保证及时释放租约，失败时也会释放。
  14. resource.descriptor() 返回可移植元数据，并且必须声明正数字节数；它不会返回 文件路径或原生 handle。
  15. resource.read(0, descriptor.byte_size) 执行一次有界读取。大型资源应使用 descriptor.read_span(...) 分块向后推进。
  16. 字节数检查和 hashlib.sha256(payload) 独立验证内容完整性；不一致时直接失败， 不把损坏几何交给规划器。
  17. Transform 查询用 Geometry ID 找到当前轻量 world_pose，并拒绝非有限位置。
  18. 打印内容包括 Catalog 大小、provider representation、资源身份、字节数/摘要和 世界位置。
  19. 最后的等待让暂停后的楔块在窗口中保留三秒。
  20. asyncio.run(main()) 在直接运行文件时执行程序。

验收门禁

  • 楔块必须恰好有一个资源型 triangle_mesh 条目，且 provider capability 必须包含 该 representation。
  • Descriptor 大小必须为正；读取字节必须同时匹配精确长度和 SHA-256；世界位置 必须有限。
  • 2026-08-25 的可见 Isaac Lab 真机验收解析了 168 字节，摘要为 7b05a6d7d6dc6542cfed8dda2f8011120be4f406948f96d0862e016be2972d7d， 世界位置为 (0, 0, 0.200000003) m，退出码为 0。

运行

从本案例目录运行：

bash
cd demo/fundamentals/10_planning_geometry
fastsim config validate run.yaml --json
python main.py

预期输出包含 Mesh representation（triangle_mesh）、非零资源大小、64 字符 SHA-256 摘要以及楔块的有限世界位置。摘要验证必须正常完成，不能抛出 RuntimeError。

验证等级

真实可见 Isaac 已通过。 真机运行解析并独立校验了 168 字节 triangle mesh， 程序正常退出，并且没有遗留 Isaac worker 进程。

规划器应该缓存什么

按照 Catalog 条目的解析身份缓存不可变 Mesh 字节；世界运动时只刷新轻量 Transform 快照。不要在每个控制 tick 重复请求不变 Mesh，也不要把 Mesh buffer 放进普通 Observation。

常见错误

  • SERVICE_ACCESS_DENIED：保留 planning_reads=True。
  • 没有资源型条目：碰撞体被降成了内联 primitive，或资产没有发布受支持的 Mesh 碰撞 representation。
  • RESOURCE_LEASE_REVOKED：reset 或 close 使旧租约失效；应基于新 generation 的 Catalog 重新解析。
  • PLANNING_SCENE_INCOMPLETE：当前 provider 无法为某个已选择资产发布完整碰撞场景。 禁止对不完整世界静默规划。