Parse contact response attributes from NewtonMaterialAPI

Read ke/kd/kf/ka from NewtonMaterialAPI on bound materials during USD
import. The schema resolver resolves these across Newton, PhysX
(compliantContactStiffness/Damping), and MuJoCo (solref) at the
MATERIAL level, with configurable resolver priority.

Legacy newton:contact_ke/kd custom attributes on shape prims are
retained as a fallback when no material value is authored, emitting a
DeprecationWarning at resolve time directing users to the
NewtonMaterialAPI attrs. MuJoCo mjc:solref on material prims is
similarly deprecated. Explicitly authoring -inf on a material attr
("use engine default") blocks legacy fallback.

Requires newton-usd-schemas>=0.3.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: andrewkaufman

CHANGELOG.md

@@ -12,6 +12,7 @@
 - Add robotics tutorial notebook covering ModelBuilder, solvers, CUDA graphs, IK, and pick-and-place
 - Add `newton.utils.OnnxRuntime`, a graph-capturable ONNX inference engine backed solely by Warp kernels (no `onnxruntime` or `torch` runtime dependency); used by `ControllerNeuralMLP` and `ControllerNeuralLSTM` to load `.onnx` policies. To migrate a TorchScript policy, run `torch.onnx.export(model, dummy_input, "policy.onnx", opset_version=17)` once and point the controllers at the resulting `.onnx` file. The `onnx` package is now an optional extra (`pip install newton[onnx]`); install it explicitly to use the ONNX runtime.
 - Add USD parsing for `NewtonSiteAPI` to mark shapes as sites.
+- Add USD parsing for contact response attributes (`ke`, `kd`, `kf`, `ka`) from `NewtonMaterialAPI` on bound materials
 
 ### Changed
 
@@ -22,6 +23,7 @@
 ### Deprecated
 
 - Deprecate loading `.pt` / `.pth` (TorchScript) checkpoints via `ControllerNeuralMLP`; the legacy TorchScript / dict-checkpoint path still works (with a `DeprecationWarning`) when PyTorch is installed but will be removed in a future release. `ControllerNeuralLSTM` requires re-exporting to ONNX with the metadata properties documented in its class docstring; pointing it at a `.pt` checkpoint now raises `NotImplementedError` with migration guidance. Convert the MLP checkpoint to ONNX once with `torch.onnx.export(model, dummy_input, "policy.onnx", opset_version=17)` and load the resulting `.onnx` file.
+- Deprecate `newton:contact_ke`/`kd` custom attributes on shape prims; author `newton:contactStiffness`/`newton:contactDamping` on the bound `NewtonMaterialAPI` material instead
 
 ### Removed
 

docs/concepts/collisions.rst

@@ -1654,20 +1654,72 @@ Example:
 USD Integration
 ---------------
 
-Custom collision properties can be authored in USD:
+Newton provides several USD schema APIs for authoring collision and contact
+properties directly in USD layers.
+
+**NewtonCollisionAPI**
+
+Applied to collision shapes to configure per-shape contact detection. The
+``newton:contactMargin`` and ``newton:contactGap`` attributes map to
+:attr:`~ModelBuilder.ShapeConfig.margin` and :attr:`~ModelBuilder.ShapeConfig.gap`
+respectively.
+
+.. code-block:: usda
+
+    def Cube "Collider" (
+        prepend apiSchemas = ["PhysicsCollisionAPI", "NewtonCollisionAPI"]
+    ) {
+        float newton:contactMargin = 0.001
+        float newton:contactGap = 0.02
+    }
+
+**NewtonMaterialAPI**
+
+Extends ``PhysicsMaterialAPI`` with torsional/rolling friction
+(``newton:torsionalFriction``, ``newton:rollingFriction``) and contact response
+attributes. The contact response attributes map to :class:`~ModelBuilder.ShapeConfig`
+fields as follows: ``newton:contactStiffness`` → ``ke``,
+``newton:contactDamping`` → ``kd``, ``newton:contactFrictionStiffness`` → ``kf``,
+``newton:contactAdhesion`` → ``ka``. A value of ``-inf`` means "use the engine's
+default" (see :ref:`Contact Material Properties`).
 
 .. code-block:: usda
 
-    def Xform "Box" (
-        prepend apiSchemas = ["PhysicsRigidBodyAPI", "PhysicsCollisionAPI"]
+    def Material "RubberMaterial" (
+        prepend apiSchemas = ["PhysicsMaterialAPI", "NewtonMaterialAPI"]
+    ) {
+        float physics:staticFriction = 1.0
+        float physics:dynamicFriction = 0.8
+        float newton:torsionalFriction = 0.1
+        float newton:rollingFriction = 0.01
+        float newton:contactStiffness = 5000.0
+        float newton:contactDamping = 200.0
+        float newton:contactFrictionStiffness = 800.0
+        float newton:contactAdhesion = 0.0
+    }
+
+    def Cube "Collider" (
+        prepend apiSchemas = ["PhysicsCollisionAPI"]
+    ) {
+        rel material:binding:physics = </RubberMaterial>
+    }
+
+**NewtonMeshCollisionAPI**
+
+Applied on top of ``PhysicsMeshCollisionAPI`` to control mesh approximation.
+Currently exposes ``newton:maxHullVertices`` for convex hull generation.
+
+**Custom Properties**
+
+Additional per-shape attributes that Newton reads:
+
+.. code-block:: usda
+
+    def Cube "Collider" (
+        prepend apiSchemas = ["PhysicsCollisionAPI"]
     ) {
         custom int newton:collision_group = 1
-        custom int newton:world = 0
-        custom float newton:contact_ke = 100000.0
-        custom float newton:contact_kd = 1000.0
-        custom float newton:contact_kf = 1000.0
-        custom float newton:contact_ka = 0.0
-        custom float newton:margin = 0.00001
+        custom bool newton:is_sensor = false
     }
 
 See :doc:`custom_attributes` and :doc:`usd_parsing` for details.

newton/_src/usd/schemas.py

@@ -39,6 +39,42 @@ def _physx_gap_from_prim(prim: Usd.Prim) -> float | None:
     return float(contact_offset) - float(rest_offset)
 
 
+def _newton_legacy_contact_attr(legacy_name: str, material_attr: str):
+    """Return a getter that reads a legacy contact custom attr with a deprecation warning."""
+
+    def _getter(prim: Usd.Prim) -> float | None:
+        value = usd.get_attribute(prim, legacy_name)
+        if value is not None:
+            warnings.warn(
+                f"'{legacy_name}' on shape prim is deprecated; "
+                f"author '{material_attr}' on the bound NewtonMaterialAPI material instead.",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            return float(value)
+        return None
+
+    return _getter
+
+
+def _mjc_legacy_material_solref(converter, material_attr: str):
+    """Return a getter that reads legacy mjc:solref on a material prim with a deprecation warning."""
+
+    def _getter(prim: Usd.Prim) -> float | None:
+        value = usd.get_attribute(prim, "mjc:solref")
+        if value is not None:
+            warnings.warn(
+                f"'mjc:solref' on material prim is deprecated; "
+                f"author '{material_attr}' on the bound NewtonMaterialAPI material instead.",
+                DeprecationWarning,
+                stacklevel=4,
+            )
+            return converter(value)
+        return None
+
+    return _getter
+
+
 class SchemaResolverNewton(SchemaResolver):
     """Schema resolver for Newton-authored USD attributes.
 
@@ -84,9 +120,17 @@ class SchemaResolverNewton(SchemaResolver):
             # Collisions: newton margin == newton:contactMargin, newton gap == newton:contactGap
             "margin": SchemaAttribute("newton:contactMargin", 0.0),
             "gap": SchemaAttribute("newton:contactGap", float("-inf")),
-            # Contact stiffness/damping
-            "ke": SchemaAttribute("newton:contact_ke", None),
-            "kd": SchemaAttribute("newton:contact_kd", None),
+            # Legacy per-shape contact attrs (deprecated; use NewtonMaterialAPI instead)
+            "ke": SchemaAttribute(
+                "newton:contact_ke",
+                None,
+                usd_value_getter=_newton_legacy_contact_attr("newton:contact_ke", "newton:contactStiffness"),
+            ),
+            "kd": SchemaAttribute(
+                "newton:contact_kd",
+                None,
+                usd_value_getter=_newton_legacy_contact_attr("newton:contact_kd", "newton:contactDamping"),
+            ),
         },
         PrimType.BODY: {},
         PrimType.ARTICULATION: {
@@ -95,6 +139,10 @@ class SchemaResolverNewton(SchemaResolver):
         PrimType.MATERIAL: {
             "mu_torsional": SchemaAttribute("newton:torsionalFriction", 0.25),
             "mu_rolling": SchemaAttribute("newton:rollingFriction", 0.0005),
+            "ke": SchemaAttribute("newton:contactStiffness", None),
+            "kd": SchemaAttribute("newton:contactDamping", None),
+            "kf": SchemaAttribute("newton:contactFrictionStiffness", None),
+            "ka": SchemaAttribute("newton:contactAdhesion", None),
         },
         PrimType.ACTUATOR: {},
     }
@@ -181,8 +229,8 @@ class SchemaResolverPhysx(SchemaResolver):
             ),
         },
         PrimType.MATERIAL: {
-            "stiffness": SchemaAttribute("physxMaterial:compliantContactStiffness", 0.0),
-            "damping": SchemaAttribute("physxMaterial:compliantContactDamping", 0.0),
+            "ke": SchemaAttribute("physxMaterial:compliantContactStiffness", None),
+            "kd": SchemaAttribute("physxMaterial:compliantContactDamping", None),
         },
         PrimType.BODY: {
             # Rigid body damping
@@ -344,8 +392,8 @@ class SchemaResolverMjc(SchemaResolver):
             ),
             "gap": SchemaAttribute("mjc:gap", 0.0),
             # Contact stiffness/damping from per-geom solref
-            "ke": SchemaAttribute("mjc:solref", [0.02, 1.0], solref_to_stiffness),
-            "kd": SchemaAttribute("mjc:solref", [0.02, 1.0], solref_to_damping),
+            "ke": SchemaAttribute("mjc:solref", None, solref_to_stiffness),
+            "kd": SchemaAttribute("mjc:solref", None, solref_to_damping),
         },
         PrimType.MATERIAL: {
             # Materials
@@ -354,8 +402,16 @@ class SchemaResolverMjc(SchemaResolver):
             # Contact models
             "priority": SchemaAttribute("mjc:priority", 0),
             "weight": SchemaAttribute("mjc:solmix", 1.0),
-            "stiffness": SchemaAttribute("mjc:solref", [0.02, 1.0], solref_to_stiffness),
-            "damping": SchemaAttribute("mjc:solref", [0.02, 1.0], solref_to_damping),
+            "ke": SchemaAttribute(
+                "mjc:solref",
+                None,
+                usd_value_getter=_mjc_legacy_material_solref(solref_to_stiffness, "newton:contactStiffness"),
+            ),
+            "kd": SchemaAttribute(
+                "mjc:solref",
+                None,
+                usd_value_getter=_mjc_legacy_material_solref(solref_to_damping, "newton:contactDamping"),
+            ),
         },
         PrimType.ACTUATOR: {
             # Actuators

newton/_src/utils/import_usd.py

@@ -8,6 +8,7 @@
 import datetime
 import inspect
 import itertools
+import math
 import os
 import posixpath
 import re
@@ -280,6 +281,10 @@ class PhysicsMaterial:
         rollingFriction: float = builder.default_shape_cfg.mu_rolling
         restitution: float = builder.default_shape_cfg.restitution
         density: float = builder.default_shape_cfg.density
+        ke: float | None = None
+        kd: float | None = None
+        kf: float | None = None
+        ka: float | None = None
 
     # load joint defaults
     default_joint_friction = builder.default_joint_cfg.friction
@@ -1768,6 +1773,13 @@ def warn_invalid_desc(path, descriptor) -> bool:
         if warn_invalid_desc(sdf_path, desc):
             continue
         prim = stage.GetPrimAtPath(sdf_path)
+
+        def _resolve_contact_attr(key, _prim=prim):
+            val = R.get_value(_prim, prim_type=PrimType.MATERIAL, key=key, verbose=verbose)
+            if val is None:
+                return None
+            return float(val)
+
         material_specs[str(sdf_path)] = PhysicsMaterial(
             staticFriction=desc.staticFriction,
             dynamicFriction=desc.dynamicFriction,
@@ -1789,6 +1801,10 @@ def warn_invalid_desc(path, descriptor) -> bool:
             # Treat non-positive/unauthored material density as "use importer default".
             # Authored collider/body MassAPI mass+inertia is handled later.
             density=desc.density if desc.density > 0.0 else default_shape_density,
+            ke=_resolve_contact_attr("ke"),
+            kd=_resolve_contact_attr("kd"),
+            kf=_resolve_contact_attr("kf"),
+            ka=_resolve_contact_attr("ka"),
         )
 
     if UsdPhysics.ObjectType.RigidBody in ret_dict:
@@ -2585,7 +2601,6 @@ def _build_mass_info_from_shape_geometry(
                     shape_density = material.density
                 else:
                     shape_density = default_shape_density
-                prim_and_scene = (prim, physics_scene_prim)
                 local_xform = wp.transform(shape_spec.localPos, usd.value_to_warp(shape_spec.localRot))
                 if body_id == -1:
                     shape_xform = incoming_world_xform * local_xform
@@ -2632,22 +2647,22 @@ def _build_mass_info_from_shape_geometry(
                 ) and not hide_collider_for_body
                 collider_is_visible = collider_is_visible and _is_effectively_visible(prim)
 
-                shape_ke = R.get_value(
-                    prim,
-                    prim_type=PrimType.SHAPE,
-                    key="ke",
-                    verbose=verbose,
-                )
-                if shape_ke is None:
-                    shape_ke = builder.default_shape_cfg.ke
-                shape_kd = R.get_value(
-                    prim,
-                    prim_type=PrimType.SHAPE,
-                    key="kd",
-                    verbose=verbose,
-                )
-                if shape_kd is None:
-                    shape_kd = builder.default_shape_cfg.kd
+                # Contact response: material (if authored) > per-shape resolver > builder default.
+                _default = builder.default_shape_cfg
+                shape_ke = material.ke if material.ke is not None and math.isfinite(material.ke) else _default.ke
+                shape_kd = material.kd if material.kd is not None and math.isfinite(material.kd) else _default.kd
+                shape_kf = material.kf if material.kf is not None and math.isfinite(material.kf) else _default.kf
+                shape_ka = material.ka if material.ka is not None and math.isfinite(material.ka) else _default.ka
+
+                for attr_key in ("ke", "kd"):
+                    if getattr(material, attr_key) is not None:
+                        continue
+                    per_shape_val = R.get_value(prim, prim_type=PrimType.SHAPE, key=attr_key, verbose=verbose)
+                    if per_shape_val is not None and math.isfinite(float(per_shape_val)):
+                        if attr_key == "ke":
+                            shape_ke = float(per_shape_val)
+                        else:
+                            shape_kd = float(per_shape_val)
 
                 shape_color = material_props.get("color")
                 shape_params = {
@@ -2656,12 +2671,8 @@ def _build_mass_info_from_shape_geometry(
                     "cfg": ModelBuilder.ShapeConfig(
                         ke=shape_ke,
                         kd=shape_kd,
-                        kf=usd.get_float_with_fallback(
-                            prim_and_scene, "newton:contact_kf", builder.default_shape_cfg.kf
-                        ),
-                        ka=usd.get_float_with_fallback(
-                            prim_and_scene, "newton:contact_ka", builder.default_shape_cfg.ka
-                        ),
+                        kf=shape_kf,
+                        ka=shape_ka,
                         margin=margin_val,
                         gap=gap_val,
                         mu=material.dynamicFriction,