一台机器人还没接上电源，开发者已经可以在电脑里查看它的身体结构。软件依据什么判断哪里是肩膀、手肘朝哪个方向弯，甚至前臂会不会碰到躯干？这些问题，需要先读懂机器人的模型文件。
这次从启元机器人官方开发者社区的资料下载页下载 Q1 URDF 模型包，我先做了一个计数：主 URDF 文件里有 25 个 joint 标签，类型为 revolute 的却只有 22 个。剩下 3 个为什么也叫关节？沿着 Q1 的左臂读下去，URDF 的用途就具体了。
本文使用官方 Q1 URDF v1.0.0 资料包中的 q1_v3.urdf。
下载时，在官方页面的“其他资料包”中找到“Q1 URDF v1.0.0”，点击这一行右侧的“下载”。也可使用从该按钮取得的Q1 URDF v1.0.0 官方 ZIP 直链。本文核验的是这份文件；后续更新请以官方资料页为准。
先把手臂拆成连杆和连接关系
URDF 是 Unified Robot Description Format，通常译为统一机器人描述格式。它用 XML 文本描述机器人的部件及其连接方式。用普通文本编辑器打开 .urdf 文件，就能读到名称、尺寸、关节类型等内容。
其中两个词最常见：link 和 joint。link 可以理解为建模时看作刚体的一个部件，也就是连杆；joint 则说明两个连杆怎样连接。这里的“关节”比日常说法宽一些：即使两块部件始终固定在一起，模型也可以用一个 fixed 类型的 joint 记录它们的位置关系。
Q1 左肘的连接关系很明确。left_elbow_joint 的 parent 指向 left_shoulder_yaw_link，child 指向 left_elbow_link。后者再通过一个固定连接，连到 left_wrist_yaw_link。名称中的 shoulder、elbow、wrist，分别对应肩、肘、腕；但判断能否运动，还得看类型。
Q1左肘附近的连接关系。蓝色表示连杆，橙色表示转动关节，灰色表示固定连接。为便于阅读，只保留左臂的一段；这是依据文件绘制的结构示意图，不代表零件实际比例。
这也解释了开头的计数。在本次检查的文件中，26 个 link 由 25 个 joint 连起来，构成一棵连接树；其中 22 个 joint 是有角度限位的转动关节，另外 3 个是固定连接。因此，“25 个关节标签”和“22 个转动关节”都对，只是统计对象不同。这个结果描述的是该版本模型，不能直接当作所有 Q1 配置的硬件规格。
弯一次手肘需要写清哪些条件
只知道两个部件相连，还不能确定动作。门合页装在门的哪一边、轴朝哪个方向，都会影响门怎么开。URDF 也需要交代连接位置、转轴，以及允许转动的范围。
在 Q1 的主 URDF 中，左肘的 type 是 revolute，表示绕一条轴转动且存在角度上下限。origin 描述关节坐标系相对父连杆的位置和朝向，axis 则给出关节自身坐标系里的转轴方向。左肘 axis 为 0 1 0，即绕局部 Y 轴转动。不能把这个 Y 轴直接理解成屏幕竖直方向；机器人姿态变化后，局部坐标轴在画面中的方向也会改变。
| 左肘参数 | 主 URDF 中的值 | 读法 |
|---|---|---|
| type | revolute | 有角度限位的转动关节 |
| axis | 0 1 0 | 绕关节局部 Y 轴转动 |
| lower | −0.87266 rad | 约 −50.0° |
| upper | 1.6581 rad | 约 95.0° |
表中数值直接取自 q1_v3.urdf 的 left_elbow_joint；角度换算按“弧度 × 180 ÷ π”计算。这里的零位由模型坐标定义，并不意味着我们看到的手臂一定伸直。
为了确认连接关系，我用配套模型做了一次姿态可视化：保持其余关节设置不变，只把左肘从 0 rad 改成 1 rad，约为 57.3°。随之改变位置的不只有肘部对应的连杆，固定在其后的腕部也一起移动。固定连接的含义是两个连杆之间没有相对运动；父连杆移动时，子连杆仍会跟随。
启元 Q1 左臂的关节与姿态变化。基于官方 q1_v3_full_range.xml，展示左臂位置、左肘局部转轴、0 rad 与 1 rad 的姿态对比，以及下游固定连接的随动关系。使用 MuJoCo 3.3.7 渲染，仅作模型姿态可视化。
同一条前臂为什么需要两种形状
继续读 left_elbow_link，会看到 visual 和 collision 两类描述。visual 负责画面里看得见的外形；collision 提供碰撞计算使用的几何形状。两者可以相同，也可以各自采用不同的模型。
Q1 这段前臂的 visual 引用了 STL 网格文件，collision 则用两段圆柱体近似。圆柱当然画不出外壳细节，但碰撞检测不必逐一处理这些细节。官方 ROS 教程也介绍了用简单几何体替代复杂网格的做法，目的之一就是减轻碰撞计算负担。
同一姿态下分别显示外观几何和碰撞几何，取自配套 MuJoCo模型的本地渲染。右图中较粗的几何体用于说明碰撞表示；
这个区别对开发很实际。假设给机器人加了一块装饰板，只改 visual 会让画面显示新外形，碰撞检测却仍使用原来的几何描述。涉及运动规划时，需要检查新增部件是否也进入碰撞模型。外观和碰撞几何表达不同用途，修改时要分别核对。
link 里面还可以有 inertial，包括质量、质心位置和转动惯量。转动惯量描述质量分布对转动的影响，例如把同样重的物体握在手边或举到手臂末端，转动时的感受会不同。模型载入成功，只说明软件能解释这些参数；参数是否足够贴近真机，还需要另外验证。
不接机器人也能复核这些结果
如果想亲自确认，不必先安装 ROS。下面的核验只读文件，不连接机器人；脚本版本为 1.0.0，实测环境为 macOS 26.5.1、Apple Silicon、CPython 3.12.14，使用 Python 标准库，无额外依赖。
按图 1 从启元机器人官方资料下载页下载“Q1 URDF v1.0.0”，解压后保留 q1_v3 目录。里面的 meshes、urdf、xml 文件夹应保持相对位置，不能只拷贝一个 .urdf 文件。
从配套 AtomGit 仓库 v1.0.0下载 inspect_q1.py，放在 q1_v3 文件夹旁边。这是本文自建的科普示例仓库，区别于启元官方 q1-urdf 模型仓库。脚本读取主 URDF，以及 xml 目录中的两份模型文件。
在这个目录打开终端，执行下面的命令。Windows 可将 python3 换成已配置的 Python 启动命令；本文实际执行记录来自 macOS。
python3 inspect_q1.py q1_v3--reportq1_report本次实际输出的关键两行是：
links=26 joints=25 revolute=22 fixed=3 left_elbow_joint: -0.87266 to 1.6581 rad脚本还会生成 q1_report.html 和 q1_report.json。双击 HTML 文件，可以看到关节计数、左肘限位和原始 URDF 的 SHA-256 校验值。校验值用于确认是不是同一份文件；
inspect_q1.py 1.0.0 生成的 HTML 报告。除了关节计数，还可以比较主 URDF 与两份 XML的左肘限位，并核对文件校验值。
也可以完全不用脚本：用文本编辑器打开 urdf/q1_v3.urdf，搜索 left_elbow_joint，再依次查看 parent、child、axis 和 limit。接着搜索 left_wrist_yaw_joint，会发现它的 type 是 fixed。即使附近仍写着 limit 数值，也不应据此把它算成可活动关节。先看类型，再解释其他字段，这一步比记住标签总数更有用。
用 grep 直接检索同一份官方 q1_v3.urdf 的实际输出。上半部分能看到左肘的 revolute类型、父子连杆、转轴和限位；下半部分显示腕部连接虽保留了 limit 字段，类型仍是 fixed。图中命令只是读取文件。
只改变左肘角度的两种Q1模型姿态可视化也可以继续复现。render_figures.py 会输出配图和 JSON 日志，其中 physics_steps 为 0，表示这次只做正向计算与渲染。
运行 render_figures.py 后的输出。model_file 指明加载的 XML 文件，elbow_angles_rad列出两次渲染使用的左肘角度；physics_steps=0，没有推进物理仿真。
如果想在窗口里转动视角、观察模型，可以使用 MuJoCo 自带的查看器。先从本文 AtomGit 仓库 article-v3 版本下载 view_q1.py，放在 q1_v3 旁边。下面是本次 macOS 环境的启动方法，查看器脚本版本为 1.0.0：
python3-mvenv .venv .venv/bin/python-mpipinstallmujoco==3.3.7 .venv/bin/mjpython view_q1.py q1_v3--elbow1macOS 上用 mjpython 启动，是 MuJoCo 官方对被动查看器的要求。脚本加载 xml/q1_v3_full_range.xml，将左肘设置为 1 rad，再打开模型窗口。拖动视角可以查看前臂与身体的位置关系；
MuJoCo 3.3.7 查看器中的 Q1。窗口左上角列出所用文件 q1_v3_full_range.xml、左肘角度 1.0 rad和物理步数 0。模型来自启元机器人官方 Q1 URDF 资料包。
模型描述身体 控制器决定怎样运动
读到这里，已经能回答几个具体问题：左肘连着谁，绕哪条轴转，文件允许它转多大，以及碰撞检测看到的前臂是什么形状。但“让 Q1 稳定地抬手”还没有完成。
URDF 提供身体结构与参数。控制器还需要根据目标、当前状态和约束，计算怎样驱动机器人。仿真软件加载模型之后，也仍需设置环境和控制逻辑；把一个关节角度改成 1 rad，并不能证明真机能够以某种速度、精度完成同样的动作。
我在这次核验中最想保留下来的提醒，是模型文件的具体写法：名字带 wrist 的连接可能是 fixed，同一个左肘在不同文件里的限位也可能不同。读清这些细节，再去看动作规划、仿真和真机接口，许多概念才有明确的对象。
本文中的模型来自启元机器人官方开源项目。进一步了解 Q1 模型、SDK 和开发资料，可访问启元机器人开发者社区，并从启元机器人 AtomGit 开源组织查看相关项目。
资料来源与复核范围
启元开发者社区资料下载页，Q1 URDF v1.0.0。下载包 SHA-256 为 332a629e51fa7559e0cb16acb7276d600cb990102934e26861f80ccaa1443fb0。
ROS 官方 urdfdom 项目，URDF 的模型元素和关节类型说明。
启元官方 q1-urdf 固定版本，提交 562b764a18613d459140ed9b255fa30434e346ef。本文主 URDF 与下载包对应文件逐字节相同；统计和限位读取均以该文件为准。
ROS 官方 Joint 定义，父子连杆、关节坐标系与轴的语义。角度单位另参见 ROS 官方可动模型教程。
ROS 官方碰撞与物理属性教程，visual、collision 和 inertial 的用途。
MuJoCo 3.3.7 官方 Python 文档。配图仅使用模型加载、正向计算与渲染，不包含动态控制实验。
