Migration of Deformables

Migration of Deformables#

In the newer versions of Omni Physics (107.0 and later), the old deformable body functionality has become deprecated. The following sections describe the changes to migrate to the new Omni Physics API, specifically moving away from Soft Bodies and towards Surface and Volume Deformables. We currently only support deformable bodies in the PhysX backend, hence these features are implemented in isaaclab_physx.

Note

The following changes are with respect to Isaac Lab v3.0.0 and Omni Physics v110.0. Please refer to the release notes for any changes in the future releases.

Surface and Volume Deformables#

With the new Omni Physics API, deformable bodies are split into two distinct types, as described in the Omni Physics documentation:

  • Volume deformables: 3D objects simulated with a tetrahedral FEM mesh (e.g., soft cubes, spheres, capsules). These support kinematic targets on individual vertices. The simulation operates on a tetrahedral mesh internally, while a separate triangle surface mesh handles rendering.

  • Surface deformables: 2D surfaces simulated directly on a triangle mesh (e.g., cloth, fabric, membranes). These have additional material properties for controlling stretch, shear, and bend stiffness, but do not support kinematic vertex targets.

The type of deformable is determined by the physics material assigned to the object:

  • DeformableBodyMaterialCfg creates a volume deformable.

  • SurfaceDeformableBodyMaterialCfg creates a surface deformable.

Migration from the Old API#

Import Changes#

All deformable-related classes have moved from isaaclab to isaaclab_physx. The table below summarizes the import changes:

Old Import

New Import

from isaaclab.sim import DeformableBodyPropertiesCfg

from isaaclab_physx.sim import DeformableBodyPropertiesCfg

from isaaclab.sim import DeformableBodyMaterialCfg

from isaaclab_physx.sim import DeformableBodyMaterialCfg

Removed Properties#

The following properties have been removed from DeformableBodyPropertiesCfg:

  • collision_simplification and related parameters (collision_simplification_remeshing, collision_simplification_target_triangle_count, collision_simplification_force_conforming, collision_simplification_remove_open_edges) — collision mesh generation is now handled automatically by PhysX through deformableUtils.create_auto_volume_deformable_hierarchy() and deformableUtils.create_auto_surface_deformable_hierarchy().

  • simulation_hexahedral_resolution — the simulation mesh resolution is no longer user-configurable; PhysX determines it automatically.

  • vertex_velocity_damping — replaced by the more general linear_damping property from the PhysX deformable schema.

  • sleep_damping — replaced by settling_damping in the PhysX deformable schema.

Added Properties#

The following properties have been added to DeformableBodyPropertiesCfg:

  • linear_damping — linear damping coefficient [1/s].

  • max_linear_velocity — maximum allowable linear velocity [m/s]. A negative value lets the simulation choose a per-vertex value dynamically (currently only supported for surface deformables).

  • settling_damping — additional damping applied when vertex velocity falls below settling_threshold [1/s].

  • enable_speculative_c_c_d — enables speculative continuous collision detection.

  • disable_gravity — per-deformable gravity control.

  • collision_pair_update_frequency — how often surface-to-surface collision pairs are updated per time step (surface deformables only).

  • collision_iteration_multiplier — collision subiterations per solver iteration (surface deformables only).

For a full description of all available properties, refer to the PhysX deformable schema and OmniPhysics deformable schema documentation.

Material Changes#

The old DeformableBodyMaterialCfg (from isaaclab.sim) has been replaced by a new hierarchy in isaaclab_physx:

  • DeformableBodyMaterialCfg — for volume deformables. Contains density, static_friction, dynamic_friction, youngs_modulus, poissons_ratio, and elasticity_damping.

  • SurfaceDeformableBodyMaterialCfg — extends the volume material config with surface-specific properties: surface_thickness, surface_stretch_stiffness, surface_shear_stiffness, surface_bend_stiffness, and bend_damping.

The old damping_scale property has been removed. Use elasticity_damping directly instead.

DeformableObject View Change#

The internal PhysX view type has changed from physx.SoftBodyView to physx.DeformableBodyView. The property root_physx_view has been deprecated in favor of root_view.

Code Examples#

Volume Deformable (Before and After)#

Before:

import isaaclab.sim as sim_utils
from isaaclab.assets import DeformableObject, DeformableObjectCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cube",
    spawn=sim_utils.MeshCuboidCfg(
        size=(0.2, 0.2, 0.2),
        deformable_props=sim_utils.DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=sim_utils.DeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cube_object = DeformableObject(cfg=cfg)

After:

import isaaclab.sim as sim_utils
from isaaclab_physx.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import DeformableBodyPropertiesCfg, DeformableBodyMaterialCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cube",
    spawn=sim_utils.MeshCuboidCfg(
        size=(0.2, 0.2, 0.2),
        deformable_props=DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=DeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cube_object = DeformableObject(cfg=cfg)

Surface Deformable (New)#

Surface deformables use MeshSquareCfg for 2D meshes, combined with SurfaceDeformableBodyMaterialCfg:

import isaaclab.sim as sim_utils
from isaaclab_physx.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import DeformableBodyPropertiesCfg, SurfaceDeformableBodyMaterialCfg

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Cloth",
    spawn=sim_utils.MeshSquareCfg(
        size=1.5,
        resolution=(21, 21),
        deformable_props=DeformableBodyPropertiesCfg(),
        visual_material=sim_utils.PreviewSurfaceCfg(),
        physics_material=SurfaceDeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
    ),
)
cloth_object = DeformableObject(cfg=cfg)

USD File Deformable#

Deformable properties can also be applied to imported USD assets using UsdFileCfg:

import isaaclab.sim as sim_utils
from isaaclab_physx.assets import DeformableObject, DeformableObjectCfg
from isaaclab_physx.sim import DeformableBodyPropertiesCfg, DeformableBodyMaterialCfg

from isaaclab.utils.assets import ISAACLAB_NUCLEUS_DIR

cfg = DeformableObjectCfg(
    prim_path="/World/Origin.*/Teddy",
    spawn=sim_utils.UsdFileCfg(
        usd_path=f"{ISAACLAB_NUCLEUS_DIR}/Objects/Teddy_Bear/teddy_bear.usd",
        deformable_props=DeformableBodyPropertiesCfg(),
        physics_material=DeformableBodyMaterialCfg(poissons_ratio=0.4, youngs_modulus=1e5),
        scale=[0.05, 0.05, 0.05],
    ),
)
teddy_object = DeformableObject(cfg=cfg)

Limitations#

  • Kinematic targets are volume-only. Calling write_nodal_kinematic_target_to_sim_index() on a surface deformable will raise a ValueError.

  • Surface-specific solver properties (collision_pair_update_frequency, collision_iteration_multiplier) have no effect on volume deformables.

  • Deformables are PhysX-only. The isaaclab_physx extension is required; other physics backends do not support deformable bodies through Isaac Lab yet.