Jerry
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# SDF interoperability notes
|
|
|
|
Use this reference when SDF work touches upstream geometry, robot-description data, Gazebo/libsdformat, model packages, or CAD Viewer.
|
|
|
|
## Geometry assets
|
|
|
|
SDF should reference geometry and mesh assets; it should not regenerate them.
|
|
|
|
When SDF references generated meshes, record:
|
|
|
|
- source geometry file;
|
|
- exported mesh path;
|
|
- mesh unit convention;
|
|
- mesh origin convention;
|
|
- visual scale;
|
|
- collision simplification decision.
|
|
|
|
Regenerate geometry and mesh artifacts with their owning workflow before regenerating SDF if geometry changed.
|
|
|
|
## Robot descriptions
|
|
|
|
Keep the simulator document aligned with the upstream robot-description source when one exists.
|
|
|
|
Upstream robot-description data usually owns:
|
|
|
|
- link and joint structure used by robot-state publishing;
|
|
- physical joint limits;
|
|
- inertials and visual/collision geometry when that source is authoritative;
|
|
- control-related structure and runtime interfaces.
|
|
|
|
Use SDF for simulator/world concerns:
|
|
|
|
- simulator plugins;
|
|
- sensors requiring simulator-specific XML;
|
|
- surfaces/contact/friction;
|
|
- lights, terrain, physics, and worlds;
|
|
- nested models and includes;
|
|
- simulator-specific metadata.
|
|
|
|
Do not use SDF to paper over a wrong upstream frame tree unless the task explicitly targets a simulator-only model.
|
|
|
|
## Planning metadata
|
|
|
|
SDF should not define planning groups, end-effectors, group states, or disabled-collision matrices. If the task becomes IK or path-planning work, use the planning metadata workflow that owns those semantics.
|
|
|
|
## CAD Viewer
|
|
|
|
CAD Viewer can review `.sdf` files visually through `$cad-viewer` and help catch gross placement or resource issues. It cannot prove simulator dynamics, inertial validity, plugin loading, sensor topics, or joint-axis semantics.
|
|
|
|
Pass explicit generated or modified `.sdf` paths to `$cad-viewer` whenever it is available, and return the live viewer link it prints.
|
|
|
|
CAD Viewer renders SDF as static structure plus direct inspection controls. It lists plugins, sensors, lights, includes, and nested models as metadata, but does not execute plugins or consume file-authored motion contracts.
|
|
|
|
## Gazebo / libsdformat
|
|
|
|
The bundled validator is a lightweight preflight check. Use the target simulator's parser and loader when compatibility matters.
|
|
|
|
Good checks include:
|
|
|
|
```bash
|
|
gz sdf --check path/to/model.sdf
|
|
```
|
|
|
|
and a real simulator load in the target environment.
|
|
|
|
## Model packages and URIs
|
|
|
|
SDF resource resolution is environment-dependent. Record which URI forms the target consumer can resolve:
|
|
|
|
- relative paths from the generated `.sdf` location;
|
|
- `model://` paths under the simulator model path;
|
|
- `package://` paths under ROS/package resolution;
|
|
- `fuel://` resources;
|
|
- `http://` or `https://` assets if external fetches are allowed.
|
|
|
|
The bundled validator can confirm local relative paths, but it cannot prove external simulator resource paths unless the target environment is available.
|