srdf

SRDF

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

このスキルは、有効なURDFがすでに存在する場合に、MoveItの意味記述を作成するために使用します。SRDFはプランニングの意味を定義するものであり、ロボットの物理構造は定義しません。.srdfファイルが信頼できる情報源です。XMLを直接作成・編集してください。gen_srdf()の仕様はありません。

SRDFの正しさは、プランニングの意味に関する問題です。よくある失敗は、XMLが無効であることではありません。MoveItに誤ったプランニンググループ、誤ったツールリンク、誤ったデフォルト状態、安全でない衝突無効化マトリックス、または誤った関節単位を与える、もっともらしいSRDFを作成してしまうことです。言語モデルは空間および運動学的な推論が不得意なため、プランニンググループ、エンドエフェクター、グループ状態、衝突無効化は、URDFのトポロジー、MoveIt Setup Assistantの出力、サンプリングした衝突解析、またはユーザーが明示したデータから導き出してください。見た目のテーマだけから推測しないでください。また、リンク名や関節名を記憶に頼って入力しないでください。まずURDFのリンク／関節一覧を抽出し、そこから名前をコピーしてください。

セットアップ

uvを使ってcadgenを実行してください。そうすることで、このスキルのコマンドは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を意味します。

初回実行時に、このインストール環境とヘッドレスブラウザー用の最初のスナップショットがダウンロードされます。以降の実行では、両方が再利用されます。

フォーマットの境界

• URDFは、リンク、関節、形状、慣性、制限、模倣関節、トランスミッション、ロボット状態のパブリッシュなど、ロボットの物理構造を定義します。
• SRDFは、仮想関節、受動関節、プランニンググループ、グループ状態、エンドエフェクター、衝突無効化ペアなど、MoveItの意味を定義します。
• SDFは、物理、センサー、ライト、プラグイン、ワールド、シミュレーション固有のメタデータなど、シミュレーター／ワールドの意味を定義します。

形状、慣性、関節の原点、リンクの姿勢、メッシュ参照、物理関節の制限、トランスミッション、ros2_controlインターフェースをSRDFに記述しないでください。

モデルを表示する

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

• 使用可能なツールに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エンコードされた絶対パス>を返してください（ポートを推測してはいけません）。起動に失敗した場合は、その旨を伝えてください。

SRDFは、対応するURDFが一意に特定できるよう、そのURDFと同じ場所に置いてください（ロボット名が同じであること）。プランニンググループ、名前付き状態、関節をレビューしてください。視覚的なレビューだけでは、プランニングの正しさを証明できません。

必須のワークフロー

1. 有効な URDF から始めます。 まず $urdf で URDF を作成または修正し、検証します。SRDF は同じフォルダーに配置され、ロボット名が一致する URDF と対になります。SRDF 内の名前はすべて、その URDF に存在していなければなりません。
2. URDF の一覧表を作成します。 SRDF の XML を書き始める前に、URDF のロボット名、リンク、ジョイント（種類、親、子、制限、mimic フラグ）を一覧にします。名前はこの一覧表からのみコピーし、記憶を頼りに入力してはいけません。references/srdf-workflow.md を参照してください。
3. 計画タスクを特定します。 目標がアーム IK、グリッパー制御、移動ベースの計画、デュアルアーム計画、ツールの使用、ローカルのスモークテストのいずれかを記録します。
4. 計画台帳を作成または更新します。 XML を書く前に references/planning-ledger.md を使用し、.srdf にコメントブロックとして簡潔なコピーを残します。
5. URDF と同じフォルダーに配置して対にします。 .srdf は対応する .urdf と同じフォルダーに保存し、同じ <robot name> を指定します。これが唯一の紐付け方法です。バリデーターとビューアーは、フォルダーを走査してロボット名が一致する URDF を見つけ、ファイルを対にします。フォルダー内では、ロボット名ごとに URDF はちょうど 1 つでなければなりません。ファイルを紐付けるメタデータ要素はありません。references/authoring-contract.md を参照してください。
6. 仮想ジョイントとパッシブジョイントを意図的に定義します。 ロボットモデルで必要な場合に使用します。
7. URDF のトポロジーに基づいて計画グループを定義します。 直列マニピュレーターでは、URDF ツリー内でベースと先端が実際の親子パスを形成する場合、チェーングループを優先します（バリデーターがこれを検証します）。ジョイント、リンク、サブグループの定義は、意図的に選択する場合にのみ使用します。
8. グループのメンバーが確定してからエンドエフェクターを定義します。 エンドエフェクターグループとその親グループが重複しないようにします。実際のターゲット/TCP リンクを記録します。
9. グループ状態は URDF 固有の単位で定義します。 回転ジョイントと連続ジョイントの値はラジアン、直動ジョイントの値はメートルです。SRDF に度単位の値を保存してはいけません。値は URDF の制限範囲内でなければならず、固定ジョイントや mimic ジョイントを設定してはいけません。
10. 根拠に基づいて無効化する衝突を生成します。 URDF ジョイント一覧から導出した隣接関係、MoveIt Setup Assistant のサンプリング、またはユーザーが明示的に提供した衝突行列を使用します。根拠なく広範な無効化リストを作成してはいけません。references/disabled-collisions.md を参照してください。
11. 作成または変更したすべての .srdf を cadgen srdf validate で検証します。 対応する URDF と照合し、すべての名前、チェーン、状態、ファイルの組み合わせを相互検証します。問題がなくなるまで指摘事項を修正して再検証します。
12. 利用可能な場合は MoveIt のスモークテストを実行します。 MoveIt Setup Assistant、またはプロジェクトの MoveIt 起動方法を直接使用します。
13. 前提事項と省略したチェックを報告します。 検証の未完了、MoveIt 環境の不足、手動で判断した衝突の無効化、推定したターゲットリンクを含めます。

コマンド

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

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

cadgen srdf validate path/to/robot.srdf
cadgen srdf validate path/to/robot.srdf --strict
cadgen srdf validate path/to/robot.srdf --json

バリデーターは SRDF を解析し、対応する URDF（同じフォルダーにあり、ロボット名が一致する .urdf。該当なし、複数、または無効なものがある場合はエラー）を解決して、名前（グループ、ジョイント、リンク、サブグループ）の存在、チェーンパスの解決可能性、サブグループの循環、仮想ジョイントとパッシブジョイント、エンドエフェクターのトポロジー、グループ状態のメンバーシップ・制限・完全性、無効化する衝突ペア（Adjacent という理由が事実に即しているかを含む）、誤記された要素を相互検証します。各フェーズでは、すべての指摘事項（重大度、コード、XML パス）を 1 回の処理で収集します。ただし、構造エラーがあるとファイル間の検証フェーズは停止します。修正するたびに再実行してください。1 回の実行で検証できるファイルは 1 つです。--strict を指定すると警告は失敗として扱われ、--json を指定すると {"ok", "path", "issues": [{"severity", "code", "message", "element", "hint"}], "summary"} の 1 行が出力されます。このうち element は XML パスです。対象が検証に失敗した場合は、ゼロ以外の終了コードを返します。相対パスの対象は、現在の作業ディレクトリを基準に解決されます。

厳守事項

• SRDFはURDFと同じフォルダーに置き、<robot name>を共有します。この同一フォルダーへの配置と名前の一致だけが対応付けの方法であり、フォルダー内に同じロボット名のURDFが複数存在してはなりません。
• すべてのリンク名、ジョイント名、グループ名、サブグループ名は、URDFの表、または同じファイル内で定義されたグループに由来する必要があります。
• グループ状態にはURDF標準の単位を使用します。回転関節／連続関節はラジアン、直動関節はメートルです。
• 無効化する衝突ペアには、正確な理由と出典情報が必要です。
• エンドエフェクターのグループは、親のプランニンググループとリンクを共有しないようにしてください。
• ビジュアルレンダリングの確認は有用ですが、プランニングの正しさを証明することはできません。

スナップショットツール

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

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

.srdfを渡すと、拡張子に応じて処理が振り分けられ、対応するURDFのジオメトリがレンダリングされます。対象となるのは、<robot name>が一致する同じフォルダー内の.urdfです。これはcadgen srdf validateの対応付けと同じです。一致するものがない場合や、複数ある場合は、レンダリング開始前に処理を拒否し、検索対象のロボット名と見つかった.urdfファイルを表示します。--joint-valuesでロボットの姿勢を指定します（{joint: degrees}形式のJSON）。指定していないジョイントは、CAD Viewerでロボットを開いたときと同じ状態になります。各ジョイントのデフォルト値が適用され、その後、このSRDFで定義されている場合はhomeグループ状態が適用されます（パケット内の"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）、クリップ設定、注釈が適用されます（cadgen snapshot --job <file>）。Quick EditではインラインJSONまたは.snapshot.jsonパスを指定します。--jobを使う前に、インラインJSONを一時ファイルに保存してください。編集前に、指定された注釈を確認してください。注釈がない場合、キャプチャされたビューは任意のコンテキストです。リクエストに役立つ場合はレンダリングしてください。

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

SRDFのジオメトリは対応するURDFに由来するため、SRDF専用のスナップショット用コマンドはありません。多態的なcadgen snapshotが拡張子に応じて処理を振り分けます。構文はcadgen snapshot TARGET [OUT] [flags]で、すべての形式のコマンドで共通です。現在のインターフェイス全体については、cadgen snapshot --helpを使用してください。

参考資料

• 作成規約（構造、URDFの対応付け、基本スケルトン）：references/authoring-contract.md
• SRDFワークフロー（URDF表の抽出、編集ループ）：references/srdf-workflow.md
• プランニング台帳：references/planning-ledger.md
• 検証手順と確認レシピ：references/validation.md
• エンドエフェクター：references/end-effectors.md
• 無効化する衝突：references/disabled-collisions.md