google-deepmind / google-deepmind/mujoco

USD decoder does not preserve sites, model names, unlimited joints, and disabled-collider metadata

Open
#3,391 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

I am working on MJCF <-> USD roundtrip validation for MuJoCo models, including MuJoCo Menagerie assets. The goal is to make USD import preserve MuJoCo-authored USD semantics closely enough that compiled-model comparison and short deterministic rollouts are useful.

### My setup

- MuJoCo built from source from `google-deepmind/mujoco` `main`.
- Build option: `MUJOCO_WITH_USD=ON`.
- API path: USD decoder plugin through `mj_parse` / `mj_loadXML`-style import, then compiled-model inspection.
- Platform: Linux x86_64.
- Source USD files are MuJoCo-authored USD, generated from MJCF models and then imported back into MuJoCo.

### What's happening? What did you expect?

Several small USD decoder behaviors make MuJoCo-authored USD imports noisier or less faithful than necessary:

1. `MjcSiteAPI` prims that are also `UsdGeomGprim`s can decode as both sites and disabled visual geoms.
2. The decoded `mjSpec` model name falls back to `"MuJoCo Model"` instead of using an available USD stage/default-prim name.
3. USD revolute/prismatic joints with un-authored limits can decode as MuJoCo limited joints with `range="-inf inf"`.
4. Disabled colliders routed through the visual-geom path can lose `MjcCollisionAPI` metadata such as `group`.

Expected behavior: these values should be preserved during USD import. They are either explicitly authored in USD or implied by the absence of authored data, so the decoded `mjSpec`/compiled model should not add extra geoms, lose a better model name, turn unbounded joints into limited joints, or drop MuJoCo collision metadata on disabled colliders.

### Steps for reproduction

Use the USD decoder plugin with MuJoCo-authored USD inputs. Each item below is independently reproducible:

1. Site double-decode:
- Start from a model with a MuJoCo site.
- Convert it to MuJoCo-authored USD, where the site prim has `MjcSiteAPI` and is also a `UsdGeomGprim`.
- Import that USD back into MuJoCo.
- Actual: the prim can appear both as a site and as an extra disabled visual geom.
- Expected: it should decode as a site only.

2. Model name fallback:
- Import a USD stage with a meaningful default prim or root layer display name.
- Actual: decoded model name can be `"MuJoCo Model"`.
- Expected: use the default prim display name, default prim name, or root layer display name when available.

3. Unlimited hinge/slide limits:
- Convert and import `unlimited_joint_limits.xml`
- Actual before the fix: unbounded hinge/slide joints can import as limited joints with `range="-inf inf"`.
- Expected: unbounded revolute/prismatic USD joints should remain unlimited MuJoCo joints unless finite limits are authored.

4. Disabled collider metadata:
- Start from a MuJoCo geom that is contact-disabled but still has MuJoCo metadata such as `group`.
- Convert to USD; the converter authors it as a disabled collider with `physics:collisionEnabled=false` and `MjcCollisionAPI`.
- Import that USD back into MuJoCo.
- Actual before the fix: the disabled collider routes through the visual-geom path and can lose `mjc:group`.
- Expected: it should remain contact-disabled but still preserve `MjcCollisionAPI` metadata.

### Minimal model for reproduction

Useful small source MJCFs for generating MuJoCo-authored USD repro files:

Unlimited joint limits:

```xml
















```

Disabled collider metadata:

```xml






```

Site double-decode:

```xml






```

### Code required for reproduction

The repro path is:

```bash
# 1. Convert the minimal MJCF to USD using the MuJoCo USD converter.
# 2. Import that USD into MuJoCo with the USD decoder plugin.
# 3. Save or inspect the decoded compiled model.
```

### 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.