urdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

URDF

Use this skill for URDF robot-description outputs. Treat URDF work as constrained kinematic modeling, not just XML writing. The main correctness risks are frame placement, joint-axis semantics, unit consistency, mesh scale, inertial data, and generated-artifact drift.

本技能适用于URDF机器人描述输出。请将URDF相关工作视为受约束的运动学建模，而非单纯的XML编写。主要的正确性风险包括坐标系放置、关节轴语义、单位一致性、网格缩放、惯性数据以及生成工件的偏差。

Core Rules

核心规则

Treat the Python source that defines
```
gen_urdf()
```
as the source of truth. Treat configured
```
.urdf
```
files as generated artifacts.
Generate only explicit URDF targets. Do not regenerate unrelated CAD, mesh, render, SRDF, SDF, or simulator artifacts from this skill.
The
```
scripts/urdf
```
generator validates generated URDFs by default. Do not use or document a separate
```
validate
```
command.
Before writing or changing URDF XML, establish the robot's frame, joint, geometry, unit, and assumption ledger. See
```
references/design-ledger.md
```
.
Use URDF frame semantics exactly. Joint origins, link frames, joint axes, and visual/collision/inertial origins use different reference frames. See
```
references/frame-semantics.md
```
.
Do not infer spatial transforms, mesh units, handedness, axes, or joint signs from vague prose. Use CAD transforms, dimensioned drawings, measured values, existing source data, or explicit documented assumptions.
Prefer simple, auditable generator code over clever XML construction. Keep constants named by physical meaning, not by arbitrary numbers.
For physical links, model
```
inertial
```
,
```
visual
```
, and
```
collision
```
separately when the target consumer needs them. Frame-only links may intentionally omit mass and geometry.

将定义
```
gen_urdf()
```
的Python源码视为可信源。将配置后的
```
.urdf
```
文件视为生成工件。
仅生成明确的URDF目标。请勿通过本技能重新生成无关的CAD、网格、渲染、SRDF、SDF或模拟器工件。
```
scripts/urdf
```
生成器默认会验证生成的URDF。请勿使用或单独记录
```
validate
```
命令。
在编写或修改URDF XML之前，建立机器人的坐标系、关节、几何、单位及假设台账。请参阅
```
references/design-ledger.md
```
。
严格遵循URDF坐标系语义。关节原点、连杆坐标系、关节轴以及视觉/碰撞/惯性原点使用不同的参考坐标系。请参阅
```
references/frame-semantics.md
```
。
请勿从模糊描述中推断空间变换、网格单位、坐标系旋向、轴方向或关节符号。请使用CAD变换、标注图纸、测量值、现有源数据或明确记录的假设。
优先选择简单、可审计的生成器代码，而非复杂的XML构造。请根据物理意义命名常量，而非使用任意数字。
对于物理连杆，当目标使用者需要时，请分别建模
```
inertial
```
、
```
visual
```
和
```
collision
```
。仅含坐标系的连杆可有意省略质量和几何参数。

Workflow

工作流程

Identify the
```
gen_urdf()
```
Python source and target
```
.urdf
```
output.
Identify target consumers: RViz, robot_state_publisher, Gazebo/Ignition, MoveIt, a real robot driver, or another simulator.
Read or create the design ledger before editing frames, origins, axes, mesh scale, limits, or inertials.
Edit the generator source, not generated URDF XML.
Regenerate only explicit targets with
```
scripts/urdf
```
.
Let generation-time validation fail fast on XML, graph, joint, geometry, mesh-reference, and inertial problems.
When geometry or mesh references depend on changed CAD or exported mesh outputs, regenerate those explicit artifacts with the owning CAD or mesh workflow, then regenerate the affected URDF target.
After creating or modifying a
```
.urdf
```
, always hand the explicit generated path to
```
$render
```
when available;
```
$render
```
checks/reuses a live viewer and returns a link.
For visual feedback during generation review, prefer
```
$render
```
snapshots over opening the viewer manually or using Playwright. Use still snapshots only; URDF review should not generate GIFs.
When available, run a consumer smoke test appropriate to the target: RViz display, robot_state_publisher tree, Gazebo/Ignition loading, or MoveIt model loading.
Report remaining assumptions, unchecked spatial data, skipped
```
$render
```
handoff/viewer checks, and validation/smoke-test gaps.

确定
```
gen_urdf()
```
Python源码及目标
```
.urdf
```
输出文件。
确定目标使用者：RViz、robot_state_publisher、Gazebo/Ignition、MoveIt、真实机器人驱动器或其他模拟器。
在编辑坐标系、原点、轴、网格缩放、限位或惯性参数之前，阅读或创建设计台账。
编辑生成器源码，而非生成的URDF XML。
仅使用
```
scripts/urdf
```
重新生成明确的目标。
让生成时验证在XML、图结构、关节、几何、网格引用及惯性问题上快速失败。
当几何或网格引用依赖于已修改的CAD或导出的网格输出时，请通过所属的CAD或网格工作流程重新生成这些明确的工件，然后重新生成受影响的URDF目标。
创建或修改
```
.urdf
```
后，若
```
$render
```
可用，请始终将生成的明确路径传递给它；
```
$render
```
会检查/复用实时查看器并返回链接。
生成审查期间如需视觉反馈，优先使用
```
$render
```
快照，而非手动打开查看器或使用Playwright。仅使用静态快照；URDF审查不应生成GIF。
若可用，请运行适合目标使用者的冒烟测试：RViz显示、robot_state_publisher树、Gazebo/Ignition加载或MoveIt模型加载。
报告剩余的假设、未检查的空间数据、跳过的
```
$render
```
交接/查看器检查以及验证/冒烟测试的缺口。

Commands

命令

Run with the Python environment for the project or workspace. The URDF generator and lightweight validator use only the Python standard library; downstream consumers such as RViz, Gazebo, or MoveIt may need their own runtime packages.

From this skill directory, the launcher shape is:

bash

python scripts/urdf path/to/source.py
python scripts/urdf path/to/source.py -o path/to/robot.urdf
python scripts/urdf path/to/a.py=out/a.urdf path/to/b.py=out/b.urdf

Plain Python targets write a sibling

.urdf

beside the source.

-o

--output

is valid only with one plain target. Use

SOURCE.py=OUTPUT.urdf

pairs for custom multi-target destinations.

Relative source targets and CLI output overrides are resolved from the current working directory. When running from outside this skill directory, prefix the launcher path so target files still resolve from the intended workspace.

The launcher executes only

gen_urdf()

and validates the generated URDF output. It does not provide a separate validation-only command.

在项目或工作区的Python环境中运行。URDF生成器和轻量验证器仅使用Python标准库；下游使用者如RViz、Gazebo或MoveIt可能需要各自的运行时包。

从本技能目录出发，启动器格式如下：

bash

python scripts/urdf path/to/source.py
python scripts/urdf path/to/source.py -o path/to/robot.urdf
python scripts/urdf path/to/a.py=out/a.urdf path/to/b.py=out/b.urdf

普通Python目标会在源码旁生成同级的

.urdf

文件。

-o

--output

仅对单个普通目标有效。对于自定义多目标路径，请使用

SOURCE.py=OUTPUT.urdf

配对格式。

相对源码目标和CLI输出覆盖路径会从当前工作目录解析。若从本技能目录外运行，请为启动器路径添加前缀，以便目标文件仍能从预期工作区解析。

启动器仅执行

gen_urdf()

并验证生成的URDF输出。不提供单独的仅验证命令。

References

参考资料

Design ledger:
```
references/design-ledger.md
```
Frame semantics:
```
references/frame-semantics.md
```
URDF generator contract:
```
references/generator-contract.md
```
URDF generation command:
```
references/gen-urdf.md
```
URDF edit workflow:
```
references/urdf-workflow.md
```
Generation-time validation expectations:
```
references/validation.md
```

设计台账：
```
references/design-ledger.md
```
坐标系语义：
```
references/frame-semantics.md
```
URDF生成器契约：
```
references/generator-contract.md
```
URDF生成命令：
```
references/gen-urdf.md
```
URDF编辑工作流程：
```
references/urdf-workflow.md
```
生成时验证预期：
```
references/validation.md
```