Improve simulator correctness and training reliability

.github/workflows/public-ci.yml

@@ -40,6 +40,17 @@ env:
   GITLEAKS_SHA256: "5bc41815076e6ed6ef8fbecc9d9b75bcae31f39029ceb55da08086315316e3ba"
 
 jobs:
+  model-licenses:
+    name: Model release licenses
+    if: github.repository == 'NVlabs/ProtoMotions'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { lfs: false }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.10" }
+      - run: python scripts/check_model_licenses.py
+
   # Catches a credential in a contributed pull request before it is merged --
   # the one class of mistake that rewriting history afterwards does not undo,
   # because the commit stays reachable from the pull request ref forever.

CONTRIBUTING.md

@@ -2,6 +2,44 @@
 
 We started ProtoMotions3 to promote open research and help all members of the community. All participation in this project is open and not bound to corporate affiliation. 
 
+## Automated Checks
+
+Linting, formatting, license headers and spell checking all run through
+[pre-commit](https://pre-commit.com/). Install the hook once and every commit is checked
+before it is created:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+**Run these tools through pre-commit rather than invoking them yourself.**
+`.pre-commit-config.yaml` pins an exact version of each tool, and pre-commit installs
+those versions into an isolated environment of its own. A `ruff` that happens to be on
+your `PATH` is almost certainly a different version, and the formatter's output changes
+between releases — so a file your local `ruff` wants to reformat may be one the pinned
+version already considers correct. Going through pre-commit is what makes everyone's
+result the same, and the same as CI's.
+
+To check specific files without committing:
+
+```bash
+pre-commit run --files <file1> <file2> ...
+```
+
+Prefer that over `pre-commit run --all-files`: parts of the tree predate these checks, so
+running over everything produces a large diff unrelated to your change.
+
+## Releasing models
+
+Code remains Apache-2.0. NVIDIA-provided model releases default to the NVIDIA
+Open Model License unless explicitly approved otherwise. Follow the
+[model-release checklist](legal/MODEL-LICENSING.md): include a License section
+in the model card, the complete license and an attribution notice with every
+model package, including exported models and adapters. Document any exception
+in the card and the reviewed exception manifest. Run
+`python scripts/check_model_licenses.py` before submitting a model release.
+
 ## Code Reviews
 
 All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult
@@ -59,4 +97,4 @@ All submissions, including submissions by project members, require review. We us
         personal information I submit with it, including my sign-off) is
         maintained indefinitely and may be redistributed consistent with
         this project or the open source license(s) involved.
-  ```
+  ```

README.md

@@ -234,7 +234,12 @@ We welcome contributions! Please read our [**Contributing Guide**](CONTRIBUTING.
 
 ## License
 
-ProtoMotions3 is released under the [**Apache-2.0 License**](LICENSE.md).
+ProtoMotions3 source code is released under the [**Apache-2.0 License**](LICENSE.md).
+
+NVIDIA-provided pretrained models are released under the **NVIDIA Open Model
+License**, unless their model card explicitly states otherwise. Each model
+directory includes its model card, license and attribution notice. See
+[model licensing and redistribution](legal/MODEL-LICENSING.md).
 
 Third-party software and bundled asset notices are listed in [legal/](legal/), including Unitree, BeyondMimic, Isaac Lab, and SMPL/SMPL-H attribution and license notices.
 

data/pretrained_models/AGENTS.md

@@ -0,0 +1,11 @@
+# Model release requirements
+
+- Follow [the model licensing policy](../../legal/MODEL-LICENSING.md).
+- NVIDIA-provided model releases default to the NVIDIA Open Model License;
+  source code remains Apache-2.0.
+- Every model needs a License section in its model card, a complete license
+  copy and an attribution notice. Include these in standalone exports too.
+- Alternative licenses require a reviewed exception recorded in both the card
+  and the exception manifest. Preserve applicable third-party terms.
+- Run `python scripts/check_model_licenses.py` from the repository root.
+- Do not modify weights or serialized configs just to change licensing notices.

data/pretrained_models/gpc_prior/soma_bones/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SOMA BONES-SEED GPC Prior
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This checkpoint is an autoregressive Generative Pre-trained Controller (GPC)

data/pretrained_models/gpc_prior/soma_bones/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/masked_mimic/smpl/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SMPL MaskedMimic
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a MaskedMimic controller for the SMPL humanoid. The policy produces

data/pretrained_models/masked_mimic/smpl/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/g1-bones-deploy/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # G1 BONES-SEED Deployment Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a general motion-tracking policy for the Unitree G1 humanoid. It is the

data/pretrained_models/motion_tracker/g1-bones-deploy/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/smpl-terrains/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SMPL AMASS Terrain Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a general SMPL motion tracker trained on a mixture of procedural terrain

data/pretrained_models/motion_tracker/smpl-terrains/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/smpl/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SMPL AMASS Flat-Terrain Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a general motion-tracking policy for the SMPL humanoid on flat terrain.

data/pretrained_models/motion_tracker/smpl/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/soma-bones/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SOMA BONES-SEED Motion Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a continuous-action general motion tracker for the SOMA 23-body

data/pretrained_models/motion_tracker/soma-bones/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/soma_bones_fsq/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SOMA BONES-SEED FSQ Motion Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a SOMA motion tracker with a finite-scalar-quantization (FSQ) bottleneck.

data/pretrained_models/motion_tracker/soma_bones_fsq/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/pretrained_models/motion_tracker/soma_bones_fsq_amp_muon/MODEL_CARD.md

@@ -1,5 +1,17 @@
 # SOMA BONES-SEED FSQ AMP Tracker
 
+## License
+
+Model license: NVIDIA Open Model License
+
+The model weights, checkpoints, serialized model configurations and exported
+models are licensed under the [NVIDIA Open Model License](LICENSE.pdf).
+See [NOTICE.txt](NOTICE.txt) for attribution. Include both files when
+redistributing these artifacts.
+
+ProtoMotions source code remains Apache-2.0. Training datasets and robot assets
+have separate terms; this model license does not grant rights to those materials.
+
 ## Overview
 
 This is a SOMA motion tracker that combines an FSQ actor bottleneck with

data/pretrained_models/motion_tracker/soma_bones_fsq_amp_muon/NOTICE.txt

@@ -0,0 +1 @@
+Licensed by NVIDIA Corporation under the NVIDIA Open Model License

data/scripts/keypoint_utils.py

@@ -2,6 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import torch
+from protomotions.utils.retargeting_keypoints import SOMA_PELVIS_KEYPOINT_SHIFT
 from protomotions.utils.rotations import quaternion_to_matrix
 from typing import List, Dict, Tuple
 
@@ -580,11 +581,13 @@ def extract_keypoints_from_motion_soma_skel(
         keypoint_orientations_quat, w_last=True
     )
 
-    # Pelvis offset: shift backward in local +y to create forward bias on all
-    # Body keypoints relative to root.
+    # Pelvis offset: store the pelvis keypoint 7 cm behind the Hips joint, as
+    # every SOMA keypoint file so far has it. The retargeters move it back onto
+    # the joint when they load the file (soma_pelvis_keypoint_on_hips in
+    # protomotions/utils/retargeting_keypoints.py).
     root_idx = conceptual_keypoint_names.index("pelvis")
     root_offset = torch.tensor(
-        [0.0, 0.07, 0.0], device=device, dtype=keypoint_positions.dtype
+        SOMA_PELVIS_KEYPOINT_SHIFT, device=device, dtype=keypoint_positions.dtype
     )
     R_root = keypoint_orientations_mat[:, root_idx, :, :]
     keypoint_positions[:, root_idx, :] += torch.einsum(
@@ -671,9 +674,10 @@ def extract_keypoints_from_motion_soma_skel(
                 dim=1,
             )
 
-        # 0.225 * 0.8 = 0.18m, matching retargeter torso_aux x.
-        # A 0.30m offset would produce 0.24m after scaling, creating
-        # a 6cm x-mismatch with the torso_aux (0.18) that pushes pelvis backward.
+        # 0.225 m in front of the shifted pelvis keypoint, i.e. 0.155 m in front
+        # of the Hips joint (0.124 m after G1's 0.8 scaling, against G1's 0.18 m
+        # torso_aux). It was sized as 0.225 * 0.8 = 0.18 m for a G1 pelvis matched
+        # to the shifted keypoint, which the retargeters no longer do.
         pelvis_idx = conceptual_keypoint_names.index("pelvis")
         p_local_pelvis = torch.tensor(
             [0.0, -0.225, 0.0], device=device, dtype=keypoint_positions.dtype

docs/source/api_reference/scripts.rst

@@ -70,10 +70,18 @@ For kinematic motion playback without physics training state:
 
 **Keyboard Controls:**
 
+Click inside the simulation viewer to give it keyboard focus, then use the
+task's key bindings.
+
 * **W/A/S/D** - Move keyboard-controlled task targets when enabled
 * **R** - Reset environments
 * **Q** - Quit
 
+**MuJoCo only:** press **.** to toggle between ProtoMotions key bindings
+(default) and MuJoCo's native viewer key bindings. Only the selected set is
+active. Switching back to ProtoMotions key bindings restores the initial
+visualization settings. Mouse orbit and zoom work in either mode.
+
 train_slurm.py
 --------------
 
@@ -106,4 +114,3 @@ See Also
 
 * :doc:`../getting_started/quickstart` - Getting started guide
 * :doc:`../user_guide/configuration` - Configuration system
-

docs/source/getting_started/pretrained_models.rst

@@ -4,6 +4,13 @@ Pre-trained Models
 Each shipped checkpoint has a model card beside it with the training recipe,
 input and output contract, artifact roles, intended use, and limitations.
 
+NVIDIA-provided pretrained models use the **NVIDIA Open Model License** unless
+their card explicitly specifies otherwise; ProtoMotions source code remains
+Apache-2.0. Each model directory includes a full license and attribution notice.
+Keep these files with redistributed checkpoints and exported models. See the
+`model licensing policy <https://github.com/NVlabs/ProtoMotions/blob/main/legal/MODEL-LICENSING.md>`__
+for details. Training datasets and robot assets retain their separate terms.
+
 Unless its model card says otherwise, a policy should be used on its training
 simulator. The recommended checkpoints were trained or fine-tuned in IsaacLab.
 The G1 deployment tracker is the only current policy trained with the full

docs/source/tutorials/workflows/retargeting_pyroki.rst

@@ -412,6 +412,20 @@ Comparing ``batch_retarget_to_g1_from_keypoints.py`` and
               * onp.array([1.1, 1.1, 1.0])[None, None, :]
           )
 
+   Take the vertical factor for the pelvis and legs from the robot/source
+   pelvis-to-ankle drop, not from the hip-joint height. Knee bend is very
+   sensitive to it: near a straight leg, a pelvis target only 1 cm too low
+   already bends G1's knees by about 20 degrees. Keep the x and y factors
+   equal, so the scaling does not depend on which way the motion is heading.
+
+   The robot matches the pelvis keypoint with its pelvis origin. Keypoint
+   extraction stores the SOMA pelvis keypoint 7 cm behind the Hips joint, so
+   ``load_motion_data`` moves it back onto the joint with
+   ``soma_pelvis_keypoint_on_hips`` from
+   ``protomotions/utils/retargeting_keypoints.py``. Call it in a new robot's
+   script too; otherwise every SOMA target lands about 7 cm too far forward
+   relative to the pelvis.
+
 3. **Auxiliary Point Offsets**
 
    Update hand and torso auxiliary point offsets in ``pc_alignment_cost()``:

docs/source/user_guide/configuration.rst

@@ -124,6 +124,28 @@ Robot configs in ``protomotions/robot_configs/`` define the robot:
 Using Configurations
 --------------------
 
+Marker Body Mass and Inertia
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before importing a robot, the shared loading code resolves its MJCF masses.
+A zero-mass body (typically a fixed tracking marker) receives **0.001 kg (1 g)**
+and diagonal inertia of **4e-8 kg m²** at its local origin. These inertias
+correspond to a 1 g solid sphere with a 1 cm radius; the visual marker geometry
+does not need to change. This convention avoids the extremely small inertia
+of a visualization-sized sphere.
+
+Source MJCF files are unchanged. The loader prepares a temporary asset with
+explicit marker inertias, which IsaacGym, IsaacLab, Newton, Genesis and MuJoCo
+all consume. IsaacLab performs this step before MJCF-to-USD conversion and
+invalidates older conversion caches. PhysX articulation links cannot have zero
+mass; leaving a marker massless can silently give it the simulator's default
+mass instead.
+
+Ordinary physical bodies retain their authored or geometry-derived mass.
+Disabling mass randomization does not make a body massless: it uses the MJCF
+values after normalization. When enabled, body-mass randomization overrides
+the selected bodies and scales their inertia from the positive source properties.
+
 Basic Usage
 ~~~~~~~~~~~