URDF Validator & Fixer

Isaac Sim へインポート前に URDF ファイルを検証・修正します。USD の命名規則違反、重複したマテリアル、制限なしのジョイント、欠落した慣性プロパティ、破損したメッシュ参照など、通常はサイレント インポート失敗を引き起こす問題を検出します。

ワークフロー

最良の結果を得るため、以下の順序に従ってください:

フェーズ 1: 検査

ロボット モデルの構造概要を取得します。

urdf_inspect(file_path="/path/to/robot.urdf")

確認項目: リンク/ジョイント数、キネマティック ツリー、質量分布、メッシュ ファイル。

フェーズ 2: 検証

すべての既知の問題をチェックします。

urdf_validate(file_path="/path/to/robot.urdf")

確認項目: 問題を重大度(エラー > 警告 > 情報)とカテゴリ別に確認。

フェーズ 3: 修正

修正可能な問題を自動修正します。

urdf_fix(
    file_path="/path/to/robot.urdf",
    output_path="/path/to/robot_fixed.urdf"
)

元のファイルは 決して変更されません。結果の name_mapping を確認してください。リンク或いはジョイントが名前変更された場合、ダウンストリーム コード(コントローラー、設定)も更新が必要です。

フェーズ 4: 再検証

修正で問題が解決されたことを確認します。

urdf_validate(file_path="/path/to/robot_fixed.urdf")

修正されたカテゴリではエラー ゼロを想定します。残存する警告(例: 衝突ジオメトリなし、package:// URI)は手動対応が必要な場合があります。

ツール リファレンス

urdf_validate

パラメーター	型	デフォルト	説明
file_path	str	None	URDF ファイルのパス
urdf_string	str	None	URDF XML を文字列として指定
categories	list[str]	all	フィルター: usd_naming、materials、joint_limits、inertial、collision、mesh_references
min_severity	str	"info"	最小値: error、warning、info

urdf_fix

パラメーター	型	デフォルト	説明
file_path	str	None	URDF ファイルのパス
urdf_string	str	None	URDF XML を文字列として指定
output_path	str	auto	出力ファイル パス(デフォルト: *_fixed.urdf)
fix_categories	list[str]	all	usd_naming、materials、joint_limits、inertial
default_mass	float	0.1	欠落した慣性の既定質量(kg)
default_inertia	float	0.001	既定の対角慣性値
max_joint_position	float	2π	±inf 位置制限を置き換え
max_joint_velocity	float	π	既定の速度制限(rad/s)
max_joint_effort	float	100.0	既定の力制限(Nm)

urdf_inspect

パラメーター	型	デフォルト	説明
file_path	str	None	URDF ファイルのパス
urdf_string	str	None	URDF XML を文字列として指定

検証カテゴリ

カテゴリ	チェック内容	自動修正可能?
usd_naming	リンク/ジョイント/マテリアル名内のハイフン、ドット、スペース、先頭の数字	可 — 名前を変更し、すべての参照を更新
materials	異なる RGBA で定義が重複、テクスチャ欠落、JPEG 警告	可 — 接尾辞を付けて重複排除
joint_limits	無限制限、欠落した力/速度、欠落した <limit> 要素	可 — 設定可能なデフォルト値にクランプ
inertial	欠落した <inertial>、ゼロ/負の質量、ゼロ慣性テンソル	可 — 設定可能なデフォルト値を追加
collision	対応する衝突ジオメトリのない視覚ジオメトリ	不可 — 手動モデリングが必要
mesh_references	存在しないメッシュ ファイル、package:// URI	不可 — メッシュ ファイルはディスク上に存在する必要があります

Isaac Sim のヒント

• USD 命名は重要: Isaac Sim は URDF 名を USD prim パスに変換します。ハイフン、ドット、スペースはサイレント失敗またはパスの破損を引き起こします。
• 慣性は必須: <inertial> のないリンクはサイレント スキップされるか、物理シミュレーションの不安定性を引き起こす可能性があります。
• ジョイント制限が重要: 無限制限はソルバー発散を引き起こします。Isaac Sim は内部で制限することがありますが、動作は未定義です。
• package:// URI は解決されません: Isaac Sim は ROS パッケージの解決をサポートしません。相対パスまたは絶対パスに変換してください。
• 固定ジョイントはマージされます: デフォルトでは Isaac Sim が固定ジョイントをマージします。分離したい場合は、インポート設定で merge_fixed_joints = False を設定してください。

よくある落とし穴

1. 名前変更がダウンストリーム コードを破損: USD 命名修正後、ジョイント名が変更されます。name_mapping 出力を確認し、コントローラー設定、ROS トピック、ジョイント名を参照するコードを更新してください。
2. 既定の慣性値はプレースホルダー: 自動修正によりクラッシュを防ぐため小さいデフォルト値が追加されます。シミュレーションの精度向上には、実際の CAD 派生値に置き換えてください。
3. 衝突ジオメトリはパフォーマンスに影響: 衝突ジオメトリがないと、そのリンクへのコンタクト検出がありません。物理的に重要なリンクには簡略化された衝突メッシュを追加してください。
4. メッシュ パスは URDF の場所に相対: 固定 URDF を別のディレクトリに移動する場合、メッシュ参照が破損する可能性があります。URDF とメッシュ ディレクトリは一緒に保つてください。

エンド ツー エンド検証

修正後、Isaac Sim へのインポートが機能することを確認します:

/path/to/isaacsim/python.sh scripts/verify_urdf_isaac_sim.py \
    --original /path/to/robot.urdf \
    --fixed /path/to/robot_fixed.urdf

このスクリプトは両方の URDF をヘッドレスで インポートし、prim パス、ジョイント、アーティキュレーションをチェックして、物理ステップを実行し安定性を検証します。