Add 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