robot-descriptions/robot_descriptions.py

robot-descriptions – 用於機器人模型資產的 Python 庫

是什麼 – 一個純 Python 套件，讓你可將開源機器人描述檔案（URDF、MJCF 等）當作一般 Python 模組進行匯入。首次請求機器人時，該套件會自動從精心整理的 Awesome Robot Descriptions 收集庫中下載描述，本地快取，並提供一個可直接用於多種模擬與分析工具的就緒物件。

為何重要 – 機器人研究與開發通常需要相同的機器人模型（例如 KUKA iiwa、Franka Panda、Boston Dynamics Spot）。在不同專案間保持這些檔案同步非常麻煩。robot_descriptions 透過提供一個在 GitHub 上版本控制的單一可信來源，解決此問題，並透過極簡的 Python API 可存取。它與最常見的機器人軟體堆疊相容，因此你可輕鬆在 MuJoCo、Pinocchio、PyBullet、iDynTree、RoboMeshCat 或 yourdfpy 之間切換，無需手動處理檔案。

安裝

# conda-forge（推薦用於科學 Python 堆疊）
conda install -c conda-forge robot_descriptions

# 或透過 pip
pip install robot_descriptions

基本用法（Python）

from robot_descriptions.loaders.pinocchio import load_robot_description

# 回傳一個可用於運動學／動力學呼叫的 Pinocchio 模型
robot = load_robot_description("upkie_description")

該套件為每個支援的後端提供一個載入器：

後端	載入器模組
iDynTree	`robot_descriptions.loaders.idyntree`
MuJoCo	`robot_descriptions.loaders.mujoco`
Pinocchio	`robot_descriptions.loaders.pinocchio`
PyBullet	`robot_descriptions.loaders.pybullet`
RoboMeshCat	`robot_descriptions.loaders.robomeshcat`
yourdfpy	`robot_descriptions.loaders.yourdfpy`

每個載入器在未快取時會下載請求的描述，並回傳該框架原生的物件。

命令列介面

該套件也提供一個小型 CLI（透過 robot_descriptions 入口點或 uvx robot_descriptions 暴露）。範例指令：

# 預先下載一個模型
uvx robot_descriptions pull iiwa14_description

# 在 MuJoCo 中視覺化（需要可選的 mujoco-python-viewer）
uvx --with mujoco-python-viewer robot_descriptions show_in_mujoco go2_mj_description

# 在 MeshCat 中視覺化
uvx --with meshcat robot_descriptions show_in_meshcat go2_description

CLI 與 Python API 一致：pull 用於快取，show_in_* 用於為所選後端啟動檢視器。

將描述當作子模組匯入

你可以將機器人描述當作一般 Python 子模組來使用：

from robot_descriptions import panda_description

print(panda_description.URDF_PATH)          # 主 URDF 檔案路徑
print(panda_description.PACKAGE_PATH)       # 描述套件根目錄
print(panda_description.REPOSITORY_PATH)    # 克隆的 Git 倉儲位置

某些套件會暴露額外的常數（例如用於高精度碰撞網格的 URDF_PATH_POLYTOPE_COLLISION）或 Xacro 處理（XACRO_PATH + 可選的 XACRO_ARGS）。

哪些機器人模型可用？

該套件索引了 Awesome Robot Descriptions 圖庫。模型依類型（機械臂、雙足、四足、無人機等）分組，並在可用時包含 URDF 與 MJCF 變體。一些範例：

panda_description / panda_mj_description（Franka Emika Panda）
iiwa14_description / iiwa14_mj_description（KUKA iiwa-14）
go2_description（Unitree Go2 四足機器人）
omx_f_description（ROBOTIS OpenManipulator-F）
low_cost_robot_arm_mj_description（DeepMind 資源庫中的簡單 MJCF 機械臂）

每個條目列出原始維護者、檔案格式和授權（BSD-3、Apache-2.0、MIT、GPL-3 等）。

範例腳本（在倉儲中）

倉儲包含可直接執行的範例，展示如何在每個支援的後端中載入模型並視覺化：

examples/load_in_pinocchio.py
examples/show_in_meshcat.py
examples/show_in_mujoco.py …以及 iDynTree、PyBullet、RoboMeshCat 和 yourdfpy 的等效腳本。

誰會使用它？

研究人員：建構需要多種機器人模型的模擬流程。
機器人教育者：希望學生無需手動尋找檔案即可嘗試多種機械臂與移動平台。
模擬到實體流程開發者：需要一種可靠方式取得訓練期間使用的精確 URDF/MJCF 檔案。

授權與貢獻

該套件本身採用 MIT 授權發布（參見 PyPI 標籤）。機器人描述檔案保留其原始上游授權，並在生成的表格中顯示。歡迎貢獻，詳情請參見 CONTRIBUTING.md 標籤。

總結 – robot_descriptions 是連接開源機器人模型倉儲與以 Python 為中心的機器人生態系統之間的輕量級、經過充分測試的橋樑，自動處理下載、快取與格式轉換。