Make PhysX tendon fragments instance-selective

Author: ooctipus

docs/source/api/lab_physx/isaaclab_physx.sim.schemas.rst

@@ -43,7 +43,10 @@ isaaclab_physx.sim.schemas
   .. autosummary::
 
     PhysxFixedTendonPropertiesCfg
+    PhysxFixedTendonCfg
+    PhysxFixedTendonAxisCfg
     PhysxSpatialTendonPropertiesCfg
+    PhysxSpatialTendonCfg
 
   .. rubric:: Deformable body
 
@@ -57,6 +60,9 @@ isaaclab_physx.sim.schemas
 
   .. autosummary::
 
+    apply_fixed_tendon
+    apply_fixed_tendon_axis
+    apply_spatial_tendon
     define_deformable_body_properties
     modify_deformable_body_properties
 
@@ -130,11 +136,30 @@ Tendon
     :show-inheritance:
     :exclude-members: __init__
 
+.. autoclass:: PhysxFixedTendonCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__
+
+.. autoclass:: PhysxFixedTendonAxisCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__
+
 .. autoclass:: PhysxSpatialTendonPropertiesCfg
     :members:
     :show-inheritance:
     :exclude-members: __init__
 
+.. autoclass:: PhysxSpatialTendonCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__
+
+.. autofunction:: apply_fixed_tendon
+.. autofunction:: apply_fixed_tendon_axis
+.. autofunction:: apply_spatial_tendon
+
 Deformable Body
 ---------------
 
@@ -177,11 +202,9 @@ The following classes are part of the public :mod:`isaaclab_physx.sim.schemas` A
    PhysxCollisionCfg
    PhysxConvexDecompositionCfg
    PhysxConvexHullCfg
-   PhysxFixedTendonCfg
    PhysxJointCfg
    PhysxRigidBodyCfg
    PhysxSDFMeshCfg
-   PhysxSpatialTendonCfg
    PhysxTriangleMeshCfg
    PhysxTriangleMeshSimplificationCfg
    RigidBodyPropertiesCfg
@@ -223,9 +246,6 @@ The following classes are part of the public :mod:`isaaclab_physx.sim.schemas` A
 .. autoclass:: PhysxConvexHullCfg
    :show-inheritance:
 
-.. autoclass:: PhysxFixedTendonCfg
-   :show-inheritance:
-
 .. autoclass:: PhysxJointCfg
    :show-inheritance:
 
@@ -235,9 +255,6 @@ The following classes are part of the public :mod:`isaaclab_physx.sim.schemas` A
 .. autoclass:: PhysxSDFMeshCfg
    :show-inheritance:
 
-.. autoclass:: PhysxSpatialTendonCfg
-   :show-inheritance:
-
 .. autoclass:: PhysxTriangleMeshCfg
    :show-inheritance:
 

docs/source/overview/core-concepts/schema_fragments.rst

@@ -60,10 +60,31 @@ imports a backend:
      - tendon-bearing prims (existing tendon instances)
    * - ``spatial_tendons_props``
      - :func:`~isaaclab.sim.schemas.apply_spatial_tendon_properties`
-     - tendon attachment root / leaf prims
+     - tendon attachment root prims
 
 The tendon families are *tune-not-apply*: the tendon topology is authored in the source
-asset, so their writers only tune existing instances and never create them.
+asset, so their writers only tune existing instances and never create them. PhysX tendon
+fragments use ``instance_names`` to select one or more instances on each matching prim;
+``None`` (the default) broadcasts to all existing instances.
+
+A fixed tendon is split at the same boundary as the PhysX schemas: the root fragment owns
+whole-tendon dynamics and limits, while the axis fragment owns each joint's contribution.
+Prim-path matching chooses the joints and ``instance_names`` chooses the tendon on those
+joints:
+
+.. code-block:: python
+
+   from isaaclab_physx.sim.schemas import PhysxFixedTendonAxisCfg, PhysxFixedTendonCfg
+
+   fixed_tendons_props = {
+       "/joints/index_root": [
+           PhysxFixedTendonCfg(instance_names="index_finger", stiffness=10.0),
+           PhysxFixedTendonAxisCfg(instance_names="index_finger", gearing=[1.0], joint_axis=["rotX"]),
+       ],
+       "/joints/index_distal": [
+           PhysxFixedTendonAxisCfg(instance_names="index_finger", gearing=[-0.5], joint_axis=["rotX"]),
+       ],
+   }
 
 Targeting expressions
 ---------------------

source/isaaclab/changelog.d/ooctipus-tendon-instance-addressing.minor.rst

@@ -0,0 +1,12 @@
+Changed
+^^^^^^^
+
+* Extended :func:`~isaaclab.sim.schemas.apply_fixed_tendon_properties` to target both
+  ``PhysxTendonAxisRootAPI`` and ``PhysxTendonAxisAPI`` instances, allowing backend fragments to
+  configure whole fixed tendons and their individual joint-axis contributions separately.
+
+Fixed
+^^^^^
+
+* Fixed the legacy fixed- and spatial-tendon writers authoring properties under the applied API
+  type name. They now use the schema-owned ``physxTendon:<instance>:*`` namespace that PhysX reads.

source/isaaclab/isaaclab/sim/schemas/schemas.py

@@ -1629,18 +1629,27 @@ def modify_joint_drive_properties(
 """
 
 
+def _applied_schema_instance(applied_schema, schema_type: str) -> str | None:
+    """Return an applied multiple-apply schema's instance when its type matches exactly."""
+    applied_type, instance = Usd.SchemaRegistry.GetTypeNameAndInstance(str(applied_schema))
+    return instance if applied_type == schema_type and instance else None
+
+
 def _is_fixed_tendon_target(prim: Usd.Prim) -> bool:
-    """Whether a prim carries a fixed-tendon representation (PhysX multi-apply instance or MjcTendon prim)."""
+    """Whether a prim carries a fixed-tendon representation."""
     if prim.GetTypeName() == "MjcTendon":
         return True
-    return any("PhysxTendonAxisRootAPI" in s for s in prim.GetAppliedSchemas())
+    fixed_types = {"PhysxTendonAxisRootAPI", "PhysxTendonAxisAPI"}
+    return any(
+        _applied_schema_instance(schema, schema_type)
+        for schema in prim.GetAppliedSchemas()
+        for schema_type in fixed_types
+    )
 
 
 def _is_spatial_tendon_target(prim: Usd.Prim) -> bool:
-    """Whether a prim carries a spatial-tendon multi-apply instance."""
-    return any(
-        "PhysxTendonAttachmentRootAPI" in s or "PhysxTendonAttachmentLeafAPI" in s for s in prim.GetAppliedSchemas()
-    )
+    """Whether a prim carries a spatial-tendon root instance."""
+    return any(_applied_schema_instance(schema, "PhysxTendonAttachmentRootAPI") for schema in prim.GetAppliedSchemas())
 
 
 def apply_fixed_tendon_properties(
@@ -1651,8 +1660,8 @@ def apply_fixed_tendon_properties(
     The prims to author on are matched with :func:`~isaaclab.sim.utils.find_matching_prims`:
     ``prim_path_expr`` is a plain regular expression over whole prim paths, so ``[^/]+``
     selects one path segment and ``/World/Robot/.*`` every descendant of a prim. A matched prim is a
-    fixed-tendon target when it carries an applied ``PhysxTendonAxisRootAPI`` multi-apply
-    instance or is a ``MjcTendon`` prim.
+    fixed-tendon target when it carries an applied ``PhysxTendonAxisRootAPI`` or
+    ``PhysxTendonAxisAPI`` instance, or is a ``MjcTendon`` prim.
 
     Fixed tendons are a *tune-not-apply* family: the tendon topology is authored in the source
     asset, so this writer never creates instances -- it only dispatches each fragment via its
@@ -1740,27 +1749,33 @@ def modify_fixed_tendon_properties(
     # check if prim has fixed tendon applied on it or if the mjc tendon prim exiss
     applied_schemas = tendon_prim.GetAppliedSchemas()
     prim_type = tendon_prim.GetTypeName()
-    if not any("PhysxTendonAxisRootAPI" in s for s in applied_schemas) and prim_type != "MjcTendon":
+    if (
+        not any(_applied_schema_instance(schema, "PhysxTendonAxisRootAPI") for schema in applied_schemas)
+        and prim_type != "MjcTendon"
+    ):
         return False
 
     # resolve all available instances of the schema since it is multi-instance
     cfg = cfg.to_dict()
     if prim_type != "MjcTendon":
         for schema_name in applied_schemas:
-            if "PhysxTendonAxisRootAPI" not in schema_name:
+            instance_name = _applied_schema_instance(schema_name, "PhysxTendonAxisRootAPI")
+            if instance_name is None:
                 continue
-            # set into PhysX API by attribute prefix schema_name: (e.g. PhysxTendonAxisRootAPI:default:stiffness)
             for attr_name, value in cfg.items():
+                template = f"physxTendon:__INSTANCE_NAME__:{to_camel_case(attr_name, 'cC')}"
+                attribute = Usd.SchemaRegistry.MakeMultipleApplyNameInstance(template, instance_name)
                 safe_set_attribute_on_usd_prim(
                     tendon_prim,
-                    f"{schema_name}:{to_camel_case(attr_name, 'cC')}",
+                    attribute,
                     value,
                     camel_case=False,
                 )
     else:
         # NOTE: ``mjc:*`` branch (``MjcTendon`` prim) kept inline; future split candidate into isaaclab_newton.
         # only stiffness and damping in the cfg map to mjc attributes
-        for attr_name, value in cfg.items():
+        for attr_name in ("stiffness", "damping"):
+            value = cfg.get(attr_name)
             safe_set_attribute_on_usd_prim(
                 tendon_prim, f"mjc:{to_camel_case(attr_name, 'cC')}", value, camel_case=False
             )
@@ -1781,8 +1796,7 @@ def apply_spatial_tendon_properties(
     The prims to author on are matched with :func:`~isaaclab.sim.utils.find_matching_prims`:
     ``prim_path_expr`` is a plain regular expression over whole prim paths, so ``[^/]+``
     selects one path segment and ``/World/Robot/.*`` every descendant of a prim. A matched prim is a
-    spatial-tendon target when it carries an applied ``PhysxTendonAttachmentRootAPI`` or
-    ``PhysxTendonAttachmentLeafAPI`` multi-apply instance.
+    spatial-tendon target when it carries an applied ``PhysxTendonAttachmentRootAPI`` instance.
 
     Spatial tendons are a *tune-not-apply* family: the tendon topology is authored in the
     source asset, so this writer never creates instances -- it only dispatches each fragment
@@ -1837,16 +1851,14 @@ def modify_spatial_tendon_properties(
     through length and limit constraints. For instance, it can be used to set up an equality constraint
     between a driven and passive revolute joints.
 
-    The schema comprises of attributes that belong to the `PhysxTendonAxisRootAPI`_ schema.
+    The schema comprises attributes that belong to the `PhysxTendonAttachmentRootAPI`_ schema.
 
     .. note::
         This function is decorated with :func:`apply_nested` that sets the properties to all the prims
         (that have the schema applied on them) under the input prim path.
 
     .. _spatial tendon: https://nvidia-omniverse.github.io/PhysX/physx/5.4.1/_api_build/classPxArticulationSpatialTendon.html
-    .. _PhysxTendonAxisRootAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_tendon_axis_root_a_p_i.html
     .. _PhysxTendonAttachmentRootAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_tendon_attachment_root_a_p_i.html
-    .. _PhysxTendonAttachmentLeafAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_tendon_attachment_leaf_a_p_i.html
 
     Args:
         prim_path: The prim path to the tendon attachment.
@@ -1870,20 +1882,21 @@ def modify_spatial_tendon_properties(
     tendon_prim = stage.GetPrimAtPath(prim_path)
     # check if prim has spatial tendon applied on it
     applied_schemas = tendon_prim.GetAppliedSchemas()
-    has_spatial = any(
-        "PhysxTendonAttachmentRootAPI" in s or "PhysxTendonAttachmentLeafAPI" in s for s in applied_schemas
-    )
+    has_spatial = any(_applied_schema_instance(schema, "PhysxTendonAttachmentRootAPI") for schema in applied_schemas)
     if not has_spatial:
         return False
 
     cfg = cfg.to_dict()
     for schema_name in applied_schemas:
-        if "PhysxTendonAttachmentRootAPI" not in schema_name and "PhysxTendonAttachmentLeafAPI" not in schema_name:
+        instance_name = _applied_schema_instance(schema_name, "PhysxTendonAttachmentRootAPI")
+        if instance_name is None:
             continue
         for attr_name, value in cfg.items():
+            template = f"physxTendon:__INSTANCE_NAME__:{to_camel_case(attr_name, 'cC')}"
+            attribute = Usd.SchemaRegistry.MakeMultipleApplyNameInstance(template, instance_name)
             safe_set_attribute_on_usd_prim(
                 tendon_prim,
-                f"{schema_name}:{to_camel_case(attr_name, 'cC')}",
+                attribute,
                 value,
                 camel_case=False,
             )

source/isaaclab/isaaclab/sim/schemas/schemas_cfg.py

@@ -123,13 +123,12 @@ class SchemaFragment:
         left unchanged on the prim (partial update).
 
     .. important::
-        Every dataclass field other than :attr:`func` is authored as a USD attribute
-        ``<_usd_namespace>:<camelCase(field)>``. A fragment must not carry non-USD/bookkeeping
-        fields -- such state belongs on the spawner cfg or as a writer keyword argument (this is
-        why ``fix_root_link`` / ``ensure_drives_exist`` are not fragment fields). The generic
-        applier (:func:`~isaaclab.sim.schemas.apply_namespaced`) enforces the invariant: it raises
-        when a fragment has no ``_usd_namespace``, and unsupported (non-scalar) value types raise
-        when written.
+        For fragments using :func:`~isaaclab.sim.schemas.apply_namespaced`, every dataclass field
+        other than :attr:`func` is authored as ``<_usd_namespace>:<camelCase(field)>``. Irregular
+        schemas may use a custom applier for value conversion. The PhysX tendon fragments are a
+        narrow exception: their custom appliers consume ``instance_names`` to address an existing
+        multiple-apply schema instance and never author it. Do not add bookkeeping fields or treat
+        multiple-apply behavior as a generic core-fragment convention.
     """
 
     # -- Class metadata (not dataclass fields) --
@@ -226,10 +225,10 @@ class MeshCollisionFragment(SchemaFragment):
 class FixedTendonFragment(SchemaFragment):
     """Marker base for fixed-tendon fragments; types the ``fixed_tendons_props`` slot.
 
-    Fixed tendons are a *tune-not-apply* family: the applied ``PhysxTendonAxisRootAPI``
-    multi-instance schemas already exist on the prim (authored in the source asset), so the
-    family writer (:func:`~isaaclab.sim.schemas.apply_fixed_tendon_properties`) does not apply
-    any anchor schema; it only tunes the existing instances via each fragment's
+    Fixed tendons are a *tune-not-apply* family: the applied ``PhysxTendonAxisRootAPI`` and
+    ``PhysxTendonAxisAPI`` instances already exist on joint prims (authored in the source asset),
+    so the family writer (:func:`~isaaclab.sim.schemas.apply_fixed_tendon_properties`) does not
+    apply an anchor schema; it only tunes existing instances via each fragment's
     :attr:`~isaaclab.sim.schemas.SchemaFragment.func`.
     """
 
@@ -241,10 +240,9 @@ class SpatialTendonFragment(SchemaFragment):
     """Marker base for spatial-tendon fragments; types the ``spatial_tendons_props`` slot.
 
     Spatial tendons are a *tune-not-apply* family: the applied
-    ``PhysxTendonAttachmentRootAPI`` / ``PhysxTendonAttachmentLeafAPI`` multi-instance schemas
-    already exist on the prim (authored in the source asset), so the family writer
-    (:func:`~isaaclab.sim.schemas.apply_spatial_tendon_properties`) does not apply any anchor
-    schema; it only tunes the existing instances via each fragment's
+    ``PhysxTendonAttachmentRootAPI`` instances already exist on the prim (authored in the source
+    asset), so the family writer (:func:`~isaaclab.sim.schemas.apply_spatial_tendon_properties`)
+    does not apply an anchor schema; it only tunes existing root instances via each fragment's
     :attr:`~isaaclab.sim.schemas.SchemaFragment.func`.
     """
 

source/isaaclab/test/sim/test_schemas.py

@@ -934,13 +934,13 @@ def test_defining_articulation_properties_on_prim(setup_simulation):
 
 @pytest.mark.isaacsim_ci
 def test_multi_instance_schema_detection_on_tendon_joints(setup_simulation):
-    """Test that multi-instance PhysX tendon schemas are correctly detected via substring matching.
+    """Test that multi-instance PhysX tendon schema tokens are recognized with their instance suffixes.
 
     Multi-instance schemas (e.g. PhysxTendonAxisAPI, PhysxTendonAxisRootAPI) appear in
     GetAppliedSchemas() as 'SchemaName:instanceName' (e.g. 'PhysxTendonAxisAPI:inst0').
     An exact ``in list`` check fails because 'PhysxTendonAxisAPI' != 'PhysxTendonAxisAPI:inst0'.
-    This test ensures the substring-based detection used by modify_joint_drive_properties
-    and modify_fixed_tendon_properties handles multi-instance schemas correctly.
+    This test ensures both the joint-drive skip predicate and the fixed-tendon writer handle
+    multiple-apply schema tokens correctly.
 
     We call the unwrapped functions directly (via ``__wrapped__``) to bypass the
     ``@apply_nested`` decorator, which traverses children and does not return the