text-to-cad 机器人网格准备指南：URDF 链接 Mesh 导出与引用工作流完整解析-平芜编程栈

text-to-cad 机器人网格准备指南：URDF 链接 Mesh 导出与引用工作流完整解析

【免费下载链接】text-to-cadA library of agent skills for CAD, CAE and CAM项目地址: https://gitcode.com/GitHub_Trending/tex/text-to-cad

text-to-cad 是一个面向 AI Agent 的 CAD、CAE 与 CAM 技能库，它的 URDF 技能可以帮你规范地完成机器人描述文件（.urdf）的编写——而其中最容易翻车的一步，就是机器人 mesh（网格）的准备与引用。本指南带你走通完整流程：按链接拆分 CAD 模型、在正确的坐标系下导出 mesh、处理毫米到米的单位换算、写出可被校验器验证的 mesh 引用，最后用内置校验脚本和 CAD Viewer 完成验收。

为什么 mesh 准备是 URDF 的第一步？

在 URDF 的世界里，一个机器人由多个link（链接）和joint（关节）组成，每个物理 link 通常需要三类几何数据：visual（显示）、collision（碰撞）、inertial（惯性）。其中 visual 和 collision 常常引用外部 mesh 文件。

官方工作流明确指出：坏掉的 mesh 处理是 URDF 失败的头号原因，而且它几乎总是发生在写任何 XML 之前——源 CAD 被错误地拆分、在错误的坐标系下导出、或者以错误的比例被引用。所以正确的顺序永远是：

✅ 先准备好 mesh 资产 → 再编写与之匹配的 URDF XML ❌ 反过来写 XML，再用 origin 偏移去"凑"，是典型的错误做法

这一点在 skills/urdf/references/meshes.md 中有完整说明。

第一步：按链接（Link）拆分源 CAD

导出单位是link，而不是整个装配体，也不是 CAD 特征树。核心规则如下：

规则	说明
一个 link 一个文件	每个有几何的 link 恰好一个视觉资产，文件以 link 命名，如`3MF/forearm_link.3mf`
禁止"一鱼多吃"	多个 link 绝不能共用一个合并装配 mesh 再用补偿 origin 硬凑；两个 link 共享同一实体时，必须先在 CAD 中沿关节切开
刚性连接要合并	属于同一 link 的刚性部件，合并进该 link 的单个导出文件中
拆分归 CAD 管	拆分、重定坐标系、导出属于 CAD 工作流（`$cad`、`$step-parts`技能）的职责，不要用改 URDF origin 的方式去修复错误的拆分

在正式导出前，先从设计台账（design ledger）中列全所有 link。台账是写在.urdf文件头部注释块里的"空间模型说明书"，格式定义在 skills/urdf/references/design-ledger.md。

第二步：在链接自身坐标系下导出 mesh

这是最容易出错的一步，规则只有一条：每个 link 的 mesh 必须以该 link 自己的坐标系导出——即台账中定义的坐标系，且在关节处于零位时与父关节坐标系重合。

做到位后，URDF 里每个<visual><origin>都是恒等变换（0 0 0, 0 0 0）。这是仓库内置夹具（fixtures）采用的约定，也是最容易被审计的状态。

少数情况确实无法重定坐标系（供应商 mesh、扫描件）时，允许使用非零的 visual origin，但必须记入台账并注明来源——它是每个 link 的固定常数，不是调试旋钮。

第三步：单位与 scale——毫米到米的换算

URDF 的长度单位是米，而 mesh 文件常常是毫米，且 STL 格式本身不携带任何单位元数据。这意味着单位只能靠引用时显式声明。

正确做法是在每一个mesh 引用上用scale属性写出换算：

<mesh filename="3MF/forearm_link.3mf" scale="0.001 0.001 0.001" />

毫米源 →scale="0.001 0.001 0.001"
只有当 mesh 真的以米为单位建模时，才可以省略scale
一个机器人只用一套单位约定，混用毫米/米的例外必须逐条记入台账

💡 快速自检：如果在查看器里机器人渲染大了或小了约 1000 倍，这是scale属性 bug——改 scale，而不是去改关节 origin。

第四步：在 URDF 中引用 mesh 的两种形式

引用形式	适用场景	校验器行为
本地相对路径（如`3MF/forearm_link.3mf`）	仓库内的机器人模型，推荐	会验证文件相对`.urdf`所在目录真实存在
`package://名称/路径`URI	面向 ROS 包用户的机器人	只检查语法，并警告"解析结果取决于使用环境"

引用形式的细节见 skills/urdf/references/meshes.md 的 "Reference Forms" 一节。两条实践建议：

mesh 文件与.urdf放在同一模型目录树下（仓库政策：都放在models/下），让文件与资产一起移动；
相对路径相对于.urdf文件所在目录解析，写完后务必用校验器确认路径可达。

编写完整的链接结构（inertial→visual→collision的顺序、命名规范、关节元素顺序）时，参照 skills/urdf/references/authoring-contract.md，其中还附有一个可直接套用的"黄金骨架"示例（含设计台账注释块）。

第五步：区分 visual mesh 与 collision mesh

同样是引用 mesh，用途完全不同：

Visual mesh：为显示服务，保留完整细节，格式支持时保留颜色；
Collision 几何：为物理仿真与规划服务，优先用简化体（box、cylinder、sphere，按包围体尺寸设置），或者一个粗糙但封闭的碰撞 mesh；
⚠️ 把 visual mesh 直接当 collision 用只是加载和冒烟测试时的临时兜底——凹面视觉 mesh 会让物理引擎变慢甚至不稳定。

另外注意：collision 的 origin 以 link 坐标系表达，与 visual origin相互独立。

验收：用 scripts/validate 跑通校验 + Viewer 扫查

mesh 和 XML 都就绪后，URDF 技能规定了固定的验收顺序（完整配方见 skills/urdf/references/validation.md）：

python scripts/validate path/to/robot.urdf

常用选项：

--strict：把警告也当作失败处理；
--format json：输出机器可读的检查结果；
--package NAME=PATH：解析package://mesh URI。

针对 mesh 的内置检查包括：本地路径必须能解析到真实文件、scale值必须非零且有限（负 scale 会翻转 mesh 并触发警告）、不常见的扩展名会收到警告等。

完整验证流程是四步走，按顺序执行、失败即停：

内置校验器（必跑）：修到零发现为止；
外部工具（如已安装check_urdf）：用 ROS 参考解析器解析并打印链接树；
Viewer 扫查：在 CAD Viewer 中加载文件，确认 mesh 的比例和位姿正常，然后逐一扫过每个可动关节的极限位置——这是唯一能抓出"轴向符号反了"的步骤；
使用端冒烟测试：RViz、robot_state_publisher、Gazebo/Ignition 或 MoveIt 加载。

最后提醒一句官方校验器的边界：校验通过 ≠ 空间正确。URDF 可以通过所有结构检查，却把关节放在错误的位置——这正是设计台账和 Viewer 扫查存在的意义。报告结论时，请明确列出哪些空间数据未能独立验证。

常见 mesh 坑位速查表

症状	根因	修复
机器人在查看器中放大/缩小约 1000 倍	`scale`缺失或写错	改`scale`属性，别动关节 origin
快照/渲染报 "No link mesh loaded"	mesh 未就位（如 Git LFS 指针未检出）	先运行`git lfs checkout <mesh目录>`
多个链接叠在一起	一个合并 mesh 被多个 link 引用	回到 CAD 沿关节重新拆分
关节运动时 mesh 跟着错位	试图用 visual origin 补偿运动学错误	修正 link/joint 坐标系，除非 mesh 确实有物理偏移
校验器报路径不存在	相对路径解析目录理解错误	相对路径以`.urdf`所在目录为基准

快速上手：安装 text-to-cad 技能库

整个技能库通过 Skills CLI 一条命令安装即可，无需手动 clone 仓库：

npx skills install earthtojake/text-to-cad

之后在你的 Agent 中按任务触发对应技能即可：

$cad：拆分/导出 STEP、STL、3MF、GLB 等链接资产（mesh 的所有者）；
$urdf：编写.urdf、处理引用与 scale、跑校验与快照；
$cad-viewer：本地浏览器预览，扫查每个关节的实际运动；
$srdf：在 URDF 之上添加 MoveIt 规划组、末端执行器等语义。

各技能的入口文档分别在 skills/cad/SKILL.md、skills/urdf/SKILL.md、skills/cad-viewer/SKILL.md 和 skills/srdf/SKILL.md，mesh 与编辑循环的操作细则则集中在 skills/urdf/references/urdf-workflow.md。