Support attached cable endpoints in USD

Detect the attachment before rigid articulations are finalized so its
target stays in the active contiguous joint range.

Build rods outward from either attached endpoint to preserve
parent-before-child joint order. Cover standalone bodies and floating-
and fixed-base robots with unrelated bodies imported afterward.

Author: eric-heiden

newton/_src/sim/builder.py

@@ -8650,12 +8650,15 @@ def _add_rod_graph(
         junction_collision_filter: bool = True,
         color: Vec3 | None = None,
         body_frame_origin: Literal["start", "com"] | None = None,
+        articulation_root_node: int | None = None,
         articulation_root_joint_factory: Callable[[int, Transform], int] | None = None,
     ) -> tuple[list[int], list[int]]:
         """Build a rod graph with an optional importer-defined articulation root joint.
 
         The callback runs after the root body exists and before the rod joints are created. Public
-        callers use :meth:`add_rod_graph`, which creates a free joint to the world instead.
+        callers use :meth:`add_rod_graph`, which creates a free joint to the world instead. An
+        importer may select the graph node where traversal starts so the resulting joints follow
+        parent-before-child order from an attached endpoint.
         """
         if cfg is None:
             cfg = self.default_shape_cfg
@@ -8682,6 +8685,13 @@ def _add_rod_graph(
 
         num_nodes = len(node_positions)
         num_edges = len(edges)
+        if articulation_root_node is not None:
+            if articulation_root_joint_factory is None:
+                raise ValueError("add_rod_graph: articulation_root_node requires an articulation root joint factory")
+            if articulation_root_node < 0 or articulation_root_node >= num_nodes:
+                raise ValueError(
+                    f"add_rod_graph: articulation_root_node must be in [0, {num_nodes}), got {articulation_root_node}"
+                )
         if quaternions is not None and len(quaternions) != num_edges:
             raise ValueError(
                 f"add_rod_graph: quaternions must have {num_edges} elements for {num_edges} edges, "
@@ -8856,7 +8866,17 @@ def _build_joints_forest() -> list[int]:
             visited = [False] * num_edges
             component_index = 0
 
-            for start_edge in range(num_edges):
+            start_edges = list(range(num_edges))
+            if articulation_root_node is not None:
+                root_edges = node_incidence[articulation_root_node]
+                if not root_edges:
+                    raise ValueError(
+                        f"add_rod_graph: articulation_root_node {articulation_root_node} has no incident edge"
+                    )
+                start_edges.remove(root_edges[0])
+                start_edges.insert(0, root_edges[0])
+
+            for start_edge in start_edges:
                 if visited[start_edge]:
                     continue
 
@@ -8871,9 +8891,14 @@ def _build_joints_forest() -> list[int]:
                         )
                     root_joint = self.add_joint_free(child=edge_bodies[start_edge], label=root_label)
                 else:
+                    root_node = (
+                        articulation_root_node
+                        if component_index == 0 and articulation_root_node is not None
+                        else edge_u[start_edge]
+                    )
                     root_joint = articulation_root_joint_factory(
                         edge_bodies[start_edge],
-                        _edge_anchor_xform(start_edge, edge_u[start_edge]),
+                        _edge_anchor_xform(start_edge, root_node),
                     )
                 component_joints: list[int] = [root_joint]
                 component_edges: list[int] = []

newton/_src/utils/import_usd.py

@@ -61,7 +61,11 @@
     _deformable_import_element_collision_filters,
     _deformable_remap_collapsed,
 )
-from .import_usd_deformable_cable import _deformable_import_cable, _deformable_prepare_cable_topology
+from .import_usd_deformable_cable import (
+    _deformable_import_cable,
+    _deformable_prepare_cable_topology,
+    _read_cable_attachment_endpoint,
+)
 from .import_usd_deformable_cloth import _deformable_import_cloth
 from .import_usd_deformable_utils import (
     _LOADABLE_VISUAL_TYPE_NAMES_LOWER,
@@ -2824,6 +2828,45 @@ def _resolve_contact_attr(key, _prim=prim):
     # This allows us to parse orphan joints (joints not included in any articulation)
     # even when articulations are present in the USD.
     processed_joints: set[str] = set()
+
+    cable_attachment_target_body_paths: set[str] = set()
+    if _deformable_prims.cables and _deformable_prims.attachments:
+        cable_topology: dict[str, tuple[int, bool]] = {}
+        for cable_prim in _deformable_prims.cables:
+            curves = UsdGeom.BasisCurves(cable_prim)
+            vertex_counts = curves.GetCurveVertexCountsAttr().Get() or []
+            if len(vertex_counts) != 1:
+                continue
+            cable_topology[str(cable_prim.GetPath())] = (
+                int(vertex_counts[0]),
+                curves.GetWrapAttr().Get() == UsdGeom.Tokens.periodic,
+            )
+
+        attachments_by_cable: dict[str, list[Usd.Prim]] = {}
+        for attachment_prim in _deformable_prims.attachments:
+            cable_path = _get_first_target(attachment_prim, "physics:src0")
+            if cable_path in cable_topology:
+                attachments_by_cable.setdefault(cable_path, []).append(attachment_prim)
+
+        for cable_path, attachment_prims in attachments_by_cable.items():
+            if len(attachment_prims) != 1:
+                continue
+            attachment_prim = attachment_prims[0]
+            point_count, closed = cable_topology[cable_path]
+            if _read_cable_attachment_endpoint(attachment_prim, deformable_read, point_count, closed) is None:
+                continue
+            target_path = _get_first_target(attachment_prim, "physics:src1")
+            target_prim = stage.GetPrimAtPath(target_path)
+            if not target_prim or not target_prim.IsValid():
+                continue
+            current_prim = target_prim
+            while current_prim and current_prim.IsValid():
+                current_path = str(current_prim.GetPath())
+                if current_path in body_specs:
+                    cable_attachment_target_body_paths.add(current_path)
+                    break
+                current_prim = current_prim.GetParent()
+
     authored_articulation_root_paths = [
         str(prim.GetPath())
         for prim in Usd.PrimRange(stage.GetPrimAtPath(root_path), Usd.TraverseInstanceProxies())
@@ -2837,10 +2880,20 @@ def _resolve_contact_attr(key, _prim=prim):
     if UsdPhysics.ObjectType.Articulation in ret_dict:
         paths, articulation_descs = ret_dict[UsdPhysics.ObjectType.Articulation]
 
+        articulation_entries = list(zip(paths, articulation_descs, strict=False))
+        target_articulations = [
+            index
+            for index, (_path, desc) in enumerate(articulation_entries)
+            if cable_attachment_target_body_paths.intersection(str(body) for body in desc.articulatedBodies)
+        ]
+        if len(target_articulations) == 1:
+            target_articulation = articulation_entries.pop(target_articulations[0])
+            articulation_entries.append(target_articulation)
+
         articulation_id = builder.articulation_count
         parent_prim = None
         body_data = {}
-        for path, desc in zip(paths, articulation_descs, strict=False):
+        for path, desc in articulation_entries:
             if warn_invalid_desc(path, desc):
                 continue
             articulation_path = str(path)
@@ -4492,11 +4545,26 @@ def _aggregate_recorded_mass_properties(body_path: str, body_density: float | No
     else:
         bodies_to_articulate = new_bodies
 
-    if bodies_to_articulate:
+    cable_attachment_target_bodies = [
+        path_body_map[path] for path in cable_attachment_target_body_paths if path in path_body_map
+    ]
+    if len(cable_attachment_target_bodies) == 1:
+        cable_attachment_target_body = cable_attachment_target_bodies[0]
+        bodies_before_cables = (
+            [cable_attachment_target_body] if cable_attachment_target_body in bodies_to_articulate else []
+        )
+        bodies_after_cables = [body_id for body_id in bodies_to_articulate if body_id != cable_attachment_target_body]
+    else:
+        bodies_before_cables = bodies_to_articulate
+        bodies_after_cables = []
+
+    def add_base_articulations(body_ids: list[int]) -> None:
+        if not body_ids:
+            return
         if parent_body != -1:
             # When parent_body is specified, manually add joints to floating bodies with correct parent
             joint_children = set(builder.joint_child)
-            for body_id in bodies_to_articulate:
+            for body_id in body_ids:
                 if body_id in joint_children:
                     continue  # Already has a joint
                 if builder.body_mass[body_id] <= 0:
@@ -4519,7 +4587,7 @@ def _aggregate_recorded_mass_properties(body_path: str, body_density: float | No
                 )
         else:
             joint_children = set(builder.joint_child)
-            for body_id in bodies_to_articulate:
+            for body_id in body_ids:
                 if body_id in joint_children:
                     continue
                 if builder.body_mass[body_id] <= 0:
@@ -4544,6 +4612,10 @@ def _aggregate_recorded_mass_properties(body_path: str, body_density: float | No
                 else:
                     builder.add_articulation([joint_id], label=body_path)
 
+    # Articulation joints occupy a contiguous range. Create the attached body's base joint
+    # immediately before the cable joints, then add unrelated base joints after the cable.
+    add_base_articulations(bodies_before_cables)
+
     def initialize_free_joint_velocities() -> None:
         imported_bodies = set(path_body_map.values())
         for joint_id, joint_type in enumerate(builder.joint_type):
@@ -4576,8 +4648,8 @@ def initialize_free_joint_velocities() -> None:
             qd_start = builder.joint_qd_start[joint_id]
             builder.joint_qd[qd_start : qd_start + 6] = [*linear_velocity, *angular_velocity]
 
-    # Build deformables after rigid bodies, collider-mass computation, and the floating-body
-    # base-joint pass so physical attachment targets and their root joints already exist.
+    # Build deformables after rigid bodies and collider-mass computation so physical attachment
+    # targets already exist.
     # Volume deformables (TetMesh -> soft body). PhysicsVolumeDeformableSimAPI (or a
     # PhysicsDeformableBodyAPI) opts into the mass precedence; a bare TetMesh stays legacy.
     # Mass precedence (proposal): per-point physics:masses > body mass > body density
@@ -4656,6 +4728,8 @@ def initialize_free_joint_velocities() -> None:
             if _filter_prim and _filter_prim.IsValid():
                 _collect_filtered_pairs(_filter_prim)
 
+    add_base_articulations(bodies_after_cables)
+
     def _resolve_collision_shape_ids(path: str) -> tuple[list[int], str | None]:
         """Resolve a filtered-pair endpoint to Newton shape indices, or an unsupported reason.
 

newton/_src/utils/import_usd_deformable_cable.py

@@ -74,6 +74,7 @@
 @dataclass(frozen=True, slots=True)
 class _CableArticulationRoot:
     attachment_path: str
+    cable_point: int
     parent_body: int
     parent_anchor: wp.vec3
 
@@ -97,6 +98,34 @@ def _add_cable_articulation_root_joint(
     return joint
 
 
+def _read_cable_attachment_endpoint(prim, deformable_read, point_count: int, closed: bool) -> int | None:
+    """Return the attached endpoint when a hard attachment can root an open cable articulation."""
+    if closed:
+        return None
+    if str(deformable_read(prim, "type0") or "") != "point":
+        return None
+    if str(deformable_read(prim, "type1") or "") != "xform":
+        return None
+    point_indices = [int(index) for index in (deformable_read(prim, "indices0") or [])]
+    if len(point_indices) != 1 or point_indices[0] not in (0, point_count - 1):
+        return None
+    if deformable_read(prim, "indices1"):
+        return None
+    if len(_attachment_vec3_list(deformable_read(prim, "coords1"))) > 1:
+        return None
+
+    enabled = deformable_read(prim, "attachmentEnabled")
+    if enabled is not None and not bool(enabled):
+        return None
+    stiffness = deformable_read(prim, "stiffness")
+    if stiffness is not None and float(stiffness) != math.inf:
+        return None
+    damping = deformable_read(prim, "damping")
+    if damping is not None and (not math.isfinite(float(damping)) or float(damping) < 0.0):
+        return None
+    return point_indices[0]
+
+
 # Thickness attributes in resolution order: the current revision first, then the deprecated name.
 _CABLE_THICKNESS_ATTRS = ("curvesThickness", "thickness")
 _NEWTON_CURVE_DAMPING_ATTRS = (
@@ -393,34 +422,15 @@ def _read_cable_articulation_root(
 ) -> _CableArticulationRoot | None:
     """Return an attachment that can connect the cable articulation to its parent.
 
-    The supported case is a hard attachment from the cable's first endpoint to the world or a
+    The supported case is a hard attachment from a cable endpoint to the world or a
     transform. If the transform belongs to a rigid body, that body must be in the most recently
     added articulation because articulation joints occupy contiguous ranges.
     """
     deformable_read = ctx.deformable_read
-    if cable.closed:
-        return None
-    if str(deformable_read(prim, "type0") or "") != "point":
-        return None
-    if str(deformable_read(prim, "type1") or "") != "xform":
-        return None
-    if [int(index) for index in (deformable_read(prim, "indices0") or [])] != [0]:
-        return None
-    if deformable_read(prim, "indices1"):
+    cable_point = _read_cable_attachment_endpoint(prim, deformable_read, len(cable.positions), cable.closed)
+    if cable_point is None:
         return None
     target_points = _attachment_vec3_list(deformable_read(prim, "coords1"))
-    if len(target_points) > 1:
-        return None
-
-    enabled = deformable_read(prim, "attachmentEnabled")
-    if enabled is not None and not bool(enabled):
-        return None
-    stiffness = deformable_read(prim, "stiffness")
-    if stiffness is not None and float(stiffness) != math.inf:
-        return None
-    damping = deformable_read(prim, "damping")
-    if damping is not None and (not math.isfinite(float(damping)) or float(damping) < 0.0):
-        return None
 
     target_point = target_points[0] if target_points else wp.vec3(0.0, 0.0, 0.0)
     target = _resolve_attachment_target(ctx, target_path, target_point)
@@ -429,7 +439,7 @@ def _read_cable_articulation_root(
     parent_body, parent_anchor = target
     if parent_body >= 0 and parent_body not in bodies_in_latest_articulation:
         return None
-    return _CableArticulationRoot(str(prim.GetPath()), parent_body, parent_anchor)
+    return _CableArticulationRoot(str(prim.GetPath()), cable_point, parent_body, parent_anchor)
 
 
 def _deformable_prepare_cable_topology(
@@ -438,7 +448,7 @@ def _deformable_prepare_cable_topology(
     """Prepare cable connectivity that must be known before creating cable joints.
 
     Hard attachments between coincident cable points become shared nodes in one rod graph. For an
-    open cable with one hard attachment at its first endpoint, that attachment connects the cable
+    open cable with one hard attachment at an endpoint, that attachment connects the cable
     articulation to the world or a rigid body. Other attachments remain separate constraints.
 
     Returns the cable paths built as shared rod graphs, the attachment paths represented by those
@@ -859,7 +869,7 @@ def _deformable_import_cable(
     """Import single-curve cable deformables (linear ``GeomBasisCurves`` -> rod via ``add_rod``).
 
     Curves already built as a rod graph are skipped. Each remaining cable is placed in an
-    articulation. A physical attachment at the first endpoint provides the root joint when
+    articulation. A physical attachment at either endpoint provides the root joint when
     possible; otherwise the cable receives a free joint to the world.
     """
     from pxr import UsdGeom
@@ -882,7 +892,11 @@ def _deformable_import_cable(
 
     if not (root_prim and root_prim.IsValid()):
         return
-    for prim in ctx.prims.cables:
+    cable_prims = sorted(
+        ctx.prims.cables,
+        key=lambda prim: str(prim.GetPath()) not in cable_articulation_roots,
+    )
+    for prim in cable_prims:
         path = str(prim.GetPath())
         if path in cables_in_shared_graphs:
             continue  # already built as part of a welded rod graph
@@ -1069,6 +1083,7 @@ def _deformable_import_cable(
                     label=label,
                     wrap_in_articulation=True,
                     body_frame_origin="com",
+                    articulation_root_node=articulation_root.cable_point,
                     articulation_root_joint_factory=partial(
                         _add_cable_articulation_root_joint,
                         builder,