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 为中心的机器人生态系统之间的轻量级、经过充分测试的桥梁，自动处理下载、缓存和格式转换。