sdf

SDF

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

成果物が SDFormat ドキュメントである場合に、このスキルを使用してください。SDFormat は、モデル、ワールド、フレーム、ポーズ、リンク、ジョイント、慣性、ビジュアル、衝突、センサー、ライト、物理、プラグイン、インクルード、シミュレーターのメタデータなど、シミュレーターとワールドの動作を記述します。

このスキルの対象は SDFormat であり、符号付き距離場のジオメトリではありません。

.sdf ファイルが信頼できる情報源です。XML を直接作成・編集してください。gen_sdf() の契約はありません。

セットアップ

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. .sdf XML を直接作成し、作成または変更したファイルはすべて、完了を報告する前に cadgen sdf validate で検証してください。
2. 編集前に対象の利用環境を特定してください。Gazebo/libsdformat のバージョン、別のシミュレーター、可視化専用ツール、モデルパッケージ、ワールドの受け渡しなどが該当します。
3. ドキュメントの種類を決定してください。モデルレベルの SDF、ワールドレベルの SDF、またはワールド内のモデルのいずれかです。再利用可能なロボットやオブジェクトのエクスポートには、モデルレベルの SDF を優先してください。
4. 対象が明示的に別の単位を要求しない限り、SI 単位を使用してください。メートル、キログラム、秒、ラジアンが該当します。
5. 新しい出力では、対象の利用環境にバージョン上の制約がない限り、version="1.12" を優先してください。
6. ポーズ、フレーム、ジョイント軸、メッシュスケール、慣性、センサー、プラグインを記述する前に設計台帳を作成し、.sdf の先頭にコメントブロックとして保持してください。references/design-ledger.md と references/llm-guardrails.md を参照してください。
7. 重要なポーズと軸すべてに、relative_to / expressed_in を明示してください。暗黙のフレーム既定値は、SDF で最もよくある失敗の原因です。references/frame-semantics.md を参照してください。
8. 見た目だけから空間変換を推測しないでください。ポーズ、軸、スケール、質量、慣性、フレーム名は、上流のソースデータ、図面、シミュレーターのドキュメント、測定値、または明示的な仮定に基づいて導出してください。計算値を手作業で見積もらないでください。公式や使い捨てのヘルパースクリプトを使用してください（慣性テンソル、単位変換など）。
9. ロボットにすでに URDF がある場合は、ジオメトリを再記述するのではなく、そこから SDF を導出してください。references/interoperability.md を参照してください。
10. SDF が参照するジオメトリ、メッシュ、ロボット記述、レンダリング、トポロジー、パッケージのアセットを編集する前に、それぞれを管理するワークフローで上流のアセットを再生成してください。
11. 作成後、利用可能なチェックを実行してください。バンドルされた検証（gz が PATH にある場合は gz sdf --check も実行します）、シミュレーターへの読み込み、ジョイントの動作、プラグインとセンサーの起動を確認してください。
12. 仮定、省略したチェック、未解決のリソースパス、対象固有の互換性リスクを報告してください。

対象範囲

SDFormat の出力には、このスキルを使用してください。明示的にシミュレーターのみを対象とするタスクでない限り、符号付き距離場のモデリング、生のジオメトリ生成、プランニングの意味論、誤った上流のロボットデータやソースデータの取り繕いには使用しないでください。

モデルの表示

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

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

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

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

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

配置、リソース、ジョイントを確認してください。ビューアーはシミュレーターのプラグインを実行せず、ダイナミクスも検証しません。シミュレーターのチェックは別途行ってください。

ワークフロー

1. 対象の .sdf と、それを使用するものを特定します。
2. 設計台帳のコメントブロックを読み込むか、作成します。
3. <pose>、<frame>、ジョイント軸、relative_to、expressed_in、ネストされたスコープ、センサーフレーム、プラグインフレームのいずれかを編集する前に、references/frame-semantics.md を読みます。
4. references/examples.md の実例に従って、XML を直接作成します。
5. cadgen sdf validate で明示的に指定した対象を検証します。バンドルされた検証は安全策として扱い、シミュレーターでの検証とは見なさないでください。
6. 利用可能な場合は、対象を使用するものに対するスモークテストを実行します（references/smoke-tests.md）。
7. 結果を表示します（モデルの表示）。静的レンダリングでは、SDF プラグインは実行されず、ファイルに記述されたモーションメタデータも読み込まれません。
8. 実行したチェック、省略したチェック、前提条件を報告します。

コマンド

Setup で定義されている方法で cadgen を実行します。cadgen doctor <skill-dir> は、使用中のインストールを報告し、それがこのスキルで指定されたものかどうかを確認します。別のインストールではドキュメントとの不整合が表面化しないためです。検証には Python 標準ライブラリ以外は必要ありません。ブラウザーが必要なのはスナップショットだけです。現在のインターフェース全体を確認するには、cadgen <verb> --help を使用します。

cadgen sdf validate path/to/model.sdf
cadgen sdf validate path/to/model.sdf --strict
cadgen sdf validate path/to/model.sdf --json
cadgen sdf snapshot path/to/model.sdf review.png

バリデーターは、ドキュメントの構造、名前のスコープ、ポーズ／フレームのグラフ、ジョイント、ジオメトリ、メッシュ URI、慣性、センサー、プラグインをチェックし、検出内容と概要を出力します。1 回の実行で検証できるファイルは 1 つです。--strict は警告を失敗として扱い、--json は {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"} の 1 行を出力します。element は XML パスです。対象が失敗すると、ゼロ以外の終了コードを返します。

外部チェックはデフォルトで有効です。

cadgen sdf validate path/to/model.sdf --gz-check required
cadgen sdf validate path/to/model.sdf --gz-check never

gz sdf --check は、対象を使用するものに対する検証です。--gz-check auto がデフォルトです。gz が PATH 上にあれば実行し、gz_check_passed を報告します。失敗した場合は、そのツールの出力をエラー gz_check_failed として報告します。gz がない場合は info: gz_check_unavailable と記録して処理を続行します。任意のツールがないことはファイルについて何も示さないため、問題のないドキュメントが失敗することはなく、--strict によっても挙動は変わりません。--gz-check required を指定すると、そのツールが必須になります。つまり、gz が見つからない場合はエラーになります。--gz-check never を指定すると、チェックを完全に省略します。

必須のレポート形式

SDF タスクを完了する際は、簡潔なレポートを含めてください。

Validated: path/to/model.sdf
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- viewer review: live link returned, or explicit launch failure
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.

Snapshot ツール

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

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

.sdf のみを受け付けます（フォーマットの入口であり、ほかと同じ TARGET [OUT] 文法です）。--joint-values — {joint: degrees} 形式の JSON — でロボットの姿勢を指定します。指定しないジョイントは、CAD Viewer でロボットを開いたときのデフォルト値のままになります（パケット内の "jointValues" ジョブフィールドも同じものです）。スナップショットは Viewer 独自のシーンでロボットを描画するため、Viewer と同じ表示になります。また、リンクメッシュを読み込めない場合は、そのリンクを表示から省くのではなく、処理が失敗します。ロボットはメートル単位で作成され、ロボットシーンのスケールに合わせて自動的にフレームに収められます。

通常のスナップショットでは Solid モードと Light 外観が使われます。表示モードは solid（デフォルト）または parts（各リンクを独自の色で表示）で、それぞれに個別のデフォルト値があります。--grid はロボットの下に計測グリッドを描画し、--preview は代わりに Preview 共通の写真風シーンを遠近法で描画します。インラインの表示 JSON と JSON ファイルには、Viewer の表示オブジェクトを指定します。項目は mode、grid、appearance（light がデフォルト、または dark）、camera（投影方式と焦点距離）、clip です。 最上位の --camera と --joint-values は、どの表示モードでも引き続き有効です。 display.clip は、Viewer の Clip と同じようにロボットを切断します（{"clip":{"axis":"x","at":0.05}}。at はメートル単位です）。exploded、および shaded、xray、hidden-line、wireframe は STEP モデルの CAD エッジとパーツを指定するものであり、ここでは名前を挙げて拒否されます。Viewer の Quick Edit ジョブは、そのまま再現されます。jointValues、selection.hide（Links パネルで非表示にしたパーツの ID）、clip、annotation が対象です（cadgen snapshot --job <file>）。Quick Edit ではインライン JSON または .snapshot.json のパスを指定します。--job を使う前に、インライン JSON を一時ファイルに保存してください。編集前に、指定されている注釈を確認してください。注釈がない場合、キャプチャしたビューは任意のコンテキストです。依頼に役立つ場合はレンダリングしてください。

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

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

参考資料

• SDF ワークフロー：references/sdf-workflow.md
• 作成例（基準となるスケルトン）：references/examples.md
• LLM のガードレール：references/llm-guardrails.md
• 設計台帳：references/design-ledger.md
• フレームのセマンティクス：references/frame-semantics.md
• 検証範囲：references/validation.md
• スモークテスト：references/smoke-tests.md
• 相互運用性に関する注記（URDF 由来の SDF、メッシュ、Gazebo）：references/interoperability.md