google-deepmind / google-deepmind/mujoco
USD decoder can change inferred mass/inertia for explicit body inertials and visual-only geoms
- Dominant language
- C++
- Stars
- 15.2k
- Forks
- 1.8k
- Avg merge
- 10d 16h
- Merged PRs (30d)
- 25
Description
### Intro
Hi!
I am working on MJCF <-> USD roundtrip validation for MuJoCo models. The validation compares compiled mass/inertia fields and short deterministic rollouts after MJCF -> USD -> MuJoCo import.
### My setup
- MuJoCo built from source from `google-deepmind/mujoco` `main`.
- Build option: `MUJOCO_WITH_USD=ON`.
- API path: USD decoder plugin import, then compiled-model and sampled-dynamics comparison.
- Platform: Linux x86_64.
- Source USD files are MuJoCo-authored USD generated from MJCF models with explicit inertials and visual-only geoms.
### What's happening? What did you expect?
Some MuJoCo-authored USD stages carry explicit body inertials or visual-only MuJoCo geoms. The current decoder can change model mass properties in two ways:
1. A body with authored mass and diagonal inertia is not marked as explicit inertial in `mjSpec`, allowing MuJoCo compilation to infer or rewrite inertial data.
2. A visual-only `MjcImageableAPI` geom without authored mass/density can inherit MuJoCo's default geom density, adding mass to a body even though the geom was visual-only in the source model.
Expected behavior:
- If USD authors `UsdPhysicsMassAPI` mass and diagonal inertia for a body, the decoded `mjsBody` should preserve that as an explicit inertial.
- If a visual-only `MjcImageableAPI` geom has no authored `UsdPhysicsMassAPI` mass or density, it should not silently inherit MuJoCo default geom density and change body mass/inertia.
This matters for simulation, not only serialized XML appearance. In roundtrip testing, the Franka hand exposed explicit inertial drift, and UMI gripper exposed visual-only geoms adding mass.
### Steps for reproduction
Explicit body inertial:
1. Convert a model with explicit body inertials to MuJoCo-authored USD.
2. Import the USD into MuJoCo with the USD decoder plugin.
3. Inspect the decoded compiled body mass, inertial position, and diagonal inertia.
4. Actual before the fix: explicit authored inertial data can be treated as inferred/recomputed during compilation.
5. Expected: the decoded body preserves authored explicit inertial data.
Visual-only geom density:
1. Convert a model containing massless/contact-disabled visual geoms to MuJoCo-authored USD.
2. Import the USD into MuJoCo with the USD decoder plugin.
3. Inspect the decoded compiled body mass and inertia.
4. Actual before the fix: visual-only geoms without authored mass/density can inherit default MuJoCo geom density and add mass.
5. Expected: visual-only `MjcImageableAPI` geoms without authored mass/density decode as massless, preserving source model mass properties.
### Minimal model for reproduction
Explicit inertial repro seed:
```xml
```
Visual-only geom density repro seed:
```xml
```
Menagerie evidence:
- `franka_emika_panda/hand.xml`: hand/finger mass and inertia drift before preserving explicit inertials.
- `umi_gripper/umi_gripper.xml` or `umi_gripper/scene.xml`: visual-only mesh geoms gained mass before defaulting massless `MjcImageableAPI` geoms to `density=0`.
### Code required for reproduction
The repro path is:
```bash
# 1. Convert the minimal MJCF to USD using mujoco-usd-converter.
# 2. Import that USD with MuJoCo's USD decoder plugin.
# 3. Save or inspect the decoded compiled model.
# 4. Compare body mass, body inertia, geom density, and sampled dynamics.
```
### Confirmations
- [x] I searched the [latest documentation](https://mujoco.readthedocs.io/en/latest/overview.html) thoroughly before posting.
- [x] I searched previous [Issues](https://github.com/google-deepmind/mujoco/issues) and [Discussions](https://github.com/google-deepmind/mujoco/discussions), I am certain this has not been raised before.
Contributor guide
Assessment
This issue has not been assessed yet.