srdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SRDF

Use this skill for MoveIt semantic robot descriptions on top of an existing valid URDF. SRDF defines planning semantics; it does not define physical robot structure.

SRDF correctness is a planning semantics problem. The common failure is not invalid XML; it is a plausible SRDF that gives MoveIt the wrong planning group, wrong tool link, wrong default state, unsafe disabled-collision matrix, or wrong joint units. Because language models are weak at spatial and kinematic reasoning, derive planning groups, end effectors, group states, and disabled collisions from the URDF topology, MoveIt Setup Assistant output, sampled collision analysis, or explicit user data. Do not infer them from visual appearance alone.

本技能用于在已有有效URDF基础上生成MoveIt语义机器人描述。SRDF定义规划语义，不定义机器人物理结构。

SRDF的正确性是规划语义问题。常见的失败并非XML无效，而是看似合理的SRDF给MoveIt传递了错误的规划组、错误的工具链接、错误的默认状态、不安全的碰撞禁用矩阵或错误的关节单位。由于语言模型在空间和运动学推理方面能力较弱，规划组、末端执行器、组状态及碰撞禁用规则需从URDF拓扑结构、MoveIt Setup Assistant输出、采样碰撞分析或明确的用户数据推导得出，不能仅从视觉外观推断。

Format boundary

格式边界

URDF owns physical robot structure: links, joints, geometry, inertials, limits, mimic joints, transmissions, and robot-state publishing.
SRDF owns MoveIt semantics: virtual joints, passive joints, planning groups, group states, end effectors, and disabled collision pairs.
SDF owns simulator/world semantics: physics, sensors, lights, plugins, worlds, and simulation-specific metadata.

Do not place geometry, inertials, joint origins, link poses, mesh references, physical joint limits, transmissions, or

ros2_control

interfaces in SRDF.

After creating or modifying generated

.srdf

files, hand the explicit output path to

$render

when that skill is available;

$render

checks/reuses a live viewer and returns a link. If the user needs interactive IK or path-planning controls, make that part of the

$render

handoff; CAD Explorer owns the local

moveit2_server

setup and runtime.

URDF负责机器人物理结构：连杆、关节、几何形状、惯性参数、限位、模拟关节、传动装置及机器人状态发布。
SRDF负责MoveIt语义：虚拟关节、被动关节、规划组、组状态、末端执行器及碰撞禁用对。
SDF负责模拟器/世界语义：物理特性、传感器、灯光、插件、世界环境及仿真特定元数据。

请勿在SRDF中放置几何形状、惯性参数、关节原点、连杆位姿、网格引用、物理关节限位、传动装置或

ros2_control

接口。

创建或修改生成的

.srdf

文件后，若

$render

技能可用，将明确的输出路径传递给

$render

；

$render

会检查/复用实时查看器并返回链接。若用户需要交互式逆运动学（IK）或路径规划控制，请将该需求纳入

$render

的交付流程；CAD Explorer负责本地

moveit2_server

的设置与运行。

Required workflow

必备工作流

Start from a valid URDF. Generate or fix the URDF first. The SRDF generator validates against the source-relative
```
.urdf
```
path supplied by
```
gen_srdf()
```
.
Identify the planning task. Record whether the goal is arm IK, gripper control, mobile base planning, dual-arm planning, tool use, or local smoke testing.
Create or update the planning ledger. Use
```
references/planning-ledger.md
```
before writing XML.
Define virtual and passive joints deliberately. Use them when needed by the robot model, even though the current lightweight runtime does not fully inventory them yet.
Define planning groups from URDF topology. Prefer chain groups for serial manipulators when base/tip form a real path. Use joint/link/subgroup definitions only when they are deliberate.
Define end effectors after group membership is known. Avoid overlap between an end-effector group and its parent group. Record the actual target/TCP link.
Define group states in URDF-native units. Revolute and continuous values are radians; prismatic values are meters. Do not store degrees in SRDF.
Generate disabled collisions from evidence. Use adjacency, MoveIt Setup Assistant sampling, or explicit user-provided collision matrices. Do not invent broad disable lists.
Regenerate only explicit SRDF targets. Generation validates the generated SRDF against the linked URDF before writing.
Run MoveIt smoke tests when available. Use MoveIt Setup Assistant or a project MoveIt launch directly. For local Explorer-based IK/path planning, hand the SRDF to
```
$render
```
; it owns
```
moveit2_server
```
startup and URL wiring.
Hand off generated artifacts for review. After creating or modifying generated
```
.srdf
```
files, pass the explicit file path to
```
$render
```
for live viewer links when available.
Use snapshots for visual feedback. Prefer
```
$render
```
snapshots over opening the viewer manually or using Playwright. Use still snapshots only; SRDF review should not generate GIFs.
Report assumptions and skipped checks. Include incomplete validation, missing MoveIt environment, skipped
```
$render
```
handoff/viewer checks, manually reasoned collision disables, and inferred target links.

从有效URDF开始。先生成或修复URDF。SRDF生成器会根据
```
gen_srdf()
```
提供的相对源路径
```
.urdf
```
进行验证。
确定规划任务。记录目标任务：机械臂逆运动学、夹爪控制、移动基座规划、双臂规划、工具使用或本地冒烟测试。
创建或更新规划台账。编写XML前，请使用
```
references/planning-ledger.md
```
。
谨慎定义虚拟关节与被动关节。根据机器人模型需求使用它们，即便当前轻量运行时尚未完全支持其清单管理。
基于URDF拓扑定义规划组。对于串联机械手，当基座/末端形成实际路径时，优先选择链式组。仅在有明确需求时才使用关节/连杆/子组定义。
明确组归属后定义末端执行器。避免末端执行器组与其父规划组存在重叠。记录实际目标/TCP连杆。
以URDF原生单位定义组状态。旋转关节和连续关节值为弧度；移动关节值为米。请勿在SRDF中存储角度值（度数）。
基于证据生成碰撞禁用规则。使用邻接关系、MoveIt Setup Assistant采样或用户明确提供的碰撞矩阵。请勿随意创建宽泛的禁用列表。
仅重新生成明确的SRDF目标。生成过程会在写入前验证生成的SRDF与关联的URDF是否匹配。
可用时运行MoveIt冒烟测试。直接使用MoveIt Setup Assistant或项目的MoveIt启动文件。对于基于本地Explorer的逆运动学/路径规划，请将SRDF交付给
```
$render
```
；它负责
```
moveit2_server
```
的启动与URL配置。
交付生成的工件以供审核。创建或修改生成的
```
.srdf
```
文件后，若可用，将明确的文件路径传递给
```
$render
```
以获取实时查看器链接。
使用快照获取视觉反馈。优先使用
```
$render
```
快照，而非手动打开查看器或使用Playwright。仅使用静态快照；SRDF审核不应生成GIF。
报告假设与跳过的检查。包括未完成的验证、缺失的MoveIt环境、跳过的
```
$render
```
交付/查看器检查、手动推导的碰撞禁用规则及推断的目标连杆。

Commands

命令

From this skill directory, the SRDF launcher shape is:

bash

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

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.

For GUI/rendering review, do not start Explorer from this skill. Hand generated or modified

.srdf

files to

$render

with explicit paths;

$render

owns viewer liveness checks and links. Request optional MoveIt2 controls only when the user needs IK or path-planning review;

$render

owns the server commands and environment guidance.

在本技能目录下，SRDF启动器的使用格式如下：

bash

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

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

对于GUI/渲染审核，请勿从本技能启动Explorer。将生成或修改后的

.srdf

文件连同明确路径交付给

$render

；

$render

负责查看器的可用性检查与链接生成。仅当用户需要逆运动学或路径规划审核时，才请求可选的MoveIt2控制；

$render

负责服务器命令与环境指导。

Hard rules

硬性规则

SRDF must reference an existing valid URDF.
The SRDF robot name must match the URDF robot name.
Group states use URDF-native units: radians for revolute/continuous, meters for prismatic.
Disabled collision pairs require truthful reasons and provenance.
End-effector groups should not share links with their parent planning group.
```
$render
```
owns CAD Explorer links and the local
```
moveit2_server
```
; SRDF should hand off explicit generated/modified
```
.srdf
```
paths rather than starting GUI services itself.
CAD Explorer or visual rendering review is useful but cannot prove planning correctness.

SRDF必须引用已存在的有效URDF。
SRDF的机器人名称必须与URDF的机器人名称匹配。
组状态使用URDF原生单位：旋转/连续关节为弧度，移动关节为米。
碰撞禁用对需提供真实的理由与来源。
末端执行器组不应与其父规划组共享连杆。
```
$render
```
负责CAD Explorer链接与本地
```
moveit2_server
```
；SRDF应交付明确的生成/修改后的
```
.srdf
```
路径，而非自行启动GUI服务。
CAD Explorer或视觉渲染审核虽有帮助，但无法证明规划的正确性。

References

参考资料

Generation command:
```
references/gen-srdf.md
```
Generator contract:
```
references/generator-contract.md
```
SRDF workflow:
```
references/srdf-workflow.md
```
Planning ledger:
```
references/planning-ledger.md
```
Validation scope:
```
references/validation.md
```
End effectors:
```
references/end-effectors.md
```
Disabled collisions:
```
references/disabled-collisions.md
```
Runtime notes and current limitations:
```
references/implementation-notes.md
```

For CAD Explorer links or local MoveIt2 controls, use

$render

; in that skill, read

references/moveit2-server.md

生成命令：
```
references/gen-srdf.md
```
生成器契约：
```
references/generator-contract.md
```
SRDF工作流：
```
references/srdf-workflow.md
```
规划台账：
```
references/planning-ledger.md
```
验证范围：
```
references/validation.md
```
末端执行器：
```
references/end-effectors.md
```
碰撞禁用：
```
references/disabled-collisions.md
```
运行时说明与当前限制：
```
references/implementation-notes.md
```

如需CAD Explorer链接或本地MoveIt2控制，请使用

$render

；在该技能中，请阅读

references/moveit2-server.md

。