urdf

URDF

由 earthtojake/text-to-cad で保守されています。 実行時の正となる情報源には、インストール済みのローカルスキルファイルを使用してください。 リポジトリへのリンクは、出典の確認とリリースレビューのみを目的としています。

URDF のロボット記述を出力する際は、このスキルを使用してください。URDF の作業は、単なる XML の記述ではなく、制約のある運動学モデリングとして扱ってください。主な正確性のリスクは、フレームの配置、ジョイント軸の意味、単位の一貫性、メッシュのスケール、慣性データです。

セットアップ

cadgen は uv 経由で実行し、このスキルのコマンドが CAD アプリのサーバーと同じインストールおよびウォームビルドデーモンを共有するようにします。

• 以下でいう cadgen は uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 cadgen を意味します。
• 以下でいう python は uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.26 python を意味します。

初回実行時にこのインストールがダウンロードされ、初回のスナップショット作成時にヘッドレスブラウザーがダウンロードされます。以降の実行では、どちらも再利用されます。

基本ルール

1. .urdf ファイルが唯一の正となる情報源です。URDF XML を直接作成・編集してください。Python による生成パイプラインは作成しないでください。gen_urdf() という仕様はありません。
2. URDF XML を作成または変更する前に、ロボットのフレーム、ジョイント、ジオメトリ、単位、前提条件を記録した台帳を作成し、.urdf ファイルの先頭にコメントブロックとして埋め込んでください。references/design-ledger.md を参照してください。
3. URDF のフレーム規則を正確に適用してください。ジョイントの原点、リンクフレーム、ジョイント軸、ビジュアル・衝突・慣性の各原点は、それぞれ異なる参照フレームを使用します。references/frame-semantics.md を参照してください。
4. 曖昧な説明から、空間変換、メッシュの単位、左右の向き、軸、ジョイントの符号を推測しないでください。CAD 変換、寸法入り図面、測定値、既存のソースデータ、または明示的に文書化した前提条件を使用してください。
5. 計算によって得られる数値（慣性テンソル、重心、多数のリンクにわたる単位変換、鏡像変換など）を手作業ででっち上げないでください。計算してください。プリミティブには閉形式の公式を、メッシュから導出する値には使い捨てのヘルパースクリプトを使用してください。references/inertials.md を参照してください。
6. 物理リンクでは、対象の利用者が必要とする場合、inertial、visual、collision を個別にモデル化してください。フレーム専用のリンクでは、質量とジオメトリを意図的に省略してもかまいません。
7. 作成または変更した .urdf はすべて、完了を報告する前に cadgen urdf validate で検証してください。references/validation.md を参照してください。
8. ヘルパースクリプトは計算のために使用でき、推奨されますが、あくまで補助的なものであり、成果物の正となる情報源ではありません。複雑なモデルや真のパラメトリックモデルでは、関連するソースコード（たとえば STEP 生成ソース）の隣に、モデル専用のヘルパースクリプトを保存し、台帳に記載してもかまいません。これは任意であり、チェックイン済みの .urdf が引き続き正本です。

モデルを表示する

作成または変更したファイルと、ユーザーから表示を求められたファイルをすべてユーザーに見せてください。スナップショットや検証で代用することはできません。

• ツールに cad_show（ホストによっては接頭辞が付く場合があります）が含まれている場合は、ファイルの絶対パスを指定して使用し、再度呼び出すタイミングについてはその説明に従ってください。cad_view はユーザーが選択したものを読み取り、cad_screenshot はユーザーが見ているものを表示します。どちらも自分の作業をレビューするためのものではありません。

• それ以外の場合は、任意のフォルダーから CAD Viewer を実行してください。

  cadgen viewer --host 127.0.0.1 --json --detach
  

  --detach を指定すると、ビューアーがリクエストに応答した時点で処理が戻り、バックグラウンドで実行を続けます。フォアグラウンドのビューアーは終了しないため、必ず指定してください（出力を tail にパイプすると URL が見えなくなる場合もあります）。このマシンで稼働するビューアーを起動するか、既存のものを再利用します。1 行の JSON から url を読み取り（ポートを推測しないでください）、ファイルごとに url?file=<そのファイルの URL エンコード済み絶対パス> を返してください。起動に失敗した場合は、その旨を伝えてください。

メッシュのスケールと配置を確認し、設計台帳に照らして、可動ジョイントをすべて動かして確認してください。リンク単体では ビューアーでの確認 は完了しません。実施できなかった確認があれば報告してください。

ワークフロー

1. 対象の .urdf ファイルとその利用先（RViz、robot_state_publisher、Gazebo/Ignition、MoveIt、実機のドライバー、または別のシミュレーター）を特定します。
2. フレーム、原点、軸、メッシュのスケール、制限、慣性を編集する前に、設計台帳を読み込むか作成します。台帳は .urdf 自体にコメントブロックとして記載してください。
3. リンクがメッシュを参照する場合は、まずメッシュアセットを準備します。リンクごとに1つのメッシュを用意し、該当リンクのフレームで、作成元のCAD／メッシュワークフローからエクスポートします。references/meshes.md を参照してください。
4. references/authoring-contract.md に従って構造、順序、命名を整え、URDF XMLを直接作成または編集します。
5. 慣性などの派生値は推測せず、必ず計算します。references/inertials.md を参照してください。
6. cadgen urdf validate で検証します。指摘事項を修正し、問題がなくなるまで再検証します。
7. references/validation.md の検証手順を実行します。利用可能な場合は外部ツール（check_urdf）で検証し、その後、すべてのジョイントを確認しながらビューアーでレビューします。
8. 残っている前提、未確認の空間データ、検証上の不足を報告します。

コマンド

Setupで定義されている方法で cadgen を実行します。cadgen doctor <skill-dir> は、現在使用中のインストールを報告し、それがこのスキルで固定されているものかを確認します。別のインストールではドキュメントとのずれが気付かないうちに生じるためです。検証自体にはPython標準ライブラリ以外は必要ありません。スナップショットの作成にのみブラウザーが必要です。現在のインターフェースの全容は cadgen <verb> --help で確認できます。

バリデーターの形式は次のとおりです。

cadgen urdf validate path/to/robot.urdf
cadgen urdf validate path/to/robot.urdf --strict
cadgen urdf validate path/to/robot.urdf --json
cadgen urdf validate path/to/robot.urdf --packages robot_description=/path/to/pkg
cadgen urdf snapshot path/to/robot.urdf review.png

バリデーターは、XML構造、ツリーのトポロジー、ジョイントの意味（制限、mimic、動力学）、ジオメトリ、メッシュ参照、マテリアル、慣性物理、要素のスペルミスについて、すべての指摘事項を1回の実行で収集し（重要度、コード、XMLパスを含む）、概要を出力します。1回の実行で検証できるファイルは1つです。--strict は警告を失敗として扱います。--json は {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"} を1行で出力します。このうち element はXMLパスです。--packages NAME=PATH は package:// メッシュURIを解決し、複数のルートについて繰り返し指定できます。対象が検証に失敗すると、ゼロ以外の終了コードを返します。相対パスで指定した対象は現在の作業ディレクトリを基準に解決されるため、ファイルを管理するワークスペースから実行してください。

検証は安全策であり、空間的な正しさを証明するものではありません。URDFはすべての構造チェックに合格していても、ジョイントの位置が誤っている場合があります。そのために台帳とビューアーでの確認があります。

スナップショットツール

cadgen urdf snapshot は、ロボットを PNG の静止画としてレンダリングします。すべてのレンダリングスキルが使う共通 CLI とヘッドレスブラウザーランタイムを使用するため、スナップショットは CAD Viewer の表示と一致します。

cadgen urdf snapshot path/to/robot.urdf review.png

受け付けるのは .urdf のみです。--joint-values でロボットのポーズを指定します。形式は {joint: degrees} の JSON です。指定しない関節は、CAD Viewer でロボットを開いたときのデフォルト値のままになります（パケット内の "jointValues" ジョブフィールドも同じです）。スナップショットではビューアー独自のシーンでロボットを描画するため、ビューアーに表示される内容がそのまま表示されます。リンクメッシュを読み込めない場合は、そのリンクを省略せずにエラーになります。ロボットはメートル単位で作成され、ロボットのシーンスケールに合わせて自動的にフレーミングされます。

通常のスナップショットでは、ソリッドモードとライトの外観が使われます。表示モードは solid（デフォルト）または parts（リンクごとに異なる色）で、それぞれに独自のデフォルト値があります。--grid を指定すると、ロボットの下に計測用グリッドが表示されます。--preview を指定すると、代わりに Preview 共通の写真風シーンがパースペクティブ表示されます。インライン表示 JSON と JSON ファイルには、ビューアーの表示オブジェクトを指定します。設定項目は mode、grid、appearance（light がデフォルト、または dark）、camera（投影法と焦点距離）、clip です。トップレベルの --camera と --joint-values は、どの表示モードでも有効です。display.clip は、ビューアーの Clip と同様にロボットを切断します（{"clip":{"axis":"x","at":0.05}}。at の単位はメートルです）。exploded、shaded、xray、hidden-line、wireframe は STEP モデルの CAD エッジとパーツを表す設定であり、ここでは名前を指定して拒否されます。ビューアーからの Quick Edit ジョブは、そのまま再生されます。つまり、jointValues、selection.hide（Links パネルで非表示にしたパーツの ID）、clip、注釈が適用されます（cadgen snapshot --job <file>）。Quick Edit では、インライン JSON または .snapshot.json パスを指定できます。インライン JSON を --job で使う場合は、一時ファイルに保存してください。編集の前に、提供された注釈を確認してください。注釈がない場合、キャプチャされたビューは任意のコンテキスト情報です。リクエストに役立つ場合にレンダリングしてください。

リンクメッシュは記述ファイルを基準に解決されるため、実際に存在している必要があります。未ハイドレートの Git LFS ポインターは、"No link mesh loaded for robot" というエラーになります。先に git lfs checkout <mesh dir> を実行してください。

文法は cadgen urdf snapshot TARGET [OUT] [flags] で、すべての形式の入口で共通です。現在のインターフェイス全体については cadgen urdf snapshot --help を使用してください。ロボットで実行できないフラグは、拒否されるのではなく、ヘルプに表示されません。

参考資料

• 作成規約（構造、順序、ゴールデンスケルトン）：references/authoring-contract.md
• 設計記録：references/design-ledger.md
• フレームの意味論：references/frame-semantics.md
• メッシュの準備と参照：references/meshes.md
• 慣性（数式、スクリプト、健全性チェック）：references/inertials.md
• URDF 編集ワークフロー：references/urdf-workflow.md
• 検証と確認の手順：references/validation.md