urdf-mjcf-to-usd-conversion

URDF / MJCF から USD への変換

目的

最新のインポーター API、インスタンス化可能なメッシュ、RL または遠隔操作向けのドライブ設定を使用して、URDF および MJCF のロボット記述を USD にインポートします。

前提条件

• インポーターのコマンドと UI を使用するには、ビルド済みの Isaac Sim と isaac-sim-orchestrator の環境が必要です。
• 移行済みのトランスフォーマー／スキーマ API を使用するには、source/libraries のビルドが完了しているか、 対応するインストール済みホイールが必要です。レンダリングには 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 拡張機能は、実装を重複させることなく、ビルド済みのホイールと SDK をステージングします。

既存の PhysX 作成済み USD（URDF/MJCF ではない）の場合は、代わりに physx-to-newton-conversion を使用してください。

2 つの変換経路と 1 つのエクスポート経路があります。

経路	用途	実行方法
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 を参照

スクリプトの実行

スキル実行ヘルパーを公開するエージェントランタイムからは、run_script() を使ってヘルパーを呼び出します。

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

ビルド済みの Isaac Sim ツリーからは、_build/*/release にある ./python.sh（Linux）または python.bat（Windows）で同じファイルを実行します。シミュレーターが不要な場合は、シェルヘルパーを直接実行することもできます。

XACRO 入力

URDFImporter コアは XACRO を解析しません。対応している方法は 2 つあります。

推奨 — 実行中の 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 を公開する到達可能なノード、およびロボットのワークスペースを source したターミナルから起動した Isaac Sim が必要です。source したワークスペースには、ロボット記述パッケージと、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 を Path 1 または Path 2 に渡してください。

Path 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）。

インポート時に適用される Robot 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 トレーニング（エージェントがトルクを制御）	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 上のメッシュを 1 つ共有します。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.robot_schema インポートを含む usd.schema.isaac モジュールは isaacsim-robot-schema に含まれます。isaacsim.robot.schema は Kit 拡張機能の名前です。ディストリビューションは source/libraries/build.sh -r --wheel（または Windows 相当のコマンド）でビルドします。

URDF/MJCF インポーター、URDF エクスポーター、transformer-rules の wheel は、従来の拡張機能パッケージング方式を引き続き使用します。この方式を維持する場合に限り、./repo.sh build_standalone_wheels --ext <name> でビルドしてください。また、wheel の名前を Kit から独立している証拠として示すのではなく、必要な Kit のブートストラップを維持してください。