Skip to content

Register CableObject facades for USD cables - #1171

Closed
KeqiYe wants to merge 4 commits into
mainfrom
codex/usd-cable-object
Closed

KeqiYe wants to merge 4 commits into
mainfrom
codex/usd-cable-object

Conversation

@KeqiYe

@KeqiYe KeqiYe commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Register USD-authored cables as managed CableObject instances. add_usd() returns one facade per source resource key, and get_cable_object() and get_asset() resolve the same instance by UID. The parsed DexSim descriptor supplies the native geometry, physics, and visuals. The facade carries the resolved geometry used by the Viser capsule exporter.

This closes the USD entry-point gap for the reset behavior introduced in #838 and the Gym and visualization integrations in #839. This branch uses main's pinned DexSim 0.6.0rc2.

Sparse asset_cfgs mappings keyed by the USD simulation curve prim can set the UID, fixed segments, self-collision filter span, rod stiffness/damping and Newton contact parameters before spawning. Unspecified fields and the authored centerline stay in the source descriptor. The same recipe participates in Gym preflight and creates the registered facade at runtime. #834 and #923 exercise this path.

Type of change

  • Bug fix

Validation on DexSim 0.6.0rc2

  • Six CUDA tests passed on an RTX 5090 D v2, including a two-environment USD cable with selective reset and Viser, and a Gym recording/replay round trip through the public USD scene entry point.
  • Sparse overrides and UID lookup were checked before native declaration, including explicit zero values, retained source fields and invalid fixed indices.

Earlier validation on rc1

  • 6 CUDA tests passed on RTX 5090 D v2 with Newton/DexUni and DexSim 0.6.0rc1. Coverage includes a two-arena USD-only cable scene, one-arena reset and state write, Viser geometry and frame capture, and the Gym round trip for recording and dynamically replaying imported and procedural cables together.
  • 163 related tests passed, with 4 simulation or GPU cases skipped in the CPU run. Coverage includes stable USD keys for multiple curves, namespacing, cable/particle scene preflight, Viser, and the USD acceptance utility.
  • The USD acceptance CLI also completed a two-arena cable case through prepare, step, and reset.
  • A local Viser server returned HTTP 200 and published three scene frames with the USD cable in the selected arena. The smoke test passed with both the packaged frontend and the rebuilt frontend. The initial frontend build exceeded the server startup timeout, and the retry after the build completed passed.
  • Black 26.10.1, API documentation coverage, and the agent context map checks passed.

Checklist

  • Ran Black and checked formatting after rebasing onto main.
  • Updated the cable lifecycle guidance and reviewed the relevant Gym and Viser guidance.
  • Updated API docstrings and ran the public API docs coverage check.
  • Extended focused regression coverage for the USD and runtime paths.

@KeqiYe
KeqiYe requested review from han-xudong and yuecideng and removed request for han-xudong November 13, 2026 02:50
@KeqiYe
KeqiYe marked this pull request as draft November 16, 2026 10:05

@yuecideng yuecideng left a comment

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.

Reviewed PR #1171 at 85f25b4d869159e91154a9f2afe114a79767be72 against base f13fb1a4d3430487f98b236280699d6969958910 (11 changed files).

The overall loading architecture is coherent: parsed USD descriptors retain ownership of native geometry, physics and visuals; source paths/resource keys remain separate from runtime UIDs; a stable CableObject facade binds during prepare(); and Gym preflight shares the runtime compiler. I recommend retaining this structure.

Confirmed finding

One P2 finding is attached inline to spawn/usd_import.py:151: a valid cable/anchor UID rename is rejected as self-attachment because validation runs before attachment target remapping. Please fix this ordering before merge.

Priority Location Root cause Impact Recommended action
P2 usd_import.py:151 Attachment validation observes a partially renamed identity graph Valid USD imports and Gym preflight fail Resolve final UIDs and references before validating attachment relationships

Follow-up API recommendations, referencing Isaac Lab v3.0.0

These are follow-up design recommendations and can be split into subsequent PRs. Isaac Lab's cable support is itself experimental; the useful reference here is its separation of authoring/source configuration, runtime assets and segment state.

  1. Add a single-cable USD source entry point while retaining whole-scene import. Isaac Lab's AssetBaseCfg accepts a spawn configuration, including UsdFileCfg; spawn=None binds an existing scene asset. For EmbodiChain, keep the existing project-wide source=UsdSourceCfg(...) vocabulary and consider extending add_cable_object() accordingly:

    # Proposed API; currently unsupported by #1171.
    cable = sim.add_cable_object(
        CableObjectCfg(
            uid="wire",
            source=UsdSourceCfg(
                file_path="wire.usda",
                source_prim_path="/World/wire",
            ),
        )
    )
    sim.prepare()

    Make source-backed and procedural points/radius inputs mutually exclusive; reject ambiguous selections in the singleton route. Reuse the existing parser, override and declaration logic. Keep add_usd(UsdImportCfg(...)) for scenes containing cables, connectors, supports and constraints, and keep UID lookup for already-imported facades so each physical cable has one managed instance.

  2. Give sparse overrides an explicit type/schema without losing field-presence semantics. A TypedDict or dedicated sparse configuration can improve completion and validation while preserving omitted fields, explicit zero coefficients, explicit None coefficients and an explicit empty fixed_segments list. The current key-presence approach is valuable. Avoid treating a full CableObjectCfg as a patch: defaults such as density 1000 and empty fixed segments can accidentally overwrite authored USD values. Document None semantics per field; the coefficient and optional contact-overlay paths have different behavior.

  3. Document physical units and qualify cross-tool USD compatibility. Isaac Lab's CableMaterialCfg exposes elastic moduli, while EmbodiChain's CablePhysicsCfg exposes direct per-connection coefficients:

    Parameter Isaac Lab v3.0.0 EmbodiChain
    stretch_stiffness Elastic modulus, Pa Joint stiffness, N/m
    bend_stiffness Elastic modulus, Pa Angular joint stiffness, N m/rad

    Isaac Lab discretizes these using cross-section and joint dual rest length, e.g. EA/L and EI/L. Copying its numerical settings directly into attrs changes the physical meaning. Preserve the existing direct-coefficient contract and provide explicit conversions or a separately identified material parameterization if needed.

    There is also a concrete schema boundary: a CPU-only minimal USD constructed from the fields authored by Isaac Lab v3.0.0's material/spawner code was rejected by the installed DexSim 0.6.0rc2 parser with NotImplementedError: ...physics:thickness: migrate to geometry thicknesses and physics:curves*Stiffness structural coefficients. This was a reconstructed field-output fixture, not an executed Isaac Lab export. A cross-tool fixture should verify radius, mass, per-connection stiffness and endpoint constraints before claiming direct asset compatibility.

  4. Separate source provenance, authoring intent and resolved runtime metadata. _usd_cable_cfg() reconstructs enough geometry/configuration for the facade and Viser, but cable.cfg does not capture every authored visual/contact descriptor. Document its scope and retain provenance separately; do not present its serialization as a complete reconstruction recipe for the USD asset. Keep the parsed descriptor as the native asset definition.

  5. Keep segment-based state and make reset semantics explicit. The world-frame segment poses/velocities and XYZW convention align well with Isaac Lab's cable data model. Keep state teleport, object reset and full episode reset as distinct operations. Isaac Lab's CableObject.reset() resets internal buffers; EmbodiChain's object reset restores creation state and clears loads, while manager/Scene reset owns the episode boundary and attached physical assets. Preserve the actual backend contracts when aligning API names.

For the compiler, a clear sequence is: parse source -> merge sparse overrides -> resolve all final UIDs -> remap attachments/constraints -> validate the complete scene -> declare facades -> prepare/bind.

Validation

  • Related no-simulation tests: 106 passed, 3 skipped, using Python 3.12 and DexSim 0.6.0rc2:
    python -m pytest tests/sim/objects/test_cable_object.py tests/sim/spawn/test_usd_scene_overrides.py -m no_sim -q -p no:cacheprovider.
  • Real-USD parsing/compiler reproduction confirmed the P2 finding without creating a World.
  • Independent engine, API and verification passes were completed and the finding was rechecked by the lead.
  • Native CUDA simulation, a live Viser server, and Gym recording/replay execution were not run for this review; those paths received static review.

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.

@KeqiYe KeqiYe closed this Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants