urdf-mjcf-to-usd-conversion

URDF / MJCF 到 USD 的转换

用途

使用现代导入器 API、可实例化网格和驱动配置，将 URDF 和 MJCF 机器人描述导入 USD，用于强化学习或远程操控。

前提条件

• 对于导入器命令和 UI：已构建 Isaac Sim，并配置好 isaac-sim-orchestrator 环境。
• 对于迁移后的转换器／架构 API：已完成 source/libraries 构建，或安装了匹配的 wheel；渲染需要 GPU，但单纯转换不需要。

限制

• 适用于 Isaac Sim 6 / Kit 110，除非某个章节另有说明。
• 对于不受支持的边缘情况，请参阅 NVIDIA 官方文档。

故障排除

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

导入器、库和 Kit 扩展的职责

URDF/MJCF 命令分发、导入器 UI、扩展设置和 Kit 生命周期仍由扩展负责。迁移后的 Asset Transformer 实现和机器人架构包由 source/libraries/isaacsim/asset/transformer 和 source/libraries/isaacsim_usd_schemas/ 管理；其 Kit 扩展负责暂存已构建的 wheel 和 SDK，不会重复实现相关功能。

对于现有的 PhysX 编写的 USD（非 URDF/MJCF），请改用 physx-to-newton-conversion。

两种转换路径和一种导出路径。

路径	适用场景	驱动程序
1. 完整 Isaac Sim 导入（CLI）	RL／Lab 资产、脚本化批处理	通过 urdf_import.py／mjcf_import.py 使用 isaacsim.asset.importer.urdf／.mjcf
2. Isaac Lab 转换脚本	原生 Isaac Lab 的 config.yaml 工作流	$ISAAC_LAB_DIR/scripts/tools/convert_urdf.py／convert_mjcf.py
导出	USD -> URDF 往返转换	通过 urdf_export.py 使用 isaacsim.asset.exporter.urdf

可用脚本

脚本	用途	参数
scripts/urdf_importer_ros.py	通过 URDFImporter 从运行中的 ROS 2 robot_state_publisher 导入 URDF	参见脚本 --help

运行脚本

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

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

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

XACRO 输入

URDFImporter 核心不解析 XACRO。支持以下两种方式：

推荐 — 直接从运行中的 ROS 2 节点导入

isaacsim.ros2.urdf 添加了专用导入路径，可通过标准 GetParameters 服务查询任意节点（通常为 robot_state_publisher）上的 robot_description 参数，解析 package:// URL，将 URDF 写入临时文件，然后交给 URDFImporter。节点负责展开 XACRO，因此也适用于仅通过启动文件分发、从不提供静态 URDF 的情况。

UI：File -> Import from ROS2 URDF Node（打开导入窗口，提供与标准 URDF 导入器相同的碰撞体 / 机器人类型 / 网格选项）。

Python（优先于已弃用的 URDFImportFromROS2Node Kit 命令）：

import_urdf_from_ros(usd_out_path, merge_fixed_joints, fix_base, robot_type) — 订阅 robot_state_publisher，解析 package:// URL，并在收到描述后导入 URDF。

参见 scripts/urdf_importer_ros.py。

需要 isaacsim.ros2.urdf 扩展（依赖 ROS 2 运行时所需的 isaacsim.ros2.bridge）、一个可访问且发布 robot_description 的节点，以及从已加载机器人工作区环境的终端启动 Isaac Sim。已加载的工作区必须包含机器人描述包，以及 package:// 网格 / 资源 URL 引用的所有包；随附的 ROS 2 运行时不提供特定于机器人的包。读取器以异步方式运行 — GetParameters 服务回复后会触发回调。

备用方案 — 离线 xacro CLI

在没有活动 ROS 图时使用。仅需 xacro 包（pip install xacro 或 apt install ros-$ROS_DISTRO-xacro）：

xacro robot.xacro > robot.urdf
xacro robot.xacro arm_id:=fr3 hand:=true > robot.urdf

# Inside a sourced ROS 2 workspace so package:// / $(find-pkg-share) work:
source /opt/ros/$ROS_DISTRO/setup.bash
source install/setup.bash
xacro $(ros2 pkg prefix --share my_robot_description)/urdf/robot.xacro \
  > robot.urdf

将生成的 .urdf 传递给路径 1 或路径 2。

路径 1 — Isaac Sim 导入器（RL/Lab 推荐）

现代公共 API：isaacsim.asset.importer.urdf.URDFImporter + URDFImporterConfig（数据类），以及对应的 isaacsim.asset.importer.mjcf 组合。导入后的 isaacsim.asset.transformer 默认运行，并重组 USD 输出（收集依赖项、运行已注册的物理转换、材质路由等规则）。

from isaacsim.asset.importer.urdf import URDFImporter, URDFImporterConfig

config = URDFImporterConfig(
    urdf_path="/path/robot.urdf",
    usd_path="/path/out",
    merge_fixed_joints=True,
    fix_base=False,
    collision_from_visuals=True,
    collision_type="Convex Decomposition",
    joint_drive_type="force",
    joint_target_type="position",
    override_joint_stiffness=800.0,
    override_joint_damping=40.0,
    robot_type="Manipulator",          # robot-schema token
    run_asset_transformer=True,         # default True; applies transformer profile
    run_multi_physics_conversion=True,  # URDF -> PhysX/MuJoCo physics
)
output_usd = URDFImporter(config).import_urdf()

URDFImporterConfig 字段（默认值）

字段	默认值	说明
urdf_path, usd_path	None	输入 / 输出
merge_fixed_joints	False	合并固定关节
merge_mesh	False	按连杆合并网格
debug_mode	False	额外日志 + 中间文件
collision_from_visuals	False	根据视觉几何体生成碰撞几何体
collision_type	"Convex Hull"	Convex Hull / Convex Decomposition / Bounding Sphere / Bounding Cube
allow_self_collision	False	训练时保持关闭
ros_package_paths	[]	解析 package:// URL
robot_type	"Default"	机器人架构标记；见下文
fix_base	False	添加 world -> root 固定关节；迁移 ArticulationRootAPI
link_density	None	URDF 未提供质量时使用的 kg/m^3 后备值
joint_drive_type	None	force / acceleration；或按关节设置的 {regex: value}
joint_target_type	None	none / position / velocity；或按关节设置的字典
override_joint_stiffness	None	Nm/rad（转动关节）或 N/m（移动关节）；或按关节设置的字典
override_joint_damping	None	Nms/rad / Ns/m；或按关节设置的字典
run_asset_transformer	True	导入后运行转换器配置
run_multi_physics_conversion	True	URDF -> PhysX 关节属性转换

CLI（Isaac Sim）

source/standalone_examples/api/isaacsim.asset.importer.urdf/urdf_import.py 会自动启用 omni.scene.optimizer.core 和 isaacsim.robot.schema，然后应用配置。

"$ISAAC_SIM_DIR/python.sh" \
  "$ISAAC_SIM_DIR/source/standalone_examples/api/isaacsim.asset.importer.urdf/urdf_import.py" \
  --urdf      /path/robot.urdf \
  --usd-path  /path/out \
  --merge-fixed-joints \
  --fix-base \
  --joint-drive-type force \
  --joint-target-type position \
  --collision-from-visuals --collision-type "Convex Decomposition" \
  --robot-type Manipulator \
  --ros-package my_pkg:/abs/path/to/my_pkg
# --no-run-asset-transformer to skip the transformer profile.

--robot-type 的可选值来自 usd.schema.isaac.robot_schema.get_allowed_tokens(Attributes.ROBOT_TYPE)：Default、End Effector、Manipulator、Humanoid、Wheeled、Holonomic、Quadruped、Mobile Manipulators、Aerial。

MJCF 导入（并行 API）

from isaacsim.asset.importer.mjcf import MJCFImporter, MJCFImporterConfig

config = MJCFImporterConfig(
    mjcf_path="/path/robot.xml",
    usd_path="/path/out",
    import_scene=True,            # include MJCF scene settings
    merge_mesh=True,
    robot_type="Quadruped",
    override_gain_type="fixed",   # MuJoCo actuator gain type
    override_bias_type="affine",  # MuJoCo actuator bias type
    override_gain_prm=[kp, 0, 0, 0, 0, 0, 0, 0, 0, 0],          # position control
    override_bias_prm=[0, -kp, -kd, 0, 0, 0, 0, 0, 0, 0],       # position control
)
output_usd = MJCFImporter(config).import_mjcf()

CLI：source/standalone_examples/api/isaacsim.asset.importer.mjcf/mjcf_import.py（与 URDF 一致：--mjcf、--usd-path、--import-scene、--robot-type、--override-gain-type、--override-bias-type 等）。

旧版 MJCF 命令 MJCFCreateAsset / MJCFCreateImportConfig 已弃用；请直接使用 MJCFImporter。

**迁移：**关于更广泛的 omni.importer.mjcf / omni.importer.urdf → isaacsim.asset.importer.* 重命名映射，请参阅扩展重命名。

Asset Transformer（run_asset_transformer=True 的运行内容）

isaacsim.asset.transformer 会执行有序的 USD 规则流水线。默认的导入后规则包括 UrdfToMjcPhysxConversionRule / MjcToPhysxConversionRule 和材质路由。要在现有 USD 上手动运行：

from isaacsim.asset.transformer import AssetTransformerManager, RuleProfile

manager = AssetTransformerManager()
profile = RuleProfile.from_json("path/to/profile.json")
report  = manager.run("input.usd", profile, package_root="/tmp/out")

CLI：source/standalone_examples/api/isaacsim.asset.transformer/run_asset_transformer.py（--input、--profile、--output）。

导入期间应用的机器人 Schema

导入器会应用现代的 usd.schema.isaac.robot_schema：

• 在机器人根 prim 上应用 IsaacRobotAPI（存储 robot_type、有序的连杆/关节关系以及命名位姿容器）。
• 在刚性连杆上应用 IsaacLinkAPI。
• 在关节上应用 IsaacJointAPI。
• 在站点上应用 IsaacSiteAPI（取代已弃用的 IsaacReferencePointAPI）。
• 使用 IsaacNamedPose prim 表示命名位姿；通过 isaacsim.robot.poser 模块管理（参见 manipulation-ik）。

导入后进行验证：

from pxr import Usd
from usd.schema.isaac.robot_schema import Classes, get_allowed_tokens, Attributes

stage = Usd.Stage.Open("/path/out/robot.usd")
robot = next(p for p in stage.Traverse() if p.HasAPI(Classes.ROBOT_API))
print(robot.GetAttribute(Attributes.ROBOT_TYPE).Get())

路径 2 — Isaac Lab convert_urdf.py / convert_mjcf.py（config.yaml）

对于原生 Isaac Lab 工作流，每个机器人在 assets/isaaclab/Robots/<Robot>/ 下都有一个 config.yaml：

asset_path: /path/to/robot.urdf      # pre-expand XACRO first
usd_file_name: robot_name.usd

force_usd_conversion: true
make_instanceable: true              # critical for parallel envs
import_inertia_tensor: true          # use URDF inertia
merge_fixed_joints: true
self_collision: false

fix_base: false
default_drive_type: none             # "none" | "position" | "velocity"
default_drive_stiffness: 0.0
default_drive_damping: 0.0

link_density: 0.0
convex_decompose_mesh: false

运行：

cd "$ISAAC_LAB_DIR"
./isaaclab.sh -p scripts/tools/convert_urdf.py \
  --config /path/MyRobot/config.yaml --output /path/MyRobot/
# MJCF equivalent:
./isaaclab.sh -p scripts/tools/convert_mjcf.py \
  --config /path/MyRobot/config.yaml --output /path/MyRobot/

Drive 预设

用例	Drive 配置
RL 训练（Agent 控制扭矩）	default_drive_type: none、刚度 0.0、阻尼 0.0
位置控制的遥操作	default_drive_type: position、刚度 800.0、阻尼 40.0
装配/操控物体（AutoMate）	default_drive_type: force、joint_drive.target_type: position、gains: {stiffness: 100, damping: 1}、collider_type: convex_hull

make_instanceable: true

GPU 网格实例化。若不启用，4096 个环境 × 完整网格会导致 VRAM 耗尽。启用后，并行环境会在 VRAM 中共享同一个网格。RL 始终应启用。

按机器人类型设置 fix_base

机器人类型	fix_base
机械臂（桌面/墙面安装）	true
移动机器人（轮式）	false
人形/腿式机器人	false
空中机器人（无人机）	false

URDF 导出（USD → URDF 往返转换）

isaacsim.asset.exporter.urdf 是反向转换路径；适用于将已导入的 USD 资产共享回 ROS 或其他 URDF 使用方。

from pxr import Usd
from isaacsim.asset.exporter.urdf import UsdToUrdfConverter

stage = Usd.Stage.Open("/path/robot.usd")
converter = UsdToUrdfConverter(
    stage,
    root_prim_path="/World/robot",
    mesh_dir_name="meshes",
    mesh_path_prefix="./",
    visualize_collision_meshes=False,
    variant_selections=None,
)
converter.export("/path/urdf_out")

CLI：source/standalone_examples/api/isaacsim.asset.exporter.urdf/urdf_export.py（--usd-path、--output-dir、--root-prim、--mesh-prefix、--variant SET=SELECTION）。

常见问题

现象	原因	修复方法
训练期间 OOM	make_instanceable: false	设为 true
机器人散架	merge_fixed_joints: false + 刚性 PD	设为 true 或降低增益
质量错误	import_inertia_tensor: false + 几何体不正确	设为 true
自碰撞导致变慢	训练期间 self_collision: true	设为 false
XACRO 未转换	URDFImporter 核心不解析 XACRO	通过运行中的节点使用 isaacsim.ros2.urdf 导入（RobotDefinitionReader / File -> Import from ROS2 URDF Node），或使用 xacro robot.xacro > robot.urdf 在离线状态下预先展开
package:// URL 无法解析	缺少映射	传入 ros_package_paths=[{"name":..., "path":...}] 或 --ros-package NAME:PATH
MJCF 执行器行为异常	增益/偏置类型保留了 MJCF 默认值	设置 override_gain_type / override_bias_type / override_gain_prm / override_bias_prm
Transformer 输出被忽略	正在运行旧测试资产	删除 usd_path，并使用 run_asset_transformer=True 重新导入

Wheel 归属

不要将每个扩展本地 wheel 都视为规范的独立库。迁移后的 isaacsim.asset.transformer 模块随 isaacsim-asset 发行包一同发布，而 usd.schema.isaac 模块（包括现代的 usd.schema.isaac.robot_schema 导入）随 isaacsim-robot-schema 一同发布。isaacsim.robot.schema 是 Kit 扩展名称。请通过 source/libraries/build.sh -r --wheel（或 Windows 等效命令）构建这些发行包。

URDF/MJCF 导入器、URDF 导出器和转换器规则 wheel 仍采用旧版扩展打包方式。仅在维护该打包方式时，才使用 ./repo.sh build_standalone_wheels --ext <name> 构建这些 wheel；并保留任何必需的 Kit 引导流程，不要将 wheel 名称作为其不依赖 Kit 的证明。