first commit

2026-07-22 13:48:46 +08:00
commit c87751c3dc
2820 changed files with 726976 additions and 0 deletions
@@ -0,0 +1,98 @@
+# SDF smoke tests
+
+Use smoke tests after generated SDF passes bundled validation. The goal is to catch simulator and spatial failures that dependency-light XML checks cannot detect.
+
+## Recommended checks
+
+### Bundled validation
+
+```bash
+python scripts/sdf path/to/model.py
+python scripts/sdf path/to/model.py --strict
+```
+
+Bundled validation runs during explicit target generation. Use `--strict` when warnings should block handoff.
+
+### SDFormat parser check
+
+When Gazebo tooling is installed:
+
+```bash
+gz sdf --check path/to/model.sdf
+```
+
+or through the skill CLI:
+
+```bash
+python scripts/sdf path/to/model.py --gz-check auto
+```
+
+Use the exact simulator environment that will consume the file when possible.
+
+### Simulator load check
+
+Load the model or world in the target simulator and check:
+
+- no parser warnings or plugin load errors;
+- model appears at the intended pose;
+- visual and collision assets resolve;
+- collision geometry is not visibly offset from visuals;
+- dynamic model does not explode, fall through the floor, or produce invalid inertia warnings.
+
+### Joint motion check
+
+For each non-fixed joint:
+
+- command a small positive motion;
+- confirm the moving child moves in the expected direction;
+- confirm limits stop motion where expected;
+- confirm continuous joints can rotate continuously if intended.
+
+### CAD Viewer static review
+
+After generating or modifying an `.sdf`, hand the explicit path to `$cad-viewer` for a live viewer link when available.
+
+- confirm direct model links, joints, frames, visuals, and collisions are placed correctly;
+- confirm includes, plugins, sensors, lights, nested models, and unsupported geometry are listed as static metadata;
+- record any simulator-only behavior that CAD Viewer cannot execute.
+
+### Sensor and plugin check
+
+For each sensor or plugin:
+
+- confirm plugin library loads;
+- confirm expected topics/services appear;
+- confirm frame names match the design ledger;
+- confirm update rate and namespace behavior;
+- capture one sample output if practical.
+
+### Visual review
+
+When CAD Viewer or an equivalent viewer is available through `$cad-viewer`, return the viewer link. Visual review is useful but insufficient: it can catch gross placement and mesh problems, but it cannot prove axis frames, inertials, dynamics, or plugin behavior.
+
+## Report format
+
+Use a compact report:
+
+```text
+Checks run:
+- bundled SDF validation: passed
+- gz sdf --check: skipped, gz not installed
+- simulator load: passed in Gazebo Harmonic
+- joint motion: shoulder_pan positive motion verified; gripper joints skipped
+- plugin startup: camera plugin unresolved, requires target simulator package
+
+Assumptions:
+- Assumed mesh units are meters.
+- Assumed lidar frame is coincident with lidar_link.
+```
+
+## When to stop
+
+Stop and fix the generator when:
+
+- bundled validation has errors;
+- `gz sdf --check` fails under a required external-check policy;
+- the simulator reports invalid inertias or unresolved required assets;
+- a joint moves opposite from the documented positive direction;
+- plugin startup fails for a plugin required by the task.