Refine cable self-collision resolution and coverage

Resolve welded rod-graph self-collision from the values member curves
actually author instead of the resolver's injected default. Any authored
newton:selfCollisionEnabled=False disables the whole graph, and the mixed
authoring warning fires only when authored values genuinely disagree, so
welding no longer lets an unauthored sibling's default override an authored
value. This matches the single-curve and rigid-articulation paths.

Skip the self-collision filter when the cable has collision disabled, so a
non-colliding cable no longer emits filter pairs for shapes the broad phase
never tests. Resolve and warn only for a colliding graph too, so a
non-colliding welded graph with disagreeing authored values no longer emits
a spurious mixed-authoring warning.

Cover the enable_self_collisions argument, the physxArticulation fallback,
the non-colliding-cable skip, and the authored-beats-default paths. Document
cable self-collision resolution and the welded-graph rule, and note the
enable_self_collisions argument in the changelog entry.

Author: mmichelis

CHANGELOG.md

@@ -91,7 +91,7 @@
 - Fix masked `SolverCoupledProxy.reset()` calls clearing proxy feedback history for unselected worlds.
 - Fix hydroelastic primitive texture SDF generation to sample analytic primitive distances instead of temporary tessellated meshes. (#3239)
 - Fix MJCF, URDF, and USD imports rendering collision-only bodies as visuals when the asset authors visual geometry elsewhere. (#3291)
-- Fix `ModelBuilder.add_usd()` ignoring `newton:selfCollisionEnabled` on imported cables; a cable articulation with self-collision disabled now filters collisions between its non-adjacent segments.
+- Fix `ModelBuilder.add_usd()` ignoring cable self-collision settings: `newton:selfCollisionEnabled` on a cable prim and the `enable_self_collisions` argument now both apply, so a cable articulation with self-collision disabled filters collisions between its non-adjacent segments.
 - Fix `SchemaResolverPhysx` reading every D6 translational limit gain from the `linear` instance instead of its `transX`, `transY`, or `transZ` instance.
 - Fix USD capsule, cylinder, and cone visuals and sites without authored `radius`/`height` to use the UsdGeom schema fallbacks, matching collision shapes.
 - Fix `ViewerUSD` texture consumers observing partially written PNGs by publishing generated textures atomically (#3288)

docs/concepts/usd_parsing.rst

@@ -144,7 +144,10 @@ Known gaps of the experimental importer, tracked as follow-ups:
   (dynamics only, per the proposal). Cloth and volume deformables cannot disable particle
   collision in Newton yet: they warn and import colliding. A welded cable graph shares one
   shape configuration, so any collision-enabled member curve makes the whole graph collide
-  (mixed authoring warns).
+  (mixed authoring warns). Self-collision resolves with the opposite polarity: one member
+  curve authoring ``newton:selfCollisionEnabled = false`` disables self-collision for the
+  whole graph (conflicting authored values warn), and once any member authors a value the
+  ``enable_self_collisions`` argument no longer applies to that graph.
 * **Collision and graphics geometry** -- separate collision or render geometry under a
   deformable body is not simulated or driven (embedding is not implemented): untagged
   PointBased graphics geometry warns and is skipped (a static import would leave a frozen
@@ -217,6 +220,12 @@ A welded rod graph gets one articulation per connected component; each of its cu
 own body range but shares that articulation. Attachment joints that tie a cable to other bodies
 close a loop, so they stay outside the articulation.
 
+Self-collision is resolved per articulation from ``newton:selfCollisionEnabled`` authored on
+the curve prim itself (see the articulation remapping below). Disabling it filters collisions
+between the articulation's non-adjacent segments; adjacent segments are already filtered by the
+cable joints. Sibling curves of a multi-curve prim are separate articulations, so the filter
+never spans them.
+
 .. code-block:: python
 
     result = builder.add_usd("cables.usda", return_deformable_results=True)
@@ -359,7 +368,7 @@ The table below shows PhysX attribute remapping examples:
 
 **Newton articulation remapping:**
 
-On articulation root prims (with ``PhysicsArticulationRootAPI`` or ``NewtonArticulationRootAPI``), the following is resolved:
+On articulation root prims (with ``PhysicsArticulationRootAPI`` or ``NewtonArticulationRootAPI``) and on cable ``BasisCurves`` prims, the following is resolved:
 
 .. list-table:: Newton Articulation Remapping
    :header-rows: 1

newton/_src/utils/import_usd_deformable_cable.py

@@ -16,6 +16,7 @@
 import math
 import warnings
 from dataclasses import replace
+from typing import TYPE_CHECKING
 
 import warp as wp
 
@@ -42,12 +43,16 @@
     _warn_unsupported_rest_fields,
 )
 
+if TYPE_CHECKING:
+    from ..sim.builder import ModelBuilder
 
-def _apply_cable_self_collision_filter(builder, bodies, self_collision_enabled: bool) -> None:
+
+def _apply_cable_self_collision_filter(builder: ModelBuilder, bodies: list[int], self_collision_enabled: bool) -> None:
     """Filter all shape pairs among a cable articulation's bodies when self-collision is disabled.
 
-    Adjacent segments are already filtered by the CABLE joints (``collision_filter_parent``);
-    this extends filtering to the non-adjacent pairs, mirroring the general rigid importer.
+    Like the rigid importer's self-collision filtering, this emits every body pair, including
+    the adjacent ones the CABLE joints already filter (``collision_filter_parent``); the
+    duplicates are deduplicated when the filter pairs are consumed.
     """
     if self_collision_enabled or len(bodies) < 2:
         return
@@ -434,28 +439,34 @@ def global_node(local: tuple[str, int]) -> int:
             body_frame_origin="com",
         )
 
-        # One rod graph is one articulation, so resolve self-collision per component: a welded graph
-        # disables it if ANY member curve prim authors newton:selfCollisionEnabled=False.
-        self_collision_states = {
-            key: bool(
-                ctx.resolver.get_value(
+        # Only a colliding graph can self-collide, so resolve and filter self-collision (and warn
+        # on mixed authoring) only then. One rod graph is one articulation, so resolve from the
+        # values member curves actually author (a None resolver means unauthored): any authored
+        # False disables the graph, and unauthored curves stay neutral so welding cannot let a
+        # default override an authored value. The default below only suppresses the
+        # unresolved-value diagnostic.
+        if collision_enabled:
+            authored_self_collisions: list[bool] = []
+            for key in comp_paths:
+                value, resolver = ctx.resolver.get_value_with_resolver(
                     curve_recs[key].prim,
                     prim_type=PrimType.ARTICULATION,
                     key="self_collision_enabled",
                     default=ctx.enable_self_collisions,
                     verbose=verbose,
                 )
+                if resolver is not None:
+                    authored_self_collisions.append(bool(value))
+            graph_self_collision = (
+                all(authored_self_collisions) if authored_self_collisions else ctx.enable_self_collisions
             )
-            for key in comp_paths
-        }
-        graph_self_collision = all(self_collision_states.values())
-        if not graph_self_collision and any(self_collision_states.values()):
-            warnings.warn(
-                f"cable graph '{cid}': welded cables mix self-collision-enabled and "
-                f"self-collision-disabled curves; the whole graph disables self-collision.",
-                stacklevel=2,
-            )
-        _apply_cable_self_collision_filter(builder, body_ids, graph_self_collision)
+            if len(set(authored_self_collisions)) > 1:
+                warnings.warn(
+                    f"cable graph '{cid}': welded cables mix self-collision-enabled and "
+                    f"self-collision-disabled curves; the whole graph disables self-collision.",
+                    stacklevel=2,
+                )
+            _apply_cable_self_collision_filter(builder, body_ids, graph_self_collision)
 
         # Partition graph bodies back to their owning curve, and rebuild the per-prim anchor
         # maps the curve-to-xform attachment pass reads (point index / segment index -> body).
@@ -674,7 +685,7 @@ def _deformable_import_cable(ctx: _DeformableImportContext, consumed_cable_curve
                 prim_type=PrimType.ARTICULATION,
                 key="self_collision_enabled",
                 default=ctx.enable_self_collisions,
-                verbose=ctx.verbose,
+                verbose=verbose,
             )
         )
 
@@ -769,8 +780,8 @@ def _deformable_import_cable(ctx: _DeformableImportContext, consumed_cable_curve
                 wrap_in_articulation=True,
                 body_frame_origin="com",
             )
-            # This curve is its own articulation, so filter its own segments' self-collisions here.
-            _apply_cable_self_collision_filter(builder, bodies, self_collision_enabled)
+            if collision_enabled:
+                _apply_cable_self_collision_filter(builder, bodies, self_collision_enabled)
             cable_bodies.extend(bodies)
             cable_joints.extend(joints)
             cable_point_runs.append((start, n, bodies))

newton/_src/utils/import_usd_deformable_utils.py

@@ -1023,6 +1023,6 @@ class _DeformableImportContext:
     path_attachment_map: dict
     path_attachment_attrs: dict
     # Default for self-collision when an articulation authors no newton:selfCollisionEnabled.
-    enable_self_collisions: bool = True
+    enable_self_collisions: bool
     # Filled by _scout_deformable_prims so the passes iterate buckets instead of the stage.
     prims: _DeformablePrimBuckets = field(default_factory=_DeformablePrimBuckets)

newton/tests/test_import_usd_deformable_cable.py

@@ -31,14 +31,14 @@ class TestUSDDeformableCable(unittest.TestCase):
     """Curve-deformable (cable) parsing into rods of capsule bodies + cable joints."""
 
     @staticmethod
-    def _author_attached_cable_pair(*, gap, stiffness=None, damping=None):
+    def _author_attached_cable_pair(*, gap, stiffness=None, damping=None, collision=True):
         """Two 4-point cables separated by ``gap`` in y with a point->point attachment
         (P0 of B onto P0 of A); returns the stage."""
         stage = _deformable_stage()
         pts_a = [(0.0, 0.0, 1.0), (0.1, 0.0, 1.0), (0.2, 0.0, 1.0), (0.3, 0.0, 1.0)]
         pts_b = [(0.0, gap, 1.0), (0.1, gap, 1.0), (0.2, gap, 1.0), (0.3, gap, 1.0)]
-        _add_cable_curve(stage, "/World/CableA", pts_a)
-        _add_cable_curve(stage, "/World/CableB", pts_b)
+        _add_cable_curve(stage, "/World/CableA", pts_a, collision=collision)
+        _add_cable_curve(stage, "/World/CableB", pts_b, collision=collision)
         _add_physics_attachment(
             stage,
             "/World/Junction",
@@ -53,6 +53,13 @@ def _author_attached_cable_pair(*, gap, stiffness=None, damping=None):
         )
         return stage
 
+    @staticmethod
+    def _shape_pair(builder, body_a, body_b):
+        """Canonical (min, max) shape-filter pair for the first shapes of two bodies."""
+        s1 = builder.body_shapes[body_a][0]
+        s2 = builder.body_shapes[body_b][0]
+        return (min(s1, s2), max(s1, s2))
+
     def test_attachment_weld_policy_rejects_compliant_or_apart(self):
         """A curve-to-curve attachment welds only when hard AND coincident: a compliant
         (zero or finite stiffness) or spatially-apart junction leaves two independent
@@ -947,72 +954,120 @@ def test_cable_self_collision_disabled_filters_non_adjacent_pairs(self):
         """newton:selfCollisionEnabled=False filters non-adjacent cable segment shape pairs.
 
         Adjacent segments are already filtered by the CABLE joints; the flag extends the
-        filtering to non-adjacent pairs, mirroring the general rigid importer. The default
-        (flag True or unauthored) leaves those pairs unfiltered.
+        filtering to non-adjacent pairs, mirroring the general rigid importer. An authored value
+        beats the ``enable_self_collisions`` argument, which only applies when the cable authors
+        nothing, and a non-colliding cable emits no filter pairs at all.
         """
         from pxr import Sdf
 
         # 5 points -> 4 segment bodies, so there are non-adjacent pairs to check.
         pts = [(0.0, 0.0, 1.0), (0.1, 0.0, 1.0), (0.2, 0.0, 1.0), (0.3, 0.0, 1.0), (0.4, 0.0, 1.0)]
-        for case, self_collision in (("disabled", False), ("enabled", True), ("unauthored", None)):
+        for case, authored, default, collision, expect_filtered in (
+            ("authored_disabled", False, True, True, True),
+            ("unauthored", None, True, True, False),
+            ("default_disabled", None, False, True, True),
+            ("authored_beats_default", True, False, True, False),
+            ("non_colliding", False, True, False, False),
+        ):
             with self.subTest(case=case):
                 stage = _deformable_stage()
-                curve = _add_cable_curve(stage, "/World/Cable", pts)
-                if self_collision is not None:
+                curve = _add_cable_curve(stage, "/World/Cable", pts, collision=collision)
+                if authored is not None:
                     curve.GetPrim().CreateAttribute("newton:selfCollisionEnabled", Sdf.ValueTypeNames.Bool).Set(
-                        self_collision
+                        authored
                     )
                 builder = newton.ModelBuilder()
-                builder.add_usd(stage)
+                builder.add_usd(stage, enable_self_collisions=default)
                 b0, b1 = group_range(builder, "cable", "/World/Cable", "body")
                 self.assertEqual(b1 - b0, 4)
                 # A non-adjacent segment pair (bodies b0 and b0+2).
-                s1 = builder.body_shapes[b0][0]
-                s2 = builder.body_shapes[b0 + 2][0]
-                pair = (min(s1, s2), max(s1, s2))
+                pair = self._shape_pair(builder, b0, b0 + 2)
                 pairs = set(builder.shape_collision_filter_pairs)
-                if case == "disabled":
+                if expect_filtered:
                     self.assertIn(pair, pairs)
                 else:
                     self.assertNotIn(pair, pairs)
+                if not collision:
+                    # Non-colliding shapes never reach the broad phase, so the filter is skipped
+                    # entirely (a colliding cable always emits the adjacent joint pairs).
+                    self.assertEqual(pairs, set())
+
+    def test_cable_self_collision_physx_fallback_needs_resolver(self):
+        """physxArticulation:enabledSelfCollisions gates a cable only with the PhysX resolver.
+
+        The default resolver list is Newton-only, so the PhysX articulation attribute is
+        silently ignored unless the caller opts in via ``schema_resolvers``.
+        """
+        from pxr import Sdf
+
+        # 5 points -> 4 segment bodies, so there is a non-adjacent pair to check.
+        pts = [(0.0, 0.0, 1.0), (0.1, 0.0, 1.0), (0.2, 0.0, 1.0), (0.3, 0.0, 1.0), (0.4, 0.0, 1.0)]
+
+        def non_adjacent_pair_filtered(**add_usd_kwargs):
+            stage = _deformable_stage()
+            curve = _add_cable_curve(stage, "/World/Cable", pts)
+            curve.GetPrim().CreateAttribute("physxArticulation:enabledSelfCollisions", Sdf.ValueTypeNames.Bool).Set(
+                False
+            )
+            builder = newton.ModelBuilder()
+            builder.add_usd(stage, **add_usd_kwargs)
+            b0, _ = group_range(builder, "cable", "/World/Cable", "body")
+            return self._shape_pair(builder, b0, b0 + 2) in set(builder.shape_collision_filter_pairs)
+
+        self.assertTrue(non_adjacent_pair_filtered(schema_resolvers=[SchemaResolverPhysx()]))
+        self.assertFalse(non_adjacent_pair_filtered())
 
     def test_welded_graph_self_collision_disabled_filters_non_adjacent_pairs(self):
         """A welded cable graph honors newton:selfCollisionEnabled=False on any member curve.
 
         Disabling self-collision on one welded member filters non-adjacent segment shape pairs
         across the whole graph articulation (both within a curve and between welded curves), and
-        the importer warns that the mixed authoring resolves to self-collision disabled.
+        the importer warns only when colliding members author disagreeing values. Only authored
+        values count, so an unauthored sibling never lets the ``enable_self_collisions`` default
+        override them, and a non-colliding graph emits no filter pairs and no warning at all.
         """
         from pxr import Sdf
 
-        for case, author in (("disabled", True), ("default", False)):
+        for case, author_a, author_b, default, collision, expect_filtered in (
+            ("disabled", False, None, True, True, True),
+            ("all_disabled", False, False, True, True, True),
+            ("mixed", False, True, True, True, True),
+            ("default", None, None, True, True, False),
+            ("authored_beats_default", True, None, False, True, False),
+            ("non_colliding_mixed", False, True, True, False, False),
+        ):
             with self.subTest(case=case):
                 # Hard, coincident junction welds CableA and CableB into one graph articulation.
-                stage = self._author_attached_cable_pair(gap=0.0)
-                if author:
-                    stage.GetPrimAtPath("/World/CableA").CreateAttribute(
-                        "newton:selfCollisionEnabled", Sdf.ValueTypeNames.Bool
-                    ).Set(False)
+                stage = self._author_attached_cable_pair(gap=0.0, collision=collision)
+                for path, authored in (("/World/CableA", author_a), ("/World/CableB", author_b)):
+                    if authored is not None:
+                        stage.GetPrimAtPath(path).CreateAttribute(
+                            "newton:selfCollisionEnabled", Sdf.ValueTypeNames.Bool
+                        ).Set(authored)
                 builder = newton.ModelBuilder()
-                if author:
-                    # Members disagree (CableB unauthored -> default True), so the importer warns.
-                    with self.assertWarnsRegex(UserWarning, "disables self-collision"):
-                        builder.add_usd(stage)
-                else:
-                    builder.add_usd(stage)
+                with warnings.catch_warnings(record=True) as caught:
+                    warnings.simplefilter("always")
+                    builder.add_usd(stage, enable_self_collisions=default)
+                # Only genuinely disagreeing authored values warn.
+                warned = any("disables self-collision" in str(w.message) for w in caught)
+                self.assertEqual(warned, case == "mixed")
                 self.assertEqual(builder.articulation_count, 1)
                 a0, _ = group_range(builder, "cable", "/World/CableA", "body")
                 b0, _ = group_range(builder, "cable", "/World/CableB", "body")
                 pairs = set(builder.shape_collision_filter_pairs)
                 # A within-curve non-adjacent pair and a cross-curve non-adjacent pair.
                 within = self._shape_pair(builder, a0, a0 + 2)
                 cross = self._shape_pair(builder, a0 + 2, b0 + 2)
-                if case == "disabled":
+                if expect_filtered:
                     self.assertIn(within, pairs)
                     self.assertIn(cross, pairs)
                 else:
                     self.assertNotIn(within, pairs)
                     self.assertNotIn(cross, pairs)
+                if not collision:
+                    # Non-colliding shapes never reach the broad phase, so the filter is skipped
+                    # entirely (a colliding graph always emits the adjacent joint pairs).
+                    self.assertEqual(pairs, set())
 
     def test_self_collision_disabled_does_not_filter_across_curves_in_one_prim(self):
         """A multi-curve BasisCurves prim filters each curve's own segments, not across curves.
@@ -1058,13 +1113,6 @@ def test_self_collision_disabled_does_not_filter_across_curves_in_one_prim(self)
         # Across the two curves (separate articulations), nothing is filtered.
         self.assertNotIn(self._shape_pair(builder, b0, b0 + 3), pairs)
 
-    @staticmethod
-    def _shape_pair(builder, body_a, body_b):
-        """Canonical (min, max) shape-filter pair for the first shapes of two bodies."""
-        s1 = builder.body_shapes[body_a][0]
-        s2 = builder.body_shapes[body_b][0]
-        return (min(s1, s2), max(s1, s2))
-
     def test_neg_inf_junction_stiffness_does_not_weld(self):
         """-inf is the material sentinel, not the attachment one (+inf = hard): a
         junction authoring -inf stiffness is nonconforming and must not weld the