Support heterogeneous OvPhysX cloning

[maxkra15]

Description

Enable heterogeneous rigid-body and articulation cloning through the Isaac Lab OvPhysX adapter. OvPhysX 0.6.3 already supports cloning compatible structures with different geometry; the adapter previously lost variant-specific environment IDs and could discard a source variant used only by its own environment.

The adapter now:

• Retains every active source geometry variant, including source-only variants, and dispatches one clone call per variant with its matching destination env_ids.
• Removes authored runtime targets from the physics export while retaining source subtrees. Lightweight destination placeholders keep collision-group membership and contact reporters resolvable.
• Uses USD collision groups to isolate heterogeneous environments when a source lives outside env_0; homogeneous scenes keep their existing fast path and runtime filtering.
• Preserves numeric environment order in rigid-body, articulation, and contact bindings so indexed reads and writes reach the intended environment.
• Rejects incompatible body/joint topology, connectivity, or effective DOF axes, including D6 layouts, before cloning.
• Keeps the legacy three-argument clone call for older OvPhysX releases; heterogeneous cloning requires OvPhysX 0.6.3 or newer.
• Enables the existing heterogeneous KUKA–Allegro shapes preset with OvPhysX.

OvPhysX 0.6.3, OVStage 0.2, and OVRTX 0.5 are already supplied by develop (#7861); this PR adds the Isaac Lab adapter integration. The OvPhysX 0.6.3 clone API defines the per-variant source, targets, transforms, and environment-ID call shape.

Validation

• 36 focused clone-plan and OvPhysX compatibility tests passed after the latest merge.
• Eight heterogeneous rigid-body, articulation, and contact cases passed on CPU and eight on CUDA; six homogeneous rigid-body cases passed on each device.
• A 32-environment, 64-step heterogeneous KUKA–Allegro CUDA smoke run passed.
• Formatting, changelog validation, and the warning-free documentation build passed. Routine PR checks passed on the preceding code commit; on-demand Docker/GPU CI has been requested for the current head with run-ci.
• Two OVRTX multi-camera depth tests failed identically on this branch and a clean develop checkout in local September 22 testing. They are tracked as a separate renderer investigation.

Remaining work and limitations

• OvPhysX heterogeneous rendering goldens are still unavailable, so that comparison remains skipped. Previously reported RGB/RGBA golden and native camera visibility discrepancies need separate renderer validation. The corrected Franka asset has since been published and its asset-dependent coverage restored in #7931.
• CPU KUKA resets can write velocities to kinematic tables, which native PhysX rejects; the behavior also reproduces with a single kinematic cube on older and current OvPhysX releases. It needs a separate Isaac Lab reset/adapter fix.
• Deformable-body fast-path cloning is unsupported by OvRuntime/OvPhysX and is outside this PR.

Type of change

• Bug fix
• Documentation update

Release backport

• Backport this pull request to the active release branch after it merges into develop.

Checklist

• Contribution guidelines and formatting checks reviewed.
• Documentation and focused regression tests updated.
• Changelog fragments cover the changed source packages.
• Contributor name is present in CONTRIBUTORS.md.

[marcodiiga]

run-ci

[greptile-apps]

Confidence Score: 4/5

The PR should not merge until articulation variants with differing effective DOF layouts are rejected before cloning.

Findings

1.  D6 layouts escape validation ▶

Summary

This PR upgrades OvPhysX and OVStage and extends the Omniverse clone pipeline to preserve heterogeneous rigid-body and articulation variants.

• Carries destination environment IDs through clone recipes and runtime clone calls.
• Retains every active source environment while stripping authored clone targets.
• Enables heterogeneous KUKA–Allegro object presets for OvPhysX.
• Adds topology checks, tests, dependency updates, and documentation.
• The articulation compatibility check remains incomplete for joints whose effective DOF structure is not determined solely by their USD type.

Diagram

sequenceDiagram
  participant P as ClonePlan
  participant R as OvPhysX replicate adapter
  participant M as OvPhysxManager
  participant S as Serialized stage
  participant X as OvPhysX runtime
  P->>R: sources, destinations, mapping, env_ids
  R->>R: validate variant topology
  R->>M: register per-variant clone recipes
  M->>S: retain source environments
  M->>X: attach source stage
  loop Each variant with targets
    M->>X: clone(source, targets, transforms, env_ids)
    X-->>M: operation complete
  end

Loading

_{Reviews (1) · Last reviewed commit: "Support heterogeneous OvPhysX cloning"}

[isaaclab-review-bot]

Isaac Lab Review Bot

The heterogeneous clone recipe is propagated consistently through construction, registration, serialization, source retention, and runtime replay. Two compatibility and API-documentation issues remain: clone dispatch unconditionally uses the OvPhysX 0.6.3 call shape despite retained legacy-version handling, and the new validation failures are absent from the affected Raises sections.

• Design and architecture: Per-variant recipes, including empty-target recipes used to retain nonzero source environments, fit the existing ClonePlan pipeline. However, runtime replay bypasses the existing OvPhysX compatibility boundary by always passing the 0.6.3-only env_ids argument, while the package still retains pre-0.6 fallback behavior. Dispatch must be version-aware or legacy support must be removed explicitly.
• API: The internal CloneRecipe expansion is applied consistently, and register_clone retains its existing signature. The public ovphysx_replicate contract and the replication-context documentation should describe the newly introduced source/destination length, mapping-shape, and topology ValueError cases.
• Implementation: Environment IDs reach each runtime clone call, source-only variants remain serialized, and dependency pins and tests are updated coherently. Before merge, runtime clone invocation should be aligned with the declared version-compatibility policy, and the new deterministic validation paths should be documented.

Minor fixes needed. Posted 2 actionable findings inline.

Automated review; human maintainers own approval decisions.

[marcodiiga]

The variant-source retention and env_id propagation address the original adapter gaps, but the heterogeneous path still has contact and environment-indexing failures. I reproduced the issues below with the pinned ovphysx 0.6.3 runtime on this commit; the focused tests and basic CPU/CUDA initialization tests pass.

[maxkra15]

Pushed follow-up review fixes for heterogeneous source/target collision isolation, environment-ordered tensor/contact bindings, topology/D6 validation, and legacy clone compatibility. The runtime pins now pair OvPhysX 0.6.3 with OVStage 0.2 and OvRTX 0.5. the earlier KUKA smoke runs also completed, with the CPU reset errors noted below.

The corrected Franka asset is still awaiting sync to the public asset bucket. Testing the updated flat asset restores cloned robot geometry and materials in the cloth, cable, and soft scenes without renderer changes. That should resolve the asset-triggered missing-robot failures once published, but does not make the complete rendering suite green.

Remaining WIP for now:

• RGB/RGBA golden failures: geometry/albedo checks pass with the corrected asset, but color differences remain with the new rendering stack. Exact cause still under investigation; no golden images or tolerances were changed.
• Native-only camera partition/visibility discrepancy: reproduced without Isaac Lab in a reduced native scene. This is not yet established as a camera-position error; the exact OvRTX/OVStage boundary responsible remains unresolved.
• Kinematic velocity errors: KUKA CPU reset writes velocities to kinematic tables, which native PhysX rejects. Independently reproduced with one kinematic cube; an Isaac Lab reset/adapter fix remains outstanding.

[ooctipus]

hmmm why ovphysx cloning support touches ovrtx?

[maxkra15]

hmmm why ovphysx cloning support touches ovrtx?

@ooctipus OvPhysX 0.6.3 requires OVStage 0.2, and in my testing the previous OvRTX version was incompatible with that combination

[maxkra15]

run-ci

[maxkra15]

run-ci

[maxkra15]

run-ci