first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,76 @@
+# 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.