简介：DH2URDF 是一份将 Denavit-Hartenberg 参数表转换为统一机器人描述格式（URDF）的 JavaScript 工具资源，面向机器人建模、运动学仿真与 ROS 学习方向的开发者及学生。它解决的是手工编写 URDF 繁琐、易错的问题：只需提供 DH 参数，即可自动生成对应 URDF 结构，并把转换后的坐标轴以 URDF 圆柱体形式放置在 DH 参考系上，便于进一步搭建完整机器人模型。压缩包共 9 个文件，约 138KB，包含 4 个 js 脚本、1 个 html 演示页、1 个 urdf 示例、1 个 litcoffee 源码及 license、md 说明等，核心转换逻辑与网页演示相互配合，另附数学与模板辅助脚本。配套演示网站支持查看生成的 URDF 并调整关节值，方便直观验证转换结果。目前已有 1049 人学习下载，适合希望快速打通 DH 建模到 URDF 输出流程、减少重复手写工作的读者参考使用。

1. DH2URDF：为什么机器人建模的最后一公里总是卡在格式转换上

做过机器人仿真的人都遇到过这个场景：机械臂的 DH 参数表在论文或手册里写得清清楚楚，四个参数一列，看起来干净利落。但当你把这张表丢进仿真环境时，发现它根本不认——仿真器要的是 URDF，一种基于 XML 的树状描述格式，里面全是 link、joint、origin、axis 这些标签。于是你开始手动换算，一个关节一个关节地填，填到第三个关节时发现姿态角符号搞反了，整条臂在 RViz 里扭成了麻花。

这不是个别现象。DH 参数和 URDF 之间的转换，看起来只是数学等价变换，实际上藏着一堆约定差异：DH 表的坐标系定义有标准 DH 和改进 DH 两套体系，URDF 的 joint origin 是相对父 link 的位姿，而 DH 参数描述的是相邻关节轴之间的几何关系。两者的“参考系”根本不在同一个层面上。DH2URDF 这个工具要解决的，就是把这件事从手工换算变成可复现的自动映射。它用 JavaScript 实现，意味着你可以在浏览器里直接跑，不需要装 ROS 环境就能完成转换。对于经常需要把论文里的 DH 表快速变成可仿真模型的人来说，这个转换链路的打通，比想象中更值得搞懂。

2. DH 参数与 URDF 的语义鸿沟：为什么不能直接对应

2.1 DH 表的四参数到底描述了什么

标准 DH 参数用四个量描述相邻两个关节坐标系之间的关系：连杆长度 a、连杆扭角 α、关节偏移 d、关节转角 θ。这四个参数的排列顺序和旋转平移顺序是有严格约定的——标准 DH 是先绕 Z 轴转 θ，再沿 Z 轴移 d，然后沿 X 轴移 a，最后绕 X 轴转 α。改进 DH 则把顺序调整为先绕 X 轴转 α，再沿 X 轴移 a，然后绕 Z 轴转 θ，最后沿 Z 轴移 d。

这个顺序差异不是学术洁癖，它直接决定了坐标系原点落在哪里。标准 DH 把坐标系原点放在关节轴上，改进 DH 把原点放在连杆的一端。如果你拿到的 DH 表没有标明用的是哪套约定，转换结果大概率是错的。常见的实现思路是：在转换前先确认 DH 表的约定类型，然后在代码里用不同的变换矩阵构造顺序来区分。

2.2 URDF 的 joint origin 是另一套语言

URDF 里每个 joint 有一个 origin 标签，包含 xyz 和 rpy 两个属性。xyz 是子坐标系原点在父坐标系中的位置，rpy 是子坐标系相对父坐标系的旋转，用 roll-pitch-yaw 表示。注意这里的旋转是“从父到子”的被动变换，而 DH 参数描述的是“从当前关节到下一个关节”的主动变换链。

更麻烦的是，URDF 的 link 坐标系默认与 joint 坐标系重合，而 DH 表的坐标系定义往往把 Z 轴对齐关节轴、X 轴对齐公垂线。这意味着你不能简单地把 DH 的四个参数塞进 origin 的六个自由度里，中间需要做一次坐标系对齐：先把 DH 变换矩阵算出来，再从矩阵反解出 xyz 和 rpy。反解过程中，欧拉角的顺序和符号约定又容易翻车。

2.3 转换的核心：从变换矩阵到 URDF 位姿

假设你已经确认了 DH 约定类型，下一步是构造相邻关节的齐次变换矩阵。以标准 DH 为例，第 i 个关节到第 i+1 个关节的变换可以写成四个基本变换的乘积：

// 标准 DH 变换矩阵构造 // theta: 关节转角, d: 连杆偏移, a: 连杆长度, alpha: 连杆扭角 function standardDHTransform(theta, d, a, alpha) { const ct = Math.cos(theta), st = Math.sin(theta); const ca = Math.cos(alpha), sa = Math.sin(alpha); // 返回 4x4 齐次变换矩阵 return [ [ct, -st * ca, st * sa, a * ct], [st, ct * ca, -ct * sa, a * st], [0, sa, ca, d ], [0, 0, 0, 1 ] ]; }

这个矩阵的几何含义是：先绕当前 Z 轴旋转 θ，再沿 Z 轴平移 d，然后沿 X 轴平移 a，最后绕 X 轴旋转 α。矩阵的左上 3x3 是旋转部分，右上 3x1 是平移部分。拿到这个矩阵后，URDF 的 origin 需要的是父 link 到子 link 的位姿，而 DH 矩阵描述的是关节 i 到关节 i+1 的变换。如果 URDF 的 link 坐标系与 DH 坐标系重合，那么直接把矩阵的平移部分作为 xyz，旋转部分转成 rpy 即可。

但实际情况往往更复杂：URDF 的 base link 和 tool link 需要额外处理，有些关节是旋转关节（revolute），有些是移动关节（prismatic），DH 表里的 θ 和 d 哪个是变量取决于关节类型。转换代码里必须根据关节类型决定哪个参数是常量、哪个是变量。

2.4 旋转矩阵转 RPY 的数值陷阱

从旋转矩阵反解 roll-pitch-yaw 时，有一个经典陷阱：当 pitch 角接近 ±90° 时，roll 和 yaw 的解不唯一，会出现万向节锁。常见的处理方式是用atan2函数并判断奇异条件：

// 旋转矩阵转 RPY (ZYX 顺序) function rotationMatrixToRPY(R) { let roll, pitch, yaw; const epsilon = 1e-6; // 判断是否接近奇异位置 if (Math.abs(R[2][0]) > 1 - epsilon) { // 万向节锁：pitch = ±90度 pitch = Math.sign(-R[2][0]) * Math.PI / 2; roll = 0; yaw = Math.atan2(-R[0][1], R[1][1]); } else { pitch = Math.asin(-R[2][0]); roll = Math.atan2(R[2][1], R[2][2]); yaw = Math.atan2(R[1][0], R[0][0]); } return [roll, pitch, yaw]; }

这段代码里R[2][0]对应的是旋转矩阵第三行第一列，在 ZYX 欧拉角约定下它等于 -sin(pitch)。当它接近 ±1 时，pitch 接近 ±90°，此时 roll 和 yaw 耦合在一起，只能任意取一个值。URDF 解析器通常能处理这种情况，但如果你手动填参数，这里就是最容易翻车的地方。DH2URDF 在实现时应该对奇异位置做了特殊处理，否则生成的 URDF 在某些构型下会出现姿态跳变。

3. 从 DH 表到 URDF 文件：转换流程的工程实现

3.1 输入解析：DH 表的格式与约定识别

DH2URDF 的输入是一张 DH 参数表，通常以数组或 CSV 形式给出。每一行包含四个参数，外加关节类型和关节限位。转换的第一步是识别约定类型：标准 DH 还是改进 DH。有些实现会让用户显式指定，有些则通过参数排列特征自动判断。一个可靠的工程做法是：在输入结构里加一个convention字段，默认值为standard，用户可切换为modified。

输入解析还需要处理单位问题。DH 表里的角度可能是度或弧度，长度可能是米或毫米。URDF 内部统一用弧度和米，所以解析阶段必须做单位归一化。常见的做法是在参数表里加一列unit，或者在转换配置里指定全局单位。如果这一步漏了，生成的 URDF 在仿真器里要么尺寸差 1000 倍，要么关节转一圈只动了 1 度。

3.2 逐关节变换：从基座到末端

转换的核心循环是遍历 DH 表的每一行，计算相邻坐标系之间的变换矩阵，然后累积成从基座到当前关节的全局位姿。这里有一个容易混淆的点：URDF 的 joint origin 是相对父 link 的，而 DH 变换是相对前一个关节坐标系的。如果 URDF 的 link 坐标系与 DH 坐标系一一对应，那么每个 joint 的 origin 就是当前 DH 变换矩阵反解出的位姿。

但 URDF 的树状结构要求每个 link 只能有一个父 joint。对于串联机械臂，这自然满足；对于带分支的结构（比如带夹爪的臂），就需要在 DH 表里标明分支点。DH2URDF 的输入格式里应该支持一个parent字段，用来指定当前关节的父 link 名称。如果没有这个字段，默认按顺序串联。

// 逐关节生成 URDF joint 定义 function generateJoint(dhRow, parentLink, childLink, convention) { const { theta, d, a, alpha, type } = dhRow; // 根据约定类型选择变换矩阵构造方式 const T = convention === 'standard' ? standardDHTransform(theta, d, a, alpha) : modifiedDHTransform(theta, d, a, alpha); // 提取平移和旋转 const xyz = [T[0][3], T[1][3], T[2][3]]; const rpy = rotationMatrixToRPY([ [T[0][0], T[0][1], T[0][2]], [T[1][0], T[1][1], T[1][2]], [T[2][0], T[2][1], T[2][2]] ]); // 根据关节类型决定 axis 和 limit const axis = type === 'revolute' ? [0, 0, 1] : [0, 0, 1]; const limit = type === 'revolute' ? { lower: -Math.PI, upper: Math.PI, effort: 100, velocity: 1 } : { lower: -0.5, upper: 0.5, effort: 100, velocity: 0.1 }; return { parentLink, childLink, xyz, rpy, axis, limit, type }; }

这段代码里，xyz和rpy直接来自变换矩阵的分解。axis对于旋转关节通常是 Z 轴，因为 DH 约定里关节轴就是 Z 轴。limit是关节限位，旋转关节默认 ±180°，移动关节默认 ±0.5 米。这些默认值在实际使用中需要根据机械臂规格调整，但作为转换工具的初始输出是合理的。

3.3 URDF 序列化：XML 结构与 link 命名

拿到所有 joint 的数据后，下一步是生成 URDF 的 XML 结构。URDF 的基本骨架是<robot>根节点，下面包含若干<link>和<joint>。每个 joint 必须引用父 link 和子 link 的名称，所以转换过程中需要维护一个 link 命名规则。常见的做法是用link_0、link_1这样的序号命名，或者用base_link、joint1_link这样的语义命名。

序列化时要注意 XML 转义：如果 link 名称里包含特殊字符，需要转义。另外，URDF 支持<material>标签给 link 上色，转换工具可以选择性地生成默认材质，方便在 RViz 里区分不同连杆。惯性矩阵<inertial>是可选的，但如果要做动力学仿真，必须提供质量和转动惯量。DH2URDF 如果只做运动学转换，可以省略 inertial，但生成的 URDF 在 Gazebo 里会报缺少惯性参数的警告。

// 生成 URDF XML 字符串 function serializeURDF(robotName, links, joints) { let xml = `<?xml version="1.0"?>\n<robot name="${robotName}">\n`; // 生成 link 定义 for (const link of links) { xml += ` <link name="${link.name}">\n`; if (link.mass) { xml += ` <inertial>\n`; xml += ` <mass value="${link.mass}"/>\n`; xml += ` <inertia ixx="${link.ixx}" ixy="0" ixz="0"`; xml += ` iyy="${link.iyy}" iyz="0" izz="${link.izz}"/>\n`; xml += ` </inertial>\n`; } xml += ` </link>\n`; } // 生成 joint 定义 for (const joint of joints) { xml += ` <joint name="${joint.name}" type="${joint.type}">\n`; xml += ` <parent link="${joint.parentLink}"/>\n`; xml += ` <child link="${joint.childLink}"/>\n`; xml += ` <origin xyz="${joint.xyz.join(' ')}"`; xml += ` rpy="${joint.rpy.join(' ')}"/>\n`; xml += ` <axis xyz="${joint.axis.join(' ')}"/>\n`; xml += ` <limit lower="${joint.limit.lower}"`; xml += ` upper="${joint.limit.upper}"`; xml += ` effort="${joint.limit.effort}"`; xml += ` velocity="${joint.limit.velocity}"/>\n`; xml += ` </joint>\n`; } xml += `</robot>`; return xml; }

这段序列化代码生成的 URDF 可以直接被 ROS 的robot_state_publisher和 RViz 加载。注意<origin>的xyz和rpy属性值用空格分隔，这是 URDF 规范要求的格式。<limit>标签对于 revolute 和 prismatic 关节是必需的，continuous 关节可以省略。

3.4 验证转换结果：用正运动学校验末端位姿

生成 URDF 后，怎么确认转换是对的？最直接的方法是用正运动学算一遍末端位姿，和 DH 表直接算出来的结果对比。如果两者一致，说明转换正确；如果有偏差，说明某个关节的 origin 或 axis 搞错了。

验证时可以用一个简单的测试构型：把所有关节角设为 0，计算末端位置。然后再把所有关节角设为某个非零值，再算一次。两次结果都和 DH 正运动学的结果对比。常见的实现思路是在转换工具里内置一个verify函数，输入 DH 表和生成的 URDF，输出位姿误差。如果误差在数值精度范围内（比如 1e-6），就认为转换成功。

这个验证步骤在手工转换时经常被忽略，但它是区分“看起来对”和“确实对”的关键。很多转换错误在零位时看不出来，一旦关节转动就暴露了。

4. 避坑指南：DH 转 URDF 时最容易翻车的几个地方

4.1 现象：RViz 里机械臂扭成麻花，关节轴方向全乱

原因：DH 约定类型搞反了。标准 DH 和改进 DH 的变换顺序不同，如果输入表是改进 DH 但代码按标准 DH 处理，每个关节的旋转轴都会偏 90°。解决：在转换前确认 DH 表的约定类型，如果不确定，用零位和 90° 两个构型分别验证，看哪个约定下末端位姿和预期一致。

4.2 现象：URDF 加载成功但关节转不动，或者转动方向相反

原因：<axis>标签的轴向搞错了。DH 约定里关节轴是 Z 轴，但 URDF 的 joint axis 是相对 joint 坐标系的。如果 origin 的 rpy 已经把坐标系转过了，axis 可能不再是 [0,0,1]。解决：在生成 joint 时，axis 应该始终设为 [0,0,1]，因为 DH 变换已经把关节轴对齐到了 Z 轴。如果发现方向相反，检查 DH 参数的符号约定。

4.3 现象：末端位置差了一个固定偏移，所有关节角下都偏

原因：基座坐标系和第一个关节坐标系之间的变换漏了。DH 表通常从第一个关节开始描述，但 URDF 需要一个 base link 到第一个 joint 的固定变换。如果这个变换没加，整个臂会偏移一个连杆长度。解决：在 DH 表前面加一行“基座到关节 1”的虚拟 DH 参数，或者在生成 URDF 时手动插入一个 fixed joint。

4.4 现象：角度单位搞混，关节转 1 弧度实际转了 57.3 度

原因：DH 表里的角度是度，但代码按弧度处理。解决：在输入解析阶段统一转成弧度。如果 DH 表里角度列的值普遍在 0-360 之间，大概率是度；如果在 0-6.28 之间，大概率是弧度。不确定时加一个angleUnit配置项。

4.5 现象：生成的 URDF 在 Gazebo 里抖动或飞走

原因：缺少惯性参数或惯性矩阵不正定。Gazebo 做动力学仿真时需要每个 link 的质量和转动惯量。如果转换工具只输出运动学结构，Gazebo 会用默认值，可能导致数值不稳定。解决：在 DH 表里补充质量和惯量信息，或者在 URDF 里给每个 link 加一个合理的默认惯性。惯量矩阵必须满足三角不等式，否则物理引擎会报错。

5. 转换工具的边界与取舍：什么时候该用 DH2URDF，什么时候不该用

DH2URDF 这类工具的价值在于把重复的手工换算自动化，但它不是万能的。它的适用边界很清晰：输入必须是结构化的 DH 参数表，输出是运动学层面的 URDF。如果你的机器人模型来自 CAD 导出，或者关节关系不是标准串联结构，DH 表本身就不容易列出来，这时候直接用 CAD 转 URDF 的工具更合适。

另一个取舍点是精度和可读性的平衡。自动生成的 URDF 里，origin 的 xyz 和 rpy 是一串浮点数，可读性差，但精度高。手工调整过的 URDF 可能把一些固定变换合并简化了，可读性好，但改一个参数可能影响多个关节。DH2URDF 选择的是前者：保持每个关节的独立变换，不做过多的代数化简。这样生成的 URDF 虽然看起来冗长，但每个 joint 的 origin 都能追溯到 DH 表里的对应行，调试时容易定位问题。

还有一个容易被忽略的点：DH 参数本身对机械臂的几何描述是不唯一的。同一台机械臂可以有多组等效的 DH 参数，取决于坐标系原点的选择。这意味着 DH2URDF 的输出也不是唯一的。如果你拿到的 URDF 和别人的不一样，不一定是谁错了，可能只是 DH 表的约定不同。理解这一点，就不会在“为什么我的 URDF 和参考模型对不上”这个问题上纠结太久。

我自己的习惯是：每次用 DH2URDF 生成 URDF 后，先跑一遍正运动学校验，确认零位和几个随机构型下的末端位姿误差在 1e-6 以内，再丢进仿真环境。这个习惯帮我省掉了无数次在 RViz 里对着扭成麻花的机械臂发呆的时间。希望帮到你。

本文还有配套的精品资源，点击获取