> ## Documentation Index
> Fetch the complete documentation index at: https://dimensional-cc-frontier.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Vgn mujoco grasp demo

# VGN MuJoCo Grasp Demo

`vgn-mujoco-grasp-demo` is an opt-in xArm7 MuJoCo demo for target-conditioned TSDF reconstruction and VGN grasp candidate generation. It does not change `xarm-perception-sim`.

The demo composes:

* `MujocoSimModule` using `data/xarm7/scene.xml`, the `wrist_camera` depth stream, and a deterministic xArm7 observation pose based on the MJCF home keyframe.
* `SceneReconstructionModule`, publishing `scene_pointcloud`, `tsdf_surface`, and reconstruction status.
* `ObjectSceneRegistrationModule`, detecting the configured target prompt/name after startup and exposing robust percentile target bounds from the registered object pointcloud.
* `VGNGraspGenModule`, generating world-frame `grasp_candidates` only after a runtime registered object has been selected.
* `GraspingModule`, resolving the generated object id to target bounds and invoking target-conditioned VGN.
* `TargetGraspDemoController`, waiting for a matching runtime object id, publishing `grasp_target_bounds`, then calling the object-id grasp API.
* `RerunBridgeModule`, visualizing stable paths under `world/`.

Run it with VGN installed and a model checkpoint path:

```bash theme={null}
uv sync --extra grasp
DIMOS_VGN_MODEL_PATH=/path/to/vgn_conv.pth uv run dimos run vgn-mujoco-grasp-demo
```

Expected Rerun entities:

* `world/scene_pointcloud`
* `world/tsdf_surface`
* `world/grasp_target_bounds`
* `world/target_masked_tsdf`
* `world/grasp_candidates`

The default target prompt/name is `orange`, the sphere near the workspace center in the xArm7 demo scene. The object id is not known at launch; it is generated by object registration after the demo starts. The controller only grasps a runtime registered object whose name matches the configured target and does not fall back to workspace-level VGN candidates. The demo uses a 1.5 cm cushion around robust target bounds before masking the TSDF.

The TSDF visualizations are diagnostic voxel views, not watertight meshes. `world/tsdf_surface` and `world/target_masked_tsdf` render near-surface TSDF voxels as points. They can look blocky at the demo resolution, and the masked TSDF is expected to look cropped because voxels outside the cushioned target bounds are suppressed before VGN inference.

For offline inspection, the demo writes TSDF debug artifacts to `/tmp/opencode/dimos-vgn-tsdf-debug/` whenever target-conditioned generation runs. Each run exports raw `.npz` grids, Open3D-readable `.ply` point clouds for near-surface and observed voxels, `.png` slice/projection summaries, and `.json` count/stat summaries for both the full TSDF and target-masked TSDF. The near-surface views use normalized TSDF values with `abs(distance) <= 0.1`; they are diagnostic zero-crossing bands, not metric-distance meshes.

If no checkpoint path is set, the VGN module starts but reports a clear `DIMOS_VGN_MODEL_PATH` requirement when target-conditioned grasp generation runs.