google-deepmind / google-deepmind/mujoco

USD decoder can change inferred mass/inertia for explicit body inertials and visual-only geoms

Open
#3,399 0 comments 0 reactions 1 assignee Claimed by @havess View on GitHub
bug
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.