usd-pipeline

USD 资产管线

用途

发现资产、测量边界框和着色器、替换占位对象、修正偏移，并在渲染前验证无头着色器兼容性。

前置条件

• 对于独立 USD 检查/创作：需要完成 source/libraries 构建， 或安装匹配的基础发行版。
• 对于实时 Kit 场景、资产服务、MDL 或渲染：需要构建好的 Isaac Sim 和 isaac-sim-orchestrator 环境；GPU 要求因执行路径而异。

限制

• 除非某一节另有说明，否则面向 Isaac Sim 6 / Kit 110。
• 不能替代 NVIDIA 官方文档中针对不受支持边缘情况的说明。

故障排除

错误 / 症状	原因	解决方案
帧画面全黑或为空	缺少灯光或非 RTX 渲染模式	添加穹顶灯/主光；确认 RTX / PathTracing 设置
加载场景或首次渲染时卡住	MDL 编译或场景过大	按照 isaac-sim-troubleshooting 中的隔离步骤操作

独立 USD 与实时 Kit 场景

对于受支持的独立 OpenUSD 场景、对象、图元和实用工具操作，请使用 source/libraries/isaacsim/foundation/ 中的 isaacsim.foundation.usd.openusd 或独立的 isaacsim.foundation.usd.ovstage 后端，以及 isaacsim.foundation.objects、 isaacsim.foundation.prims 和 isaacsim.foundation.utils。

仅在 Kit 路径中使用 omni.usd、Kit 资产服务、MDL、视口/渲染、命令和 实时场景交互。

可用脚本

脚本	用途	参数
scripts/articulation_builder.py	用于构建带物理关节的 USD articulation 树的辅助工具	参见脚本 --help
scripts/measure_asset.py	测量 USD 资产：边界框、着色器类型和图元数量	参见脚本 --help
scripts/place_assets.py	按块位置放置 USD 资产，并修正边界框中心偏移	参见脚本 --help

运行脚本

在提供技能执行辅助工具的 Agent 运行时中，使用 run_script() 调用辅助工具：

run_script("scripts/articulation_builder.py", args=["--help"])

从构建好的 Isaac Sim 目录中，在 _build/*/release 下使用 ./python.sh（Linux）或 python.bat（Windows）运行同一文件；如果 shell 辅助工具不需要模拟器，也可以直接执行。

使用场景

• 对文件夹树中的 USD 资产编目（尺寸、着色器、图元数量）。
• 用真实资产替换占位几何体（立方体/球体/边界框）。
• 使用模块化资产库构建布景场景。
• 验证无头渲染兼容性（MDL 与 UsdPreviewSurface）。
• 立方体原型到真实资产的替换工作流。

核心概念

从占位对象到资产的管线

真实世界的 USD 场景构建遵循以下模式：

1. 用立方体制作原型 — 使用彩色 UsdGeom.Cube 网格布局空间区域
2. 为资产编目 — 测量每个候选 USD 资产（边界框、着色器、图元数量）
3. 将块映射到资产 — 将占位对象类型与尺寸合适的真实资产匹配
4. 修正偏移后放置 — 在块位置引用资产，并修正资产边界框中心偏移
5. 验证渲染效果 — 由视觉模型和领域专家进行评分
6. 迭代 — 修正超出范围、侵入走廊和缩放不匹配问题

为什么边界框偏移修正很重要

大多数 USD 资产的原点都不在中心。例如，某个货架资产的边界框中心可能位于 (46.7, 104.6, 4.5)；如果不修正就将它放在目标位置 (112.0, 20.0, 0.0)，它会落在目标位置以东 46.7 m、以北 104.6 m 处。

公式：

translate_x = target_x - asset_bbox_center_x
translate_y = target_y - asset_bbox_center_y
translate_z = -asset_bbox_min_z  (puts asset base on ground plane)

阶段 1：资产发现与测量

脚本模式（Kit Python — 无需渲染器）

measure_asset(path) — 打开 USD 文件，计算边界框，检测 UsdPreviewSurface 着色器，并统计图元数量。返回包含 width/depth/height/center/mpu/prims/dual_shader/shader_tag 的字典。catalog_assets(root_dir, extensions) — 递归查找并测量所有 USD 资产。

参见 scripts/measure_asset.py。

关键经验

• 使用 Usd.Stage.Open()，而非 Sdf.Layer.FindOrOpen() — Sdf 无法读取二进制 .usd crate 文件时不会报错，并会返回默认 mpu=1.0
• 始终检查 mpu — 有些资产使用 cm（mpu=0.01），有些使用米（mpu=1.0）。请据此缩放测量值。
• 无效的 bbox（min > 1e30） 表示资产未能组合 — 通常是缺少引用或负载
• Kit Python（kit/python/bin/python3）测量速度最快 — 无需启动渲染器
• 在 Kit 运行时中计算 bbox（SimulationApp）时，可定义一个临时 prim 并添加引用，更新几帧后再计算 bbox — 对复杂组合更可靠

第 2 阶段：着色器兼容性检查

无头 arm64 上的 MDL 问题

着色器类型	无头 SimulationApp	Isaac Sim GUI	OVRTX
仅 UsdPreviewSurface	可渲染	可渲染	可渲染
MDL + UsdPreviewSurface（双着色器）	回退到 Preview	使用 MDL	使用 MDL
仅 MDL（sourceAsset）	黑屏	可渲染	可渲染
无材质	灰色／不可见	灰色	灰色

规则： 对于无头渲染工作流，只能使用带有 UsdPreviewSurface 回退的资产（双着色器）或原生 UsdPreviewSurface。

Xvfb 的发现

在 DISPLAY=:99（Xvfb 虚拟帧缓冲区）下运行 Isaac Sim，而不是使用被锁定的真实显示器 :0，可以让某些 MDL 资产渲染出非黑画面。此方法并非完全可靠，但值得一试：

# Start Xvfb
Xvfb :99 -screen 0 1920x1080x24 &>/dev/null &

# Run with virtual display
DISPLAY=:99 isaac-sim.sh --exec script.py

识别双着色器资产

在 USD 中查找以下模式：

• 任意 Shader prim 上的 info:id = "UsdPreviewSurface" → 适用于无头环境
• 存在 info:mdl:sourceAsset，但没有同级 UsdPreviewSurface → 仅 MDL，不适用于无头环境
• 经 Lightspeed 处理的资产通常仅包含 MDL
• “Collected” Dematic 资产通常包含双着色器

第 3 阶段：占位资产映射

策略

1. 按名称前缀对占位立方体分组（例如，CvL001→CvL、BRk045→BRk）
2. 对每个前缀，按以下条件查找最合适的资产：
   • 功能相似（货架→货架资产，输送机→输送机资产）
   • 尺寸兼容（资产不应远超占位区域）
   • 双着色器兼容性（无头渲染要求）
3. 在开始构建前记录映射表

映射表格式

| Block Prefix | Count | Placeholder Size | Asset | Asset Size | Shader | Notes |
|---|---|---|---|---|---|---|
| BRk | 352 | 3.5×1.2×5.0m | ASRS_Racks_Center | 2.36×2.82×8.29m | dual | Per-block, no scaling |
| CvL | 190 | 2.0×4.0×1.5m | Conveyor_09 | 0.94×6.72×1.66m | dual | Roller conveyor |

尺寸原则

使用资产的自然尺寸，而不是缩放到立方体大小。 将资产缩放到与立方体尺寸匹配，会破坏视觉密度和真实感。将资产放在区块的 XY 位置，并使用资产的自然尺寸。

例外：如果资产远大于其所在区域（例如，在 20m 区域内放置 83m 的装配件），则改用较小的模块化部件。

第 4 阶段：放置脚本模式

SimulationApp 运行时放置

get_asset_bbox(stage, asset_path, app) — 临时引用资产，以获取准确的 bbox 中心。collect_blocks(stage) — 按名称前缀对可见的 Cube prim 进行分组，并获取其世界坐标位置。place_assets(stage, blocks, asset_map, asset_bboxes, module_name) — 在区块位置放置资产，并校正 bbox 中心偏移；隐藏原始立方体。

参见 scripts/place_assets.py。

层级约定

/World/
  Module1/          # Racks
    VNA/
      VNA001        # Individual asset reference
      VNA002
    BRk/
      BRk001
  Module2/          # Conveyors, sorters
    CvL/
      CvL001
    Sort/
      Sort001
  Module3/          # Safety, humans

第 5 阶段：动画与关节结构

动画烘焙

使用 spatial-reasoning 技能中的 bake_waypoints()，让机器人、人物或物体沿路径移动。

bake_waypoints(xform_op, waypoints, speed_mps, fps, mpu) — 沿一系列 (x,y,z) 路径点为 XformOp 设置关键帧。定义于 spatial-reasoning 技能中的 ../spatial-reasoning/scripts/spatial.py。

关节结构构建器

用于机器人 USD：

build_forklift_articulation(output_path) — 创建底盘、固定关节连接的门架以及棱柱升降关节；包含 _create_box、_create_fixed_joint、_create_prismatic_joint 辅助函数。

参见 scripts/articulation_builder.py。

UV 映射与材质

对于纹理：

• 全局资产使用 sphereUV 映射
• 平面（地板、墙面）使用 linear
• 始终使用 UsdPreviewSurface 作为回退方案
• 无头模式下切勿使用仅支持 MDL 的材质

阶段 6：验证

占位流程颜色键

颜色	值	表示
红色	(1.0, 0.2, 0.2)	验证失败
黄色	(1.0, 1.0, 0.2)	警告（接近重叠）
绿色	(0.2, 1.0, 0.2)	有效，可替换为资产

格式验证清单

• 所有资产的扩展名均为 .usd、.usda 或 .usdc
• 所有路径均使用正斜杠 /
• 不包含 .. 相对路径
• 所有资产的 mpu = 1.0（脚本会验证比例）
• 引用中不使用 ./ 或 ../ 语法
• 拓扑：如果为空，伪影不得嵌套在 Xform 下

资产建议（基于扫描结果）

首先，使用 catalog_assets() 扫描所有资产，然后：

• 筛选：dual_shader 为 True
• 排序：prims < 5000
• 指定：与占位立方体的包围盒尺寸在 20% 容差范围内匹配
• 排除：所有 blockpallet_a*、palletstack_a*——这些不是真实资产

经验教训

1. 切勿缩放资产以匹配立方体尺寸——这会破坏视觉密度。请使用自然尺寸。
2. 大型装配体（>20m）很少能适配成组的方块——请改用更小的模块化部件。
3. 务必校正包围盒中心偏移——大多数资产的中心并不在原点。
4. **经 Lightspeed 处理的资产 = 仅支持 MDL = 在无头 arm64 上呈黑色。**只能使用“Collected”双着色器变体。
5. Tote_01、Pallet_Pile、AMR_Table 仅支持 MDL——它们可以放置，但渲染结果为黑色。请使用 Scissor_Lift 或 Electrical_Panel 作为功能性占位对象。
6. 启动新的 Isaac Sim 之前，务必终止所有 kit 进程——僵尸进程会导致冷启动耗时 90–170s。
7. 重启之间清理 /dev/shm/carb-*，以防止 SIGKILL。
8. 无头模式下的 SimulationApp 需要显式添加 DomeLight 和 DistantLight——GUI 会自动添加视口灯光，无头模式则不会。
9. **Xvfb（DISPLAY=:99）**可以改善 MDL 渲染效果，相比被锁定的桌面（:0），但并非通用解决方案。