sdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SDF

Use this skill when the deliverable is an SDFormat document or a Python

gen_sdf()

source. SDFormat describes simulator and world behavior: models, worlds, frames, poses, links, joints, inertials, visuals, collisions, sensors, lights, physics, plugins, includes, and simulator metadata.

This skill is for SDFormat, not signed-distance-field geometry.

当交付物为SDFormat文档或Python

gen_sdf()

源码时，使用本技能。SDFormat用于描述仿真器与世界的行为：包括模型、世界、坐标系、位姿、连杆、关节、惯性参数、视觉组件、碰撞组件、传感器、灯光、物理系统、插件、引用以及仿真器元数据。

本技能适用于SDFormat，而非有符号距离场几何造型。

Core rules

核心规则

Treat the Python file defining
```
gen_sdf()
```
as source of truth. Treat configured
```
.sdf
```
files as generated artifacts unless the user explicitly asks for direct XML editing.
Identify the target consumer before editing: Gazebo/libsdformat version, another simulator, visualization-only tooling, model package, or world handoff.
Decide document kind: model-level SDF, world-level SDF, or model-in-world. Prefer model-level SDF for reusable robot/object exports.
Use SI units unless the target explicitly requires otherwise: meters, kilograms, seconds, radians.
Prefer
```
version="1.12"
```
for new outputs unless the target consumer constrains the version.
Establish the design ledger before writing poses, frames, joint axes, mesh scales, inertials, sensors, or plugins. Use
```
references/design-ledger.md
```
and
```
references/llm-guardrails.md
```
.
Do not infer spatial transforms from visual impression alone. Derive poses, axes, scale, mass, inertia, and frame names from upstream source data, drawings, simulator documentation, measured values, or explicit assumptions.
Prefer helper functions and named constants over large XML string literals. Hidden numbers are a common SDF failure mode.
Generate only explicit targets with
```
scripts/sdf
```
or the repository's existing SDF launcher. Do not run directory-wide generation.
Regenerate upstream geometry, mesh, robot-description, render, topology, or package assets with their owning workflows before regenerating SDF that references them.
After generation, run available checks: bundled validation, optional
```
gz sdf --check
```
, simulator load, joint motion, plugin/sensor startup, and
```
$render
```
handoff when available.
Report assumptions, skipped checks, unresolved resource paths, and target-specific compatibility risks.

将定义
```
gen_sdf()
```
的Python文件视为唯一可信源。除非用户明确要求直接编辑XML，否则将已配置的
```
.sdf
```
文件视为生成产物。
编辑前确认目标使用者：Gazebo/libsdformat版本、其他仿真器、仅可视化工具、模型包或世界交付对象。
确定文档类型：模型级SDF、世界级SDF或模型嵌入世界的SDF。优先选择模型级SDF用于可复用机器人/对象导出。
除非目标明确要求，否则使用国际单位制（SI）：米、千克、秒、弧度。
除非目标使用者限制版本，否则新输出优先使用
```
version="1.12"
```
。
在编写位姿、坐标系、关节轴、网格缩放、惯性参数、传感器或插件之前，建立设计台账。使用
```
references/design-ledger.md
```
和
```
references/llm-guardrails.md
```
。
不得仅通过视觉印象推断空间变换。位姿、轴、缩放比例、质量、惯性和坐标系名称需从上游源数据、图纸、仿真器文档、测量值或明确假设中推导。
优先使用辅助函数和命名常量，而非大型XML字符串字面量。隐藏数值是SDF常见的故障原因。
仅通过
```
scripts/sdf
```
或仓库现有SDF启动器生成指定目标。不得运行目录级全量生成。
在重新生成引用上游几何、网格、机器人描述、渲染、拓扑或包资产的SDF之前，先通过其所属工作流重新生成这些资产。
生成完成后，运行可用检查：内置验证、可选的
```
gz sdf --check
```
、仿真器加载、关节运动、插件/传感器启动，以及可用时的
```
$render
```
交付检查。
报告假设条件、跳过的检查、未解析的资源路径和目标特定的兼容性风险。

Scope

适用范围

Use this skill for SDFormat outputs and generators. Do not use it for signed-distance-field modeling, raw geometry generation, planning semantics, or to paper over incorrect upstream robot/source data unless the task is explicitly simulator-only.

本技能适用于SDFormat输出与生成器。请勿用于有符号距离场建模、原始几何生成、规划语义，或掩盖上游机器人/源数据的错误，除非任务明确仅针对仿真器。

Workflow

工作流程

Locate the
```
gen_sdf()
```
source and intended
```
.sdf
```
output.
Read or create the design ledger.
Read
```
references/frame-semantics.md
```
before editing any
```
<pose>
```
,
```
<frame>
```
, joint axis,
```
relative_to
```
,
```
expressed_in
```
, nested scope, sensor frame, or plugin frame.
Edit the generator source, not generated XML.
Use optional builder helpers when they make the generated structure clearer; raw ElementTree is still allowed.
Regenerate the explicit target.
Treat bundled validation as a guardrail, not simulator proof.
Run target-consumer smoke tests when available.
After creating or modifying
```
.sdf
```
output, always hand the explicit generated path to
```
$render
```
when available;
```
$render
```
checks/reuses a live viewer and returns a link. CAD Explorer does not execute SDF plugins or read file-authored motion metadata.
For visual feedback during generation review, prefer
```
$render
```
snapshots over opening the viewer manually or using Playwright. Use still snapshots only; SDF review should not generate GIFs.
Report checks run, checks skipped, and assumptions.

定位
```
gen_sdf()
```
源码与预期的
```
.sdf
```
输出文件。
读取或创建设计台账。
在编辑任何
```
<pose>
```
、
```
<frame>
```
、关节轴、
```
relative_to
```
、
```
expressed_in
```
、嵌套作用域、传感器坐标系或插件坐标系之前，阅读
```
references/frame-semantics.md
```
。
编辑生成器源码，而非生成的XML文件。
当辅助构建工具能让生成结构更清晰时优先使用；也可直接使用ElementTree。
重新生成指定目标。
将内置验证视为防护机制，而非仿真器兼容性的绝对证明。
可用时运行目标使用者的冒烟测试。
创建或修改
```
.sdf
```
输出后，若可用，务必将生成的明确路径移交
```
$render
```
；
```
$render
```
会检查/复用实时查看器并返回链接。CAD Explorer不会执行SDF插件或读取文件中的运动元数据。
生成审查期间如需视觉反馈，优先使用
```
$render
```
快照，而非手动打开查看器或使用Playwright。仅使用静态快照；SDF审查不得生成GIF动图。
报告已执行的检查、跳过的检查以及假设条件。

Commands

命令

Run with the project or workspace Python environment.

bash

python scripts/sdf path/to/source.py
python scripts/sdf path/to/source.py -o path/to/output.sdf
python scripts/sdf path/to/a.py=out/a.sdf path/to/b.py=out/b.sdf

Plain Python targets write sibling

.sdf

files beside their sources.

-o

--output

is valid only with one plain target.

SOURCE.py=OUTPUT.sdf

supports custom multi-target destinations.

If the runtime supports optional external checking:

bash

python scripts/sdf path/to/source.py --gz-check auto
python scripts/sdf path/to/source.py --gz-check required
python scripts/sdf path/to/source.py --gz-check never

gz sdf --check

is optional target-consumer validation. It should be reported as skipped when unavailable unless explicitly required.

在项目或工作区Python环境中运行。

bash

python scripts/sdf path/to/source.py
python scripts/sdf path/to/source.py -o path/to/output.sdf
python scripts/sdf path/to/a.py=out/a.sdf path/to/b.py=out/b.sdf

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

.sdf

文件。仅当单个普通目标时，

-o

--output

参数才有效。

SOURCE.py=OUTPUT.sdf

支持自定义多目标输出路径。

若运行环境支持可选的外部检查：

bash

python scripts/sdf path/to/source.py --gz-check auto
python scripts/sdf path/to/source.py --gz-check required
python scripts/sdf path/to/source.py --gz-check never

gz sdf --check

是可选的目标使用者验证工具。若不可用，除非明确要求，否则应报告为已跳过。

Required report shape

报告要求格式

When finishing an SDF task, include a compact report:

text

Generated: path/to/model.sdf from path/to/model.py
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- visual review: render viewer link returned; snapshot run/skipped
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.

完成SDF任务时，请包含一份简洁报告：

text

生成文件：path/to/model.sdf 来自 path/to/model.py
已执行检查：
- 内置SDF验证：通过
- gz sdf --check：已跳过，未安装gz
- 仿真器加载：已跳过，目标仿真器不可用
- 视觉审查：已返回渲染查看器链接；快照已执行/已跳过
假设条件：
- 假设网格单位为米。
- 假设激光雷达坐标系与lidar_link重合。
风险提示：
- 相机插件文件名未在目标仿真器环境中验证。

References

参考文档

Generation command:
```
references/gen-sdf.md
```
Generator contract:
```
references/generator-contract.md
```
SDF workflow:
```
references/sdf-workflow.md
```
Builder helpers:
```
references/builder-helpers.md
```
LLM guardrails:
```
references/llm-guardrails.md
```
Design ledger:
```
references/design-ledger.md
```
Frame semantics:
```
references/frame-semantics.md
```
Validation scope:
```
references/validation.md
```
Smoke tests:
```
references/smoke-tests.md
```
Interoperability notes:
```
references/interoperability.md
```
Examples:
```
references/examples.md
```
Runtime notes and current limitations:
```
references/implementation-notes.md
```

生成命令：
```
references/gen-sdf.md
```
生成器契约：
```
references/generator-contract.md
```
SDF工作流：
```
references/sdf-workflow.md
```
辅助构建工具：
```
references/builder-helpers.md
```
LLM防护规则：
```
references/llm-guardrails.md
```
设计台账：
```
references/design-ledger.md
```
坐标系语义：
```
references/frame-semantics.md
```
验证范围：
```
references/validation.md
```
冒烟测试：
```
references/smoke-tests.md
```
互操作性说明：
```
references/interoperability.md
```
示例：
```
references/examples.md
```
运行时说明与当前限制：
```
references/implementation-notes.md
```