Jerry
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# SDF workflow
|
|
|
|
Use this reference when editing SDF robot model structure, world structure, mesh references, simulator metadata, or generated SDF output.
|
|
|
|
## Edit loop
|
|
|
|
1. Find the Python source that defines `gen_sdf()`.
|
|
2. Treat that source as authoritative. Do not hand-edit generated `.sdf` output unless explicitly instructed.
|
|
3. Identify the target consumer and required SDFormat version.
|
|
4. Decide whether the output is model-level, world-level, or model-in-world.
|
|
5. Fill or update the design ledger before writing XML.
|
|
6. For every pose and axis, state the frame in which it is expressed. Use `relative_to` / `expressed_in` where ambiguity would otherwise remain.
|
|
7. Edit the generator source.
|
|
8. Regenerate only the explicit target.
|
|
9. Review bundled validation errors as structural guardrails, not exhaustive simulator proof.
|
|
10. Hand generated or modified `.sdf` files to `$cad-viewer` for live viewer links when available.
|
|
11. Run available smoke tests.
|
|
12. Report assumptions and skipped checks.
|
|
|
|
## Model vs world
|
|
|
|
Use **model-level SDF** when exporting a reusable robot or object model that another world can include.
|
|
|
|
Use **world-level SDF** when the task includes:
|
|
|
|
- physics engine settings;
|
|
- lights or scene setup;
|
|
- terrain or ground plane;
|
|
- multiple initial model placements;
|
|
- world plugins;
|
|
- includes of external model packages;
|
|
- simulator scene setup.
|
|
|
|
Use **model-in-world SDF** when the task explicitly needs both an inline model and world-specific context.
|
|
|
|
The lightweight validator should allow pure world-only documents. A world-only document with lights, physics, actors, or includes can be valid SDFormat even when it contains no inline `<model>`.
|
|
|
|
## Mesh references
|
|
|
|
SDF mesh URIs should be stable from the generated `.sdf` file's perspective or use a simulator/package URI convention understood by the consumer.
|
|
|
|
Good URI choices include:
|
|
|
|
- relative paths beside the generated SDF when the model is self-contained;
|
|
- `model://...` for simulator model packages;
|
|
- `package://...` when the simulator environment resolves package roots;
|
|
- `fuel://...`, `http://...`, or `https://...` only when the consumer is expected to fetch external assets.
|
|
|
|
Do not use generated SDF XML as the source of truth for mesh placement. Prefer deriving visual and collision mesh references from the same source data that owns mesh instance placement.
|
|
|
|
## Inertials and physics
|
|
|
|
For dynamic models, inertial data is simulation-critical. If inertials are estimated, record the approximation method. Do not copy visual origins into inertial origins unless that is physically justified.
|
|
|
|
Collision geometry should be selected for stable and fast physics, not visual fidelity. Use primitive or simplified collision geometry when possible.
|
|
|
|
## Plugins and sensors
|
|
|
|
For plugins and sensors, record:
|
|
|
|
- plugin filename or sensor type;
|
|
- expected simulator distribution/version;
|
|
- topics, frames, update rates, namespaces;
|
|
- parameter source;
|
|
- startup smoke test result.
|
|
|
|
Do not invent plugin parameters. Incorrect plugin XML can pass lightweight validation and still fail at simulator load time.
|
|
|
|
CAD Viewer reviews SDF files as static model/world structure through `$cad-viewer` links. Do not add Explorer-only motion plugins; use simulator-native controllers, plugins, or test harnesses for simulator behavior.
|
|
|
|
## Existing SDF inspection
|
|
|
|
When inspecting existing `.sdf` files, separate three questions:
|
|
|
|
1. Is the XML structurally valid enough for the bundled validator?
|
|
2. Is it compatible with the target SDFormat/libsdformat/simulator version?
|
|
3. Does it satisfy this project's packaging, mesh, and workflow policy?
|
|
|
|
Do not reject valid SDF solely because it violates a project preference unless the task or repository policy requires that preference.
|