first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,115 @@
+# SDF design ledger
+
+Create or update this ledger before writing SDF XML. The ledger can live in the response, a project note, or comments in the generator source. The goal is to externalize spatial and simulator assumptions before they become hard-to-audit XML.
+
+## Document
+
+| Field | Value |
+|---|---|
+| Output path | |
+| Source file | |
+| SDF version | `1.12` unless constrained |
+| Document kind | model / world / model-in-world |
+| Target consumer | Gazebo / other simulator / visualization-only / model package |
+| Units | meters, kilograms, seconds, radians unless documented otherwise |
+| Coordinate convention | REP-103-like / simulator-specific / documented exception |
+| World support needed | yes/no; reason |
+| Optional external checks | `gz sdf --check`, simulator load, CAD Viewer, other |
+
+## Model or world scope
+
+| Item | Value |
+|---|---|
+| Model/world name | |
+| Static or dynamic | |
+| Canonical link, if relevant | |
+| Model/world pose | xyz + rpy/quaternion |
+| Model/world pose `relative_to` | |
+| Includes | URI + purpose |
+| World physics/lights/plugins | source and target simulator |
+
+## Frames
+
+| Frame | Scope | Attached to | Pose | Pose `relative_to` | Purpose | Source |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+Use named frames for clarity when multiple sensors, nested models, tool frames, plugin frames, or repeated transforms depend on the same relationship.
+
+## Links
+
+| Link | Physical / frame-like | Pose | Pose `relative_to` | Inertial source | Sensor/plugin attached | Notes |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+Physical dynamic links need inertials. Frame-like links may omit inertials only when documented.
+
+## Joints
+
+| Joint | Type | Parent | Child | Pose | Pose frame / `relative_to` | Axis | Axis frame / `expressed_in` | Limits | Positive motion | Source |
+|---|---|---|---|---|---|---|---|---|---|---|
+| | | | | | | | | | | |
+
+For revolute and prismatic joints, record limit units: radians for revolute, meters for prismatic. Continuous joints should not be given artificial finite position limits unless a simulator-specific reason is documented.
+
+## Geometry
+
+| Owner | Visual/collision | Name | Geometry type | Pose | Pose `relative_to` | URI or dimensions | Mesh units | Scale | Source |
+|---|---|---|---|---|---|---|---|---|---|
+| | | | | | | | | | |
+
+Collision geometry should be selected for simulation cost and stability, not just visual similarity.
+
+## Inertials
+
+| Link | Mass | COM pose | Inertia tensor | Method/source | Confidence |
+|---|---|---|---|---|---|
+| | | | | | |
+
+Mark approximations clearly. Very small, zero, negative, or guessed inertias are high risk for simulation.
+
+## Sensors and plugins
+
+| Element | Parent | Pose/frame | Filename/type | Parameters | Source docs | Assumptions |
+|---|---|---|---|---|---|---|
+| | | | | | | |
+
+Do not invent plugin filenames, topics, frame names, namespaces, controller parameters, or update rates. Derive them from simulator documentation or user-provided configuration.
+
+## Mesh URI policy
+
+| URI kind | Allowed? | Resolution expectation | Notes |
+|---|---|---|---|
+| Relative local path | | Relative to generated `.sdf` location | |
+| `file://` | | Absolute local file | |
+| `model://` | | Simulator model path | |
+| `package://` | | Simulator/ROS package environment | |
+| `fuel://`, `http://`, `https://` | | External resource | |
+
+## Assumptions to report
+
+List every guessed or inferred value:
+
+- transform or pose;
+- axis sign or positive-motion convention;
+- mesh unit or scale;
+- mass, COM, or inertia;
+- target simulator behavior;
+- plugin parameter;
+- unresolved external URI;
+- skipped validation or smoke test.
+
+If a value cannot be derived or safely assumed, generate a minimal placeholder only when the user asked for a placeholder, and label it as such.
+
+## Compact response template
+
+```text
+SDF source: path/to/source.py
+Generated target: path/to/output.sdf
+Target consumer: Gazebo Harmonic, SDF 1.12
+Bundled validation: passed with 2 warnings
+External checks: gz sdf --check skipped, gz not installed
+Assumptions:
+- Assumed mesh units are meters.
+- Assumed camera optical frame follows simulator plugin documentation.
+```