urdf

Name: urdf
Author: earthtojake

URDF

來源：維護於 earthtojake/text-to-cad。
使用安裝的本地技能檔案作為執行時的真實來源；儲存庫連結僅供來源追溯與版本審查。

使用此技能處理 URDF 機器人描述輸出。將 URDF 工作視為約束運動學建模，而非單純的 XML 撰寫。主要正確性風險包括框架放置、關節軸語義、單位一致性、網格縮放、慣性資料以及生成產物的漂移。

核心規則

將定義 gen_urdf() 的 Python 原始碼視為真實來源。將配置的 .urdf 檔案視為生成的產物。
僅生成明確的 URDF 目標。不要從此技能重新生成不相關的 CAD、網格、渲染、SRDF、SDF 或模擬器產物。
scripts/urdf 生成器預設會驗證生成的 URDF。不要使用或記錄單獨的 validate 指令。
在撰寫或修改 URDF XML 之前，建立機器人的框架、關節、幾何、單位與假設記錄。請參閱 references/design-ledger.md。
精確使用 URDF 框架語義。關節原點、連桿框架、關節軸以及視覺/碰撞/慣性原點使用不同的參考框架。請參閱 references/frame-semantics.md。
不要從模糊的文字推斷空間轉換、網格單位、手性、軸或關節方向。應使用 CAD 轉換、標註圖紙、測量值、現有原始資料或明確記錄的假設。
偏好簡單、可稽核的生成器程式碼，而非複雜的 XML 建構。常數應以物理意義命名，而非任意數字。
對於實體連桿，當目標使用者需要時，分別建模 inertial、visual 和 collision。僅框架的連桿可以刻意省略質量和幾何。

CAD Viewer 交接

完成建立或修改 .urdf 的 URDF 工作後，若該技能已安裝，你必須始終將明確的檔案路徑交給 $cad-viewer。$cad-viewer 必須啟動 CAD Viewer（如果尚未執行）並回傳相關已建立或更新檔案的連結；如果 $cad-viewer 不可用或啟動失敗，則回報該情況，而非默默省略交接。

工作流程

識別 gen_urdf() 的 Python 原始碼與目標 .urdf 輸出。
識別目標使用者：RViz、robot_state_publisher、Gazebo/Ignition、MoveIt、真實機器人驅動程式或其他模擬器。
在編輯框架、原點、軸、網格縮放、限制或慣性之前，讀取或建立設計記錄。
編輯生成器原始碼，而非生成的 URDF XML。
僅使用 scripts/urdf 重新生成明確的目標。
讓生成時驗證在 XML、圖形、關節、幾何、網格參考和慣性問題上快速失敗。
當幾何或網格參考依賴於變更的 CAD 或匯出的網格輸出時，使用所屬的 CAD 或網格工作流程重新生成那些明確的產物，然後重新生成受影響的 URDF 目標。
如果可行，針對目標執行消費者冒煙測試：RViz 顯示、robot_state_publisher 樹、Gazebo/Ignition 載入或 MoveIt 模型載入。
回報剩餘的假設、未檢查的空間資料以及驗證/冒煙測試的缺口。

指令

使用專案或工作區的 Python 環境執行。將範例中的 python 視為直譯器佔位符；如果裸 python 不可用，請替換為 python3、專案虛擬環境直譯器或配置的直譯器路徑。URDF 生成器和輕量驗證器僅使用 Python 標準函式庫；下游消費者（如 RViz、Gazebo 或 MoveIt）可能需要自己的執行時套件。

從此技能目錄，啟動器格式為：

python scripts/urdf path/to/source.py
python scripts/urdf path/to/source.py -o path/to/robot.urdf
python scripts/urdf path/to/a.py=out/a.urdf path/to/b.py=out/b.urdf

純 Python 目標會在原始碼旁生成同名的 .urdf。-o/--output 僅在只有一個純目標時有效。對於自訂的多目標目的地，請使用 SOURCE.py=OUTPUT.urdf 配對。

相對的原始碼目標和 CLI 輸出覆蓋會從目前工作目錄解析。當從此技能目錄外部執行時，請加上啟動器路徑前綴，以便目標檔案仍從預期的工作區解析。

啟動器僅執行 gen_urdf() 並驗證生成的 URDF 輸出。它不提供單獨的僅驗證指令。