Update USD support in MuJoCo to Newton USD schemas v0.4.0.

See changelog for more info. PiperOrigin-RevId: 960284190 Change-Id: I89a84b1efbc22c89ee99db7436851ef27a325176
2026-08-06 07:17:01 -07:00
parent 63b779042c
commit 39e4458806
13 changed files with 421 additions and 93 deletions
@@ -207,7 +207,7 @@ function(install_newton_usd_plugin install_base_dir)
  FetchContent_Declare(
    newton-usd-schemas
    GIT_REPOSITORY https://github.com/newton-physics/newton-usd-schemas.git
-    GIT_TAG v0.1.0rc3
+    GIT_TAG v0.4.0
    GIT_SHALLOW TRUE
    UPDATE_DISCONNECTED TRUE
  )
@@ -290,6 +290,7 @@ class "MjcSceneAPI" (
 }

 class "MjcSiteAPI" (
+    apiSchemas = ["NewtonSiteAPI"]
    doc = "API describing a MuJoCo site."
 )
 {
@@ -340,7 +341,9 @@ class "MjcCollisionAPI" (
    )
    uniform bool mjc:shellinertia = 0 (
        displayName = "Shell Inertia"
-        doc = "Enables handling of the inertia assuming mass is concentrated on the surface."
+        doc = """DEPRECATED: Use NewtonMassAPI's newton:massModel = \"shell\" instead.
+
+        Enables handling of the inertia assuming mass is concentrated on the surface."""
    )
    uniform double[] mjc:solimp = [0.9, 0.95, 0.001, 0.5, 2] (
        displayName = "SolImp"
@@ -364,7 +367,9 @@ class "MjcMeshCollisionAPI" (
    uniform token mjc:inertia = "legacy" (
        allowedTokens = ["legacy", "convex", "exact", "shell"]
        displayName = "Inertia"
-        doc = "Controls how a mesh is used when mass and inertia are inferred from geometry."
+        doc = """DEPRECATED: Use NewtonMassAPI's newton:massModel or UsdPhysics's physics:approximation instead.
+
+        Controls how a mesh is used when mass and inertia are inferred from geometry."""
    )
    uniform int mjc:maxhullvert = -1 (
        displayName = "Maximum Hull Vertices"
@@ -493,6 +498,7 @@ class MjcKeyframe "MjcKeyframe" (
 }

 class "MjcJointAPI" (
+    apiSchemas = ["NewtonJointAPI"]
    doc = "API describing a MuJoCo joint."
 )
 {
@@ -510,13 +516,19 @@ class "MjcJointAPI" (
        doc = "If this flag is enabled, gravity compensation applied to this joint is added to actuator forces (mjData.qfrc_actuator) rather than passive forces (mjData.qfrc_passive). Notionally, this means that gravity compensation is the result of a control system rather than natural buoyancy. In practice, enabling this flag is useful when joint-level actuator force clamping is used. In this case, the total actuation force applied on a joint, including gravity compensation, is guaranteed to not exceed the specified limits. See Force limits and actuatorfrcrange for more details on this type of force limit."
    )
    uniform double mjc:armature = 0 (
-        doc = "Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."
+        doc = """DEPRECATED: Use newton:armature instead.
+
+        Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."""
    )
    uniform double mjc:damping = 0 (
-        doc = "Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."
+        doc = """DEPRECATED: Use newton:damping instead.
+
+        Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."""
    )
    uniform double mjc:frictionloss = 0 (
-        doc = "Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."
+        doc = """DEPRECATED: Use newton:friction instead.
+
+        Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."""
    )
    uniform int mjc:group = 0 (
        displayName = "Group"
@@ -643,6 +643,7 @@ class "MjcSiteAPI"
    }
    doc = """API describing a MuJoCo site."""

+    prepend apiSchemas = ["NewtonSiteAPI"]
    inherits = </APISchemaBase>
 )
 {
@@ -698,7 +699,9 @@ class "MjcCollisionAPI"
            string apiName = "ShellInertia"
        }
        displayName = "Shell Inertia"
-        doc = """Enables handling of the inertia assuming mass is concentrated on the surface."""
+        doc = """DEPRECATED: Use NewtonMassAPI's newton:massModel = "shell" instead.
+
+        Enables handling of the inertia assuming mass is concentrated on the surface."""
    )

    uniform int mjc:priority = 0 (
@@ -779,7 +782,9 @@ class "MjcMeshCollisionAPI"
            string apiName = "Inertia"
        }
        displayName = "Inertia"
-        doc = """Controls how a mesh is used when mass and inertia are inferred from geometry."""
+        doc = """DEPRECATED: Use NewtonMassAPI's newton:massModel or UsdPhysics's physics:approximation instead.
+
+        Controls how a mesh is used when mass and inertia are inferred from geometry."""
    )

    uniform int mjc:maxhullvert = -1 (
@@ -968,6 +973,7 @@ class "MjcJointAPI"
    }
    doc = """API describing a MuJoCo joint."""

+    prepend apiSchemas = ["NewtonJointAPI"]
    inherits = </APISchemaBase>
 )
 {
@@ -1033,15 +1039,21 @@ class "MjcJointAPI"
    )

    uniform double mjc:armature = 0 (
-        doc = "Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."
+        doc = """DEPRECATED: Use newton:armature instead.
+
+        Additional inertia associated with movement of the joint that is not due to body mass. This added inertia is usually due to a rotor (a.k.a armature) spinning faster than the joint itself due to a geared transmission. The value applies to all degrees of freedom created by this joint. Besides increasing the realism of joints with geared transmission, positive armature significantly improves simulation stability, even for small values, and is a recommended possible fix when encountering stability issues."""
    )

    uniform double mjc:damping = 0 (
-        doc = "Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."
+        doc = """DEPRECATED: Use newton:damping instead.
+
+        Damping applied to all degrees of freedom created by this joint. Unlike friction loss which is computed by the constraint solver, damping is simply a force linear in velocity. It is included in the passive forces. Despite this simplicity, larger damping values can make numerical integrators unstable, which is why our Euler integrator handles damping implicitly. See Integration in the Computation chapter."""
    )

    uniform double mjc:frictionloss = 0 (
-        doc = "Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."
+        doc = """DEPRECATED: Use newton:friction instead.
+
+        Friction loss due to dry friction. This value is the same for all degrees of freedom created by this joint. Semantically friction loss does not make sense for free joints, but the compiler allows it. To enable friction loss, set this attribute to a positive value."""
    )
 }

@@ -122,14 +122,21 @@ TF_DEFINE_PRIVATE_TOKENS(kTokens,
                         (UsdPreviewSurface)
                         ((NewtonMaterialAPI, "NewtonMaterialAPI"))
                         ((NewtonMeshCollisionAPI, "NewtonMeshCollisionAPI"))
+                         ((NewtonJointAPI, "NewtonJointAPI"))
+                         ((NewtonMassAPI, "NewtonMassAPI"))
                         ((newtonTorsionalFriction, "newton:torsionalFriction"))
                         ((newtonRollingFriction, "newton:rollingFriction"))
+                         ((newtonArmature, "newton:armature"))
+                         ((newtonDamping, "newton:damping"))
+                         ((newtonFriction, "newton:friction"))
+                         ((newtonMassModel, "newton:massModel"))
                         ((newtonMaxHullVertices, "newton:maxHullVertices"))
                         ((newtonMaxSolverIterations, "newton:maxSolverIterations"))
                         ((newtonTimeStepsPerSecond, "newton:timeStepsPerSecond"))
                         ((newtonGravityEnabled, "newton:gravityEnabled"))
                         ((newtonContactMargin, "newton:contactMargin"))
                         ((newtonContactGap, "newton:contactGap"))
+                         ((newtonContactAdhesion, "newton:contactAdhesion"))
                        );

 // Using to satisfy TF_REGISTRY_FUNCTION macro below and avoid operating in PXR_NS.
@@ -404,6 +411,13 @@ class ModelWriter {
    WriteUniformAttribute(mesh_spec, pxr::SdfValueTypeNames->Token,
                          MjcPhysicsTokens->mjcInertia, inertia);

+    // Newton mass model attribute (partially replaces deprecated mjc:inertia)
+    if (mesh->inertia == mjtMeshInertia::mjMESH_INERTIA_SHELL) {
+      ApplyApiSchema(layer_, mesh_spec, kTokens->NewtonMassAPI);
+      WriteUniformAttribute(mesh_spec, pxr::SdfValueTypeNames->Token,
+                            kTokens->newtonMassModel, MjcPhysicsTokens->shell);
+    }
+
    // Newton mesh attribute (replaces deprecated mjc:maxhullvert)
    if (mesh->maxhullvert != -1) {
      WriteUniformAttribute(mesh_spec, pxr::SdfValueTypeNames->Int,
@@ -902,6 +916,11 @@ class ModelWriter {
    WriteUniformAttribute(material_spec, pxr::SdfValueTypeNames->Float,
                          kTokens->newtonRollingFriction,
                          (float)geom->friction[2]);
+    if (geom->adhesion != 0.0f) {
+      WriteUniformAttribute(material_spec, pxr::SdfValueTypeNames->Float,
+                            kTokens->newtonContactAdhesion,
+                            (float)geom->adhesion);
+    }

    return material_spec;
  }
@@ -1703,10 +1722,12 @@ class ModelWriter {
                     pxr::UsdPhysicsTokens->PhysicsCollisionAPI);
      ApplyApiSchema(layer_, geom_spec, MjcPhysicsTokens->MjcCollisionAPI);

-      WriteUniformAttribute(
-          geom_spec, pxr::SdfValueTypeNames->Bool,
-          MjcPhysicsTokens->mjcShellinertia,
-          geom->typeinertia == mjtGeomInertia::mjINERTIA_SHELL);
+      if (geom->typeinertia == mjtGeomInertia::mjINERTIA_SHELL) {
+        ApplyApiSchema(layer_, geom_spec, kTokens->NewtonMassAPI);
+        WriteUniformAttribute(geom_spec, pxr::SdfValueTypeNames->Token,
+                              kTokens->newtonMassModel,
+                              MjcPhysicsTokens->shell);
+      }

      WriteUniformAttribute(geom_spec, pxr::SdfValueTypeNames->Int,
                            MjcPhysicsTokens->mjcPriority, geom->priority);
@@ -2138,15 +2159,19 @@ class ModelWriter {
      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Double,
                            MjcPhysicsTokens->mjcSpringref, joint->springref);

-      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Double,
-                            MjcPhysicsTokens->mjcArmature, joint->armature);
+      // Newton joint attributes (replaces deprecated mjc:armature / mjc:damping
+      // / mjc:frictionloss)
+      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Float,
+                            kTokens->newtonArmature,
+                            static_cast<float>(joint->armature));

-      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Double,
-                            MjcPhysicsTokens->mjcDamping, joint->damping[0]);
+      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Float,
+                            kTokens->newtonDamping,
+                            static_cast<float>(joint->damping[0]));

-      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Double,
-                            MjcPhysicsTokens->mjcFrictionloss,
-                            joint->frictionloss);
+      WriteUniformAttribute(joint_spec, pxr::SdfValueTypeNames->Float,
+                            kTokens->newtonFriction,
+                            static_cast<float>(joint->frictionloss));
    }
    if (joint_id >= 0) {
      joint_paths_[joint_id] = joint_spec->GetPath();