Adds surface deformable support and migrate deformable API to isaaclab_physx

[mmichelis]

Description

Update the deformable body implementation in the PhysX backend according to the new Omni Physics migration guide (v110.0). Main changes are:

• Migrates all deformable body schemas, materials, and spawner configs from isaaclab to isaaclab_physx, since deformables are PhysX-specific.
• Updates DeformableObject to support both surface (cloth/triangle mesh) and volume (soft body/tetrahedral mesh) deformables via the new PhysX DeformableBodyView API, replacing the deprecated SoftBodyView.
• Adds MeshSquareCfg / spawn_mesh_square for spawning 2D triangle mesh grids used as cloth.
• Adds physics material support when spawning deformables from USD files.
• Introduces namespace-aware config classes (OmniPhysicsPropertiesCfg, PhysXDeformableBodyPropertiesCfg, PhysXCollisionPropertiesCfg) that route properties to the correct USD attribute prefixes (omniphysics:, physxDeformableBody:, physxCollision:).

Fixes #4469 and addresses #2004.

Type of change

• Bug fix: Deformable demos
• Breaking change: PhysX removed some deformable object functionality, such as computing per-element internal stresses and deformation gradients.
• Documentation update

Migration guide

• DeformableBodyPropertiesCfg → from isaaclab_physx.sim.schemas import DeformableBodyPropertiesCfg
• define_deformable_body_properties / modify_deformable_body_properties → from isaaclab_physx.sim.schemas import define_deformable_body_properties, modify_deformable_body_properties
• DeformableBodyMaterialCfg → from isaaclab_physx.sim.spawners.materials import DeformableBodyMaterialCfg
• DeformableObjectSpawnerCfg → from isaaclab_physx.sim.spawners.spawner_cfg import DeformableObjectSpawnerCfg

Demos

• Run ./isaaclab.sh -p scripts/demos/deformables.py — verify mixed surface and volume deformables simulate correctly
• Run ./isaaclab.sh -p scripts/tutorials/01_assets/run_deformable_object.py --visualizer kit — verify tutorial works for kinematically constrained volume deformables
• Run ./isaaclab.sh -p -m pytest source/isaaclab_physx/test/assets/test_deformable_object.py

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh --format
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• I have updated the changelog and the corresponding version in the extension's config/extension.toml file
• I have added my name to the CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

This PR migrates the deformable body subsystem to the updated Omni Physics v110 API, moving all PhysX-specific schemas, materials, and spawner configs from isaaclab into isaaclab_physx, and upgrading DeformableObject to use the new DeformableBodyView (replacing deprecated SoftBodyView) while adding first-class support for surface (cloth) deformables alongside existing volume (soft-body) deformables.

Key changes:

• New isaaclab_physx modules: sim/schemas (DeformableBodyPropertiesCfg with namespace-aware _property_prefix routing to omniphysics:, physxDeformableBody:, physxCollision:), sim/spawners/materials (DeformableBodyMaterialCfg, SurfaceDeformableBodyMaterialCfg), and sim/spawners/spawner_cfg (DeformableObjectSpawnerCfg).
• DeformableObject._initialize_impl: Detects deformable type (surface vs. volume) first from the bound physics material's applied schemas (PhysxSurfaceDeformableMaterialAPI / PhysxDeformableMaterialAPI), then falls back to a prim-hierarchy heuristic (presence of TetMesh child). Type determines which view (create_surface_deformable_body_view vs. create_volume_deformable_body_view) is created and whether nodal_kinematic_target buffers are allocated.
• New MeshSquareCfg / spawn_mesh_square: Wraps deformableUtils.create_triangle_mesh_square for spawning cloth meshes.
• Physics material support in _spawn_from_usd_file: USD-file spawning now applies a physics_material binding for deformable bodies.
• The _property_prefix docstring for physics_material_path in from_files_cfg.py has an inverted condition ("not None" instead of "None"), consistent with a copy-paste pattern already present elsewhere in the codebase.
• In meshes.py, the physics material is still created at {geom_prim_path}/{path} while the visual material was updated to {prim_path}/{path}, leaving a minor path-location inconsistency (functionally harmless, both are bound to prim_path).
• The MeshCfg class docstring describing where deformable body properties are applied is now stale after the spawning path was updated.

Confidence Score: 4/5

• PR is safe to merge; all runtime issues flagged in earlier review rounds appear addressed and the new implementation is well-structured.
• The core logic — type detection, view creation, property routing via _property_prefix, and material binding — is correct and well-tested. Issues remaining are all documentation/style level: an inverted docstring condition, a stale class comment, and a minor inconsistency in where the physics material prim is created vs. where the visual material prim is created. None of these affect runtime correctness.
• source/isaaclab_physx/isaaclab_physx/assets/deformable_object/deformable_object.py (type-detection heuristic for non-standard USD assets), source/isaaclab/isaaclab/sim/spawners/meshes/meshes.py (physics material creation path inconsistency)

Important Files Changed

Filename	Overview
source/isaaclab_physx/isaaclab_physx/assets/deformable_object/deformable_object.py	Migrates from deprecated SoftBodyView to DeformableBodyView; adds surface/volume type detection via material schema inspection and a tetmesh hierarchy heuristic; gates kinematic-target operations on _deformable_type == "volume". The type-detection fallback heuristic can silently mis-classify non-standard USD assets.
source/isaaclab_physx/isaaclab_physx/sim/schemas/schemas.py	New file implementing define_deformable_body_properties and modify_deformable_body_properties for the updated PhysX API, with surface vs. volume dispatch, namespace-aware property application, and a correct ValueError for unsupported deformable types.
source/isaaclab_physx/isaaclab_physx/sim/schemas/schemas_cfg.py	New config hierarchy (OmniPhysicsPropertiesCfg, PhysXDeformableBodyPropertiesCfg, PhysXCollisionPropertiesCfg, DeformableBodyPropertiesCfg) with _property_prefix routing to correct USD attribute namespaces. Implementation is clean and correct.
source/isaaclab_physx/isaaclab_physx/sim/spawners/materials/physics_materials_cfg.py	New material config hierarchy for surface and volume deformable body materials; uses _property_prefix mapping correctly; SurfaceDeformableBodyMaterialCfg properly extends DeformableBodyMaterialCfg with surface-specific fields.
source/isaaclab_physx/isaaclab_physx/sim/spawners/materials/physics_materials.py	New spawner for deformable body materials; correctly applies OmniPhysicsDeformableMaterialAPI, PhysxDeformableMaterialAPI, and conditionally PhysxSurfaceDeformableMaterialAPI. Attribute dispatch through _property_prefix is correct.
source/isaaclab/isaaclab/sim/spawners/from_files/from_files.py	Adds physics material binding support for USD file spawning and correctly dispatches define_deformable_body_properties vs modify_deformable_body_properties based on whether the deformable body API is already present. deformable_type inference from physics_material type is appropriate.
source/isaaclab/isaaclab/sim/spawners/from_files/from_files_cfg.py	Adds physics_material and physics_material_path fields to FileCfg; minor docstring issue: "ignored if physics_material is not None" has an inverted condition (should be "is None").
source/isaaclab/isaaclab/sim/spawners/meshes/meshes.py	Adds spawn_mesh_square for cloth simulation; migrates define_deformable_body_properties call to prim_path level; fixes material binding targets to prim_path. Physics material creation path still uses geom_prim_path, inconsistent with visual material's switch to prim_path.
source/isaaclab/isaaclab/sim/spawners/meshes/meshes_cfg.py	Adds MeshSquareCfg for 2D triangle mesh grids; migrates DeformableObjectSpawnerCfg import to isaaclab_physx. The MeshCfg class docstring still describes deformable properties as being applied to {prim_path}/geometry/mesh, which is no longer accurate after the change to call define_deformable_body_properties with prim_path.
source/isaaclab_physx/isaaclab_physx/assets/deformable_object/deformable_object_data.py	Updated to use DeformableBodyView (replacing the deprecated SoftBodyView); streamlined by removing deprecated per-element stress/deformation-gradient buffers; lazy-buffer pattern is preserved and correct.
source/isaaclab_physx/test/assets/test_deformable_object.py	Good test coverage added for surface deformable initialization, CPU-device failure, nodal state setting, and kinematic targets; new test_initialization_surface_deformable correctly asserts that nodal_kinematic_target is None for surface bodies and that ValueError is raised when kinematic targets are written to a surface deformable.
source/isaaclab_physx/isaaclab_physx/sim/spawners/spawner_cfg.py	New file correctly migrating DeformableObjectSpawnerCfg from isaaclab to isaaclab_physx with updated deformable_props type to the new DeformableBodyPropertiesCfg.

Sequence Diagram

sequenceDiagram
    participant User
    participant SpawnFn as spawn_mesh / spawn_from_usd
    participant Schemas as isaaclab_physx.sim.schemas
    participant deformableUtils as omni.physx.deformableUtils
    participant MatSpawn as spawn_deformable_body_material
    participant USD as USD Stage
    participant InitImpl as DeformableObject._initialize_impl
    participant PhysX as PhysX (DeformableBodyView)

    User->>SpawnFn: spawn with DeformableBodyPropertiesCfg + DeformableBodyMaterialCfg
    SpawnFn->>deformableUtils: create_auto_surface/volume_deformable_hierarchy(prim_path)
    deformableUtils-->>USD: add OmniPhysicsDeformableBodyAPI + sim_mesh/tetmesh
    SpawnFn->>Schemas: modify_deformable_body_properties(prim_path, cfg)
    Schemas-->>USD: set omniphysics:*, physxDeformableBody:*, physxCollision:* attrs
    SpawnFn->>MatSpawn: spawn_deformable_body_material(material_path, cfg)
    MatSpawn-->>USD: apply PhysxDeformableMaterialAPI (+ PhysxSurfaceDeformableMaterialAPI if surface)
    SpawnFn-->>USD: bind_physics_material(prim_path, material_path)

    Note over InitImpl: sim.reset() triggers initialization
    InitImpl->>USD: find prim with OmniPhysicsDeformableBodyAPI
    InitImpl->>USD: get bound material → check PhysxSurfaceDeformableMaterialAPI
    alt surface deformable
        InitImpl->>PhysX: create_surface_deformable_body_view(expr)
    else volume deformable
        InitImpl->>PhysX: create_volume_deformable_body_view(expr)
        InitImpl->>InitImpl: allocate nodal_kinematic_target buffer
    end
    InitImpl->>PhysX: create_deformable_material_view(material_expr)

Loading

_{Last reviewed commit: a270443}

[mmichelis]

@greptile

[mmichelis]

@greptile

[mmichelis]

@greptile

[mmichelis]

@greptile

[mmichelis]

@greptile

[mmichelis]

@greptile

[AntoineRichard]

LGTM thanks Mike!

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot — Follow-up Review

Reviewing incremental changes (1dcbc13..234eb2d). Previous critical findings on missing setup.py packages and unconditional isaaclab_physx imports have been partially addressed (the sim subpackages are now listed, and wrappers_cfg.py has a try/except guard). However, the same packaging bug recurs with the new video_recording modules.

🔴 Critical: Missing video_recording packages in setup.py

New modules isaaclab_physx/video_recording/ and isaaclab_newton/video_recording/ are added with __init__.py files, but neither package is listed in their respective setup.py packages lists.

source/isaaclab_physx/setup.py needs:

"isaaclab_physx.video_recording",

source/isaaclab_newton/setup.py needs:

"isaaclab_newton.video_recording",

Without these entries, from isaaclab_physx.video_recording.isaacsim_kit_perspective_video import ... and from isaaclab_newton.video_recording.newton_gl_perspective_video import ... will raise ModuleNotFoundError after pip install -e .. The VideoRecorder constructor imports these dynamically, so --video will fail at runtime.

🟡 Warnings

1. wrappers_cfg.py catches bare Exception instead of ImportError

The new try/except guard catches Exception, which will silently swallow unrelated errors (e.g. a syntax error in isaaclab_physx):

try:
    from isaaclab_physx.sim.spawners.spawner_cfg import DeformableObjectSpawnerCfg
except Exception as e:  # should be ImportError or ModuleNotFoundError

2. Unused sim_time variable in scripts/demos/deformables.py

After the refactor to a while loop with modulo-based reset, sim_time is accumulated but never read — the reset now uses count % int(3.0 / sim_dt). Can be removed for clarity.

🟢 Improvements Noted

• Newton FK invalidation fix — Clean approach. invalidate_fk() ensures body_q is fresh before collision detection after env resets. The regression test in test_body_q_consistent_after_root_write is thorough.
• VideoRecorder abstraction — Good separation of Kit vs Newton GL backends behind a common interface. The _resolve_video_backend heuristic is reasonable.
• Deformable mass_props validation — Raising ValueError when users set MassPropertiesCfg on deformable bodies (pointing them to DeformableBodyPropertiesCfg(mass=<value>)) is a helpful guard.
• Visual material binding fix in meshes.py — Binding to mesh_prim_path instead of geom_prim_path is correct for the USD hierarchy.
• Benchmark startup profiler — Well-structured with whitelist mode, proper cProfile wrapping per phase, and fallback top-N.
• Summary backend dynamic phase rendering — Good extension to handle arbitrary benchmark phases.
• Previous finding #6 addressed — Demo reset condition is now reachable with the modulo-based approach.

[isaaclab-review-bot]

🤖 Isaac Lab Review Bot — Follow-up

New commits (7bd7ea1→570033f9): Major refactor adding PVA sensor (renamed from old IMU), new lightweight IMU sensor, Camera/TiledCamera unification, CameraData.info flattened to dict[str, Any], ensure_drives_exist schema flag, actuator gain randomization fix, and Python 3.12 / Isaac Sim 6.0 baseline.

🔴 Missing isaaclab_physx.sensors.pva in setup.py

source/isaaclab_physx/setup.py explicitly lists every subpackage but does not include the new isaaclab_physx.sensors.pva package. After pip install, from isaaclab_physx.sensors.pva import Pva will raise ModuleNotFoundError.

This is the same class of bug flagged in prior reviews (missing sim subpackages, missing video_recording packages). The video_recording packages from the prior review also remain unlisted.

Fix: Add to the packages list in source/isaaclab_physx/setup.py:

"isaaclab_physx.sensors.pva",