Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions agent_context/topics/simulation-system/deformables.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,14 @@ Focused coverage: `tests/sim/test_deformable_cfg.py`,
`CableObjectCfg` and `CableObject(BatchEntity)` are independent of particle-set
deformables. `SimulationManager.add_cable_object()` lowers through
`spawn/descriptors.py` into `CableDesc`, declares in the existing `SpawnScene`,
and binds the same facade in place during `prepare()`. Backend capabilities
reject Default, CPU, other Newton solvers and gradient mode; use DexUni on CUDA.
and binds the same facade in place during `prepare()`. `add_usd(UsdImportCfg)`
also returns a `CableObject` per imported cable under its source resource key,
with the same UID lookup, segment state and reset as a procedural declaration.
Cable geometry, placement and visuals come from the parsed `CableDesc`.
A sparse `asset_cfgs` entry keyed by the simulation curve prim can override
the UID, `fixed_segments`, `collision_filter_span` and individual `attrs` physics and
contact fields before declaration. Omitted fields retain the parsed values.
Cable declarations require DexUni on CUDA with gradient mode disabled.
With this backend, an arena containing a cable cannot also contain fluid,
cloth or soft-body particles: cable episode reset does not support those
particles. Spawn checks the native cable and particle descriptors for direct
Expand Down
5 changes: 4 additions & 1 deletion embodichain/lab/sim/cfg/usd.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,10 @@ class UsdImportCfg:

In sparse mappings with ``auto`` placement, explicit ``init_pos`` or
``init_rot`` keys select the configured pose, including zero values.
Omitted pose fields retain source placement.
Omitted pose fields retain source placement. For cables, sparse mappings
accept ``uid``, ``fixed_segments``, ``collision_filter_span`` and fields of
``CablePhysicsCfg`` under ``attrs``. Overrides apply to all curves on
the targeted prim, preserving its authored geometry and placement.
"""

robot_cfgs: dict[str, RobotCfg] = field(default_factory=dict)
Expand Down
48 changes: 30 additions & 18 deletions embodichain/lab/sim/sim_manager.py
Original file line number Diff line number Diff line change
Expand Up @@ -3065,7 +3065,13 @@ def add_usd(
) -> (
UsdImportResult
| dict[
str, VisualObject | RigidObject | Articulation | Robot | DeformableObject
str,
VisualObject
| RigidObject
| Articulation
| Robot
| DeformableObject
| CableObject,
]
):
"""Declare a USD import through a validated configuration recipe.
Expand Down Expand Up @@ -3094,7 +3100,8 @@ def add_usd(
asset_cfgs: Legacy per-asset overrides; use ``cfg.asset_cfgs``.

Returns:
Source-path mapping of declared facades and imported resource UIDs.
Source-path mapping of declared facades, including USD cables,
and imported resource UIDs.
Legacy argument forms retain the mutable asset dictionary result.
"""
from .cfg.usd import _normalize_usd_import
Expand Down Expand Up @@ -3146,6 +3153,7 @@ def add_usd(
),
"soft_object": self._deformable_objects,
"cloth_object": self._deformable_objects,
"cable_object": self._cable_objects,
}[kind]
registry[descriptor.name] = facade
assets[source_path] = facade
Expand Down Expand Up @@ -3644,22 +3652,8 @@ def get_fluid_diagnostics(self, uid: str) -> dict[str, object]:
raise RuntimeError("Fluid diagnostics require prepare().")
return self.physics.fluid_diagnostics(fluid)

def add_cable_object(self, cfg: CableObjectCfg) -> CableObject:
"""Declare a cable before ``prepare()`` using DexSim's public Spawn API.

Args:
cfg: Typed cable geometry, four-mode material and visual configuration.

Returns:
A declared facade whose data becomes available after ``prepare()``.

Raises:
NotImplementedError: Backend/device/solver/gradient mode is unsupported,
or the physical scene has already been finalized.
ValueError: Required configuration or the asset UID is invalid.
"""
if not isinstance(cfg, CableObjectCfg):
raise TypeError("Cable objects require CableObjectCfg.")
def _require_cable_declaration(self) -> None:
"""Check the shared runtime requirements for declaring cables."""
if not self.physics.supports_cables:
raise NotImplementedError("Cable objects require the Newton backend.")
if self.device.type != "cuda":
Expand All @@ -3676,6 +3670,24 @@ def add_cable_object(self, cfg: CableObjectCfg) -> CableObject:
raise NotImplementedError(
"Declare cable objects before scene finalization."
)

def add_cable_object(self, cfg: CableObjectCfg) -> CableObject:
"""Declare a cable before ``prepare()`` using DexSim's public Spawn API.

Args:
cfg: Typed cable geometry, four-mode material and visual configuration.

Returns:
A declared facade whose data becomes available after ``prepare()``.

Raises:
NotImplementedError: Backend/device/solver/gradient mode is unsupported,
or the physical scene has already been finalized.
ValueError: Required configuration or the asset UID is invalid.
"""
if not isinstance(cfg, CableObjectCfg):
raise TypeError("Cable objects require CableObjectCfg.")
self._require_cable_declaration()
descriptor, materials = cable_desc_from_cfg(cfg, per_env=True)
if descriptor.name in self.asset_uids or descriptor.name in self._spawn_scene:
raise ValueError(
Expand Down
30 changes: 17 additions & 13 deletions embodichain/lab/sim/spawn/descriptors.py
Original file line number Diff line number Diff line change
Expand Up @@ -809,6 +809,22 @@ def _explicit_tet_mesh_from_cfg(
}


def _cable_contact_spec(attrs: CablePhysicsCfg) -> _RigidPhysicsSpec:
if not isinstance(attrs, CablePhysicsCfg):
raise TypeError("Cable attrs must be CablePhysicsCfg.")
if isinstance(attrs.collision_props, DefaultCollisionPropertiesCfg):
raise NotImplementedError(
"Cable contact properties require common or Newton configuration."
)
return _resolve_rigid_physics(
RigidBodyPhysicsCfg(
collision_props=attrs.collision_props,
material_props=attrs.material_props,
),
newton_solver_type="dexuni",
)


def cable_desc_from_cfg(
cfg: CableObjectCfg,
*,
Expand All @@ -835,19 +851,7 @@ def cable_desc_from_cfg(
) from exc
cfg.validate()
uid = _required_uid(cfg.uid, "Cable object")
if not isinstance(cfg.attrs, CablePhysicsCfg):
raise TypeError("Cable attrs must be CablePhysicsCfg.")
if isinstance(cfg.attrs.collision_props, DefaultCollisionPropertiesCfg):
raise NotImplementedError(
"Cable contact properties require common or Newton configuration."
)
contact = _resolve_rigid_physics(
RigidBodyPhysicsCfg(
collision_props=cfg.attrs.collision_props,
material_props=cfg.attrs.material_props,
),
newton_solver_type="dexuni",
)
contact = _cable_contact_spec(cfg.attrs)
collision = _compile_newton_collision(
contact, newton_solver_type="dexuni", author_shape_defaults=True
)
Expand Down
121 changes: 117 additions & 4 deletions embodichain/lab/sim/spawn/usd_import.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,16 @@
from __future__ import annotations

from collections import Counter
from collections.abc import Mapping
from copy import deepcopy
from dataclasses import dataclass, field, fields
from dataclasses import dataclass, field, fields, replace
from typing import TYPE_CHECKING, Any

import numpy as np

from dexsim.spawn import (
ArticulationDesc,
CableDesc,
ConstraintDesc,
MeshObjectDesc,
SoftBodyDesc,
Expand All @@ -36,6 +38,9 @@
from embodichain.lab.sim.cfg import (
ArticulationCfg,
ArticulationRootPropertiesCfg,
CableAttachmentCfg,
CableObjectCfg,
CablePhysicsCfg,
RigidObjectCfg,
RobotCfg,
VisualObjectCfg,
Expand All @@ -46,6 +51,7 @@
)
from embodichain.lab.sim.objects import (
Articulation,
CableObject,
RigidObject,
Robot,
VisualObject,
Expand All @@ -54,10 +60,17 @@
)
from embodichain.lab.sim.sensors import Camera, CameraCfg, StereoCamera, StereoCameraCfg
from embodichain.lab.sim.sensors.registry import _resolve_sensor_factory
from .descriptors import _pose_from_cfg, configure_articulation_desc
from .descriptors import (
_cable_contact_spec,
_compile_newton_collision,
_pose_from_cfg,
_required_uid,
configure_articulation_desc,
)
from .usd import (
_configure_articulation_usd,
_configure_rigid_usd,
_overlay_optional_properties,
_parse_usd_source,
_source_pose,
_set_resolved_usd_pose,
Expand Down Expand Up @@ -91,6 +104,67 @@ def _source_path(descriptor: Any) -> str:
return usd.prim_path if usd is not None and usd.prim_path else descriptor.name


def _usd_cable_cfg(
descriptor: CableDesc, overrides: Mapping[str, Any] | None
) -> CableObjectCfg:
"""Apply sparse cable properties before declaring the descriptor and its facade."""
if overrides is None:
overrides = {}
if not isinstance(overrides, Mapping):
raise TypeError("USD cable overrides must be a sparse mapping.")
unknown = overrides.keys() - {
"uid",
"attrs",
"fixed_segments",
"collision_filter_span",
}
if unknown:
raise ValueError(f"Unknown USD cable override fields: {sorted(unknown)}.")
attrs = overrides.get("attrs", {})
if not isinstance(attrs, Mapping):
raise TypeError("USD cable attrs must be a sparse mapping.")
parsed_physics = {
item.name: getattr(descriptor.physics, item.name)
for item in fields(descriptor.physics)
}
physics_cfg = CablePhysicsCfg(**{**parsed_physics, **attrs})
if overrides:
if "uid" in overrides:
descriptor.name = _required_uid(overrides["uid"], "Cable object")
# Preserve the difference between an omitted coefficient and an explicit zero/None.
descriptor.physics = replace(
descriptor.physics,
**{key: attrs[key] for key in attrs.keys() & parsed_physics.keys()},
)
contact = _cable_contact_spec(physics_cfg)
descriptor.collision = _overlay_optional_properties(
descriptor.collision,
_compile_newton_collision(contact, newton_solver_type="dexuni"),
)
if contact.collision_enabled is not None:
descriptor.enable_collision = contact.collision_enabled
for name in ("fixed_segments", "collision_filter_span"):
if name in overrides:
setattr(descriptor, name, overrides[name])
# Revalidate indices, attachments and thickness against the source
# geometry before publishing any part of this freshly parsed scene.
descriptor.__post_init__()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Resolve attachment targets before validating the renamed cable

A valid source cable wire attached to rigid object base fails when these overrides reuse the rigid object's original name:

asset_cfgs = {
    "/World/base": {"uid": "anchor"},
    "/World/wire": {"uid": "base"},
}

The final UIDs are unique and the intended connection is cable base -> rigid anchor. However, _usd_cable_cfg() changes descriptor.name to base and calls CableDesc.__post_init__() while start_attachment.target still contains the old name base. The SDK raises ValueError: a cable cannot attach to itself before target remapping at lines 646-660 can run. Both add_usd() and Gym's manager-free preflight reject this valid configuration.

Reproduced with a real parsed USD under DexSim 0.6.0rc2, with the cable endpoint and rigid anchor both at world [0, 0, 0]. Renaming the cable to renamed_wire succeeds and produces renamed_wire -> anchor; changing only that UID to base causes the error.

Please validate attachment relationships after all final UIDs and attachment targets have been resolved, while retaining early validation of geometry and fixed indices. A focused no-simulation regression for this valid UID-reuse case would cover the gap.


frames = descriptor.segment_quaternions
return CableObjectCfg(
uid=descriptor.name,
points=descriptor.points,
radius=descriptor.radius,
init_local_pose=descriptor.pose,
segment_quaternions=None if frames is None else frames[:, [1, 2, 3, 0]],
closed=descriptor.closed,
fixed_segments=descriptor.fixed_segments,
attrs=physics_cfg,
collision_filter_span=descriptor.collision_filter_span,
render_mode=descriptor.render_mode,
)


def _compile_usd_import(
manager: SimulationManager | None,
recipe: UsdImportCfg,
Expand Down Expand Up @@ -143,6 +217,8 @@ def _compile_usd_import(
manager._spawn_scene._require_compatible_particles(
cables=bool(source.cables), particles=bool(source.particle_sets)
)
if source.cables:
manager._require_cable_declaration()
resources = list(source.iter_entities())
source_paths_by_id = {id(item): _source_path(item) for item in resources}
counts = Counter(source_paths_by_id.values())
Expand All @@ -163,7 +239,12 @@ def _compile_usd_import(
if item.usd is not None and item.usd.prim_path
else item.name
)
for item in (*source.mesh_objects, *source.articulations, *source.particle_sets)
for item in (
*source.mesh_objects,
*source.articulations,
*source.particle_sets,
*source.cables,
)
}
overlap = robot_cfgs.keys() & asset_cfgs.keys()
missing = (robot_cfgs.keys() | asset_cfgs.keys()) - source_paths
Expand Down Expand Up @@ -251,6 +332,21 @@ def _compile_usd_import(
and descriptor.physics is None
and not descriptor.collisions
)
if isinstance(descriptor, CableDesc):
if root_pose is not None:
descriptor.pose = root_pose @ descriptor.pose
cfg = _usd_cable_cfg(descriptor, configured)
if descriptor.name in occupied:
raise ValueError(f"USD asset UID already exists: {descriptor.name!r}.")
occupied.add(descriptor.name)
renamed[original_name] = descriptor.name
facade = (
None if manager is None else CableObject(cfg, device=manager.device)
)
declarations.append(
(resource_keys[id(descriptor)], "cable_object", descriptor, facade)
)
continue
if configured is not None and not isinstance(
descriptor, (MeshObjectDesc, ArticulationDesc, SoftBodyDesc, ClothDesc)
):
Expand Down Expand Up @@ -547,6 +643,23 @@ def renamed_endpoint(endpoint: str) -> str:
owner, separator, suffix = endpoint.partition("/")
return renamed.get(owner, owner) + separator + suffix

for _, kind, descriptor, facade in declarations:
if kind == "cable_object":
for name in ("start_attachment", "end_attachment"):
anchor = getattr(descriptor, name)
if anchor is not None:
anchor.target = renamed.get(anchor.target, anchor.target)
if facade is not None:
setattr(
facade.cfg,
name,
CableAttachmentCfg(
target=anchor.target,
position=anchor.position.copy(),
link_name=anchor.link_name,
),
)

for constraint in source.constraints:
if constraint.body0 is not None:
constraint.body0 = renamed_endpoint(constraint.body0)
Expand Down Expand Up @@ -577,6 +690,7 @@ def renamed_endpoint(endpoint: str) -> str:
public_kinds = {
"soft_object": "volume_deformable",
"cloth_object": "surface_deformable",
"cable_object": "cable",
}
resource_types = {
path: "robot" if path in robot_paths else public_kinds.get(kind, kind)
Expand All @@ -586,7 +700,6 @@ def renamed_endpoint(endpoint: str) -> str:
("cameras", "camera"),
("lights", "light"),
("records", "record"),
("cables", "cable"),
("constraints", "constraint"),
):
resource_types.update(
Expand Down
Loading
Loading