Adds APIs for spawning deformable meshes (#613)

# Description This MR adds schemas and spawners to create deformable bodies based on primitive shapes. It uses the latest PhysX 5.4 support for FEM simulation of deformable bodies. The MR adds the required demo and docs changes. ## Type of change - New feature (non-breaking change which adds functionality) - This change requires a documentation update ## Screenshots https://github.com/isaac-sim/IsaacLab/assets/12863862/9c239d6d-098d-4c70-b6fd-0a73c74c80c4 ## Checklist - [x] I have run the [`pre-commit` checks](https://pre-commit.com/) with `./isaaclab.sh --format` - [x] I have made corresponding changes to the documentation - [x] 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 - [x] I have added my name to the `CONTRIBUTORS.md` or my name already exists there
isaac-sim · Jul 13, 2024 · 0a6079d · 0a6079d
1 parent 8cf6647
commit 0a6079d
Show file tree

Hide file tree

Showing 26 changed files with 1,881 additions and 24 deletions.
diff --git a/docs/source/api/lab/omni.isaac.lab.sim.schemas.rst b/docs/source/api/lab/omni.isaac.lab.sim.schemas.rst
@@ -13,6 +13,7 @@
     MassPropertiesCfg
     JointDrivePropertiesCfg
     FixedTendonPropertiesCfg
+    DeformableBodyPropertiesCfg
 
   .. rubric:: Functions
 
@@ -29,6 +30,8 @@
     modify_mass_properties
     modify_joint_drive_properties
     modify_fixed_tendon_properties
+    define_deformable_body_properties
+    modify_deformable_body_properties
 
 Articulation Root
 -----------------
@@ -88,3 +91,13 @@ Fixed Tendon
     :exclude-members: __init__
 
 .. autofunction:: modify_fixed_tendon_properties
+
+Deformable Body
+---------------
+
+.. autoclass:: DeformableBodyPropertiesCfg
+    :members:
+    :exclude-members: __init__
+
+.. autofunction:: define_deformable_body_properties
+.. autofunction:: modify_deformable_body_properties
diff --git a/docs/source/api/lab/omni.isaac.lab.sim.spawners.rst b/docs/source/api/lab/omni.isaac.lab.sim.spawners.rst
@@ -8,6 +8,7 @@
   .. autosummary::
 
     shapes
+    meshes
     lights
     sensors
     from_files
@@ -19,6 +20,7 @@
 
     SpawnerCfg
     RigidObjectSpawnerCfg
+    DeformableObjectSpawnerCfg
 
 Spawners
 --------
@@ -32,6 +34,11 @@ Spawners
     :show-inheritance:
     :exclude-members: __init__
 
+.. autoclass:: DeformableObjectSpawnerCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__
+
 Shapes
 ------
 
@@ -87,6 +94,60 @@ Shapes
     :show-inheritance:
     :exclude-members: __init__, func
 
+Meshes
+------
+
+.. automodule:: omni.isaac.lab.sim.spawners.meshes
+
+  .. rubric:: Classes
+
+  .. autosummary::
+
+    MeshCfg
+    MeshCapsuleCfg
+    MeshConeCfg
+    MeshCuboidCfg
+    MeshCylinderCfg
+    MeshSphereCfg
+
+.. autoclass:: MeshCfg
+    :members:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_mesh_capsule
+
+.. autoclass:: MeshCapsuleCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_mesh_cone
+
+.. autoclass:: MeshConeCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_mesh_cuboid
+
+.. autoclass:: MeshCuboidCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_mesh_cylinder
+
+.. autoclass:: MeshCylinderCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__, func
+
+.. autofunction:: spawn_mesh_sphere
+
+.. autoclass:: MeshSphereCfg
+    :members:
+    :show-inheritance:
+    :exclude-members: __init__, func
 
 Lights
 ------
@@ -198,6 +259,7 @@ Materials
     GlassMdlCfg
     PhysicsMaterialCfg
     RigidBodyMaterialCfg
+    DeformableBodyMaterialCfg
 
 Visual Materials
 ~~~~~~~~~~~~~~~~
@@ -234,3 +296,9 @@ Physical Materials
 .. autoclass:: RigidBodyMaterialCfg
     :members:
     :exclude-members: __init__, func
+
+.. autofunction:: spawn_deformable_body_material
+
+.. autoclass:: DeformableBodyMaterialCfg
+    :members:
+    :exclude-members: __init__, func
diff --git a/docs/source/setup/sample.rst b/docs/source/setup/sample.rst
@@ -35,6 +35,12 @@ A few quick showroom scripts to run and checkout:
 
       ./isaaclab.sh -p source/standalone/demos/procedural_terrain.py
 
+-  Spawn different deformable (soft) bodies and let them fall from a height:
+
+   .. code:: bash
+
+      ./isaaclab.sh -p source/standalone/demos/deformables.py
+
 -  Spawn multiple markers that are useful for visualizations:
 
    .. code:: bash

diff --git a/docs/source/tutorials/00_sim/spawn_prims.rst b/docs/source/tutorials/00_sim/spawn_prims.rst
@@ -22,7 +22,7 @@ Let's take a look at the Python script:
 
    .. literalinclude:: ../../../../source/standalone/tutorials/00_sim/spawn_prims.py
       :language: python
-      :emphasize-lines: 40-79, 91-92
+      :emphasize-lines: 40-88, 100-101
       :linenos:
 
 
@@ -134,8 +134,17 @@ default to the default values set by USD Physics.
 .. literalinclude:: ../../../../source/standalone/tutorials/00_sim/spawn_prims.py
    :language: python
    :start-at: # spawn a green cone with colliders and rigid body
-   :end-before: # spawn a usd file of a table into the scene
+   :end-before: # spawn a blue cuboid with deformable body
+
+Lastly, we spawn a cuboid ``CuboidDeformable`` which contains deformable body physics properties. Unlike the
+rigid body simulation, a deformable body can have relative motion between its vertices. This is useful for simulating
+soft bodies like cloth, rubber, or jello. It is important to note that deformable bodies are only supported in
+GPU simulation and require a mesh object to be spawned with the deformable body physics properties.
 
+.. literalinclude:: ../../../../source/standalone/tutorials/00_sim/spawn_prims.py
+   :language: python
+   :start-at: # spawn a blue cuboid with deformable body
+   :end-before: # spawn a usd file of a table into the scene
 
 Spawning from another file
 --------------------------

diff --git a/source/extensions/omni.isaac.lab/config/extension.toml b/source/extensions/omni.isaac.lab/config/extension.toml
@@ -1,7 +1,7 @@
 [package]
 
 # Note: Semantic Versioning is used: https://semver.org/
-version = "0.19.2"
+version = "0.19.3"
 
 # Description
 title = "Isaac Lab framework for Robot Learning"

diff --git a/source/extensions/omni.isaac.lab/docs/CHANGELOG.rst b/source/extensions/omni.isaac.lab/docs/CHANGELOG.rst
@@ -1,13 +1,26 @@
 Changelog
 ---------
 
+0.19.3 (2024-07-13)
+~~~~~~~~~~~~~~~~~~~
+
+Added
+^^^^^
+
+* Added schemas for setting and modifying deformable body properties on a USD prim.
+* Added API to spawn a deformable body material in the simulation.
+* Added APIs to spawn rigid and deformable meshes of primitive shapes (cone, cylinder, sphere, box, capsule)
+  in the simulation. This is possible through the :mod:`omni.isaac.lab.sim.spawners.meshes` module.
+
+
 0.19.2 (2024-07-05)
 ~~~~~~~~~~~~~~~~~~~
 
 Changed
 ^^^^^^^
 
-* Modified cloning scheme based on the attribute :attr:`~omni.isaac.lab.scene.InteractiveSceneCfg.replicate_physics` to determine whether environment is homogeneous or heterogeneous.
+* Modified cloning scheme based on the attribute :attr:`~omni.isaac.lab.scene.InteractiveSceneCfg.replicate_physics`
+  to determine whether environment is homogeneous or heterogeneous.
 
 
 0.19.1 (2024-07-05)

diff --git a/source/extensions/omni.isaac.lab/omni/isaac/lab/sim/converters/mesh_converter.py b/source/extensions/omni.isaac.lab/omni/isaac/lab/sim/converters/mesh_converter.py
@@ -102,7 +102,7 @@ def _convert_asset(self, cfg: MeshConverterCfg):
                 # Apply collider properties to mesh
                 if cfg.collision_props is not None:
                     # -- Collision approximation to mesh
-                    # TODO: https://github.com/isaac-orbit/orbit/issues/163 Move this to a new Schema
+                    # TODO: Move this to a new Schema: https://github.com/isaac-orbit/IsaacLab/issues/163
                     mesh_collision_api = UsdPhysics.MeshCollisionAPI.Apply(child_mesh_prim)
                     mesh_collision_api.GetApproximationAttr().Set(cfg.collision_approximation)
                     # -- Collider properties such as offset, scale, etc.

diff --git a/source/extensions/omni.isaac.lab/omni/isaac/lab/sim/schemas/__init__.py b/source/extensions/omni.isaac.lab/omni/isaac/lab/sim/schemas/__init__.py
@@ -27,19 +27,21 @@
 
 Locally, the schemas are defined in the following files:
 
-* ``_isaac_sim/kit/extsPhysics/omni.usd.schema.physics/plugins/UsdPhysics/resources/UsdPhysics/schema.usda``
-* ``_isaac_sim/kit/extsPhysics/omni.usd.schema.physx/plugins/PhysxSchema/resources/PhysxSchema/schema.usda``
+* ``_isaac_sim/extsPhysics/omni.usd.schema.physics/plugins/UsdPhysics/resources/UsdPhysics/schema.usda``
+* ``_isaac_sim/extsPhysics/omni.usd.schema.physx/plugins/PhysxSchema/resources/generatedSchema.usda``
 
 """
 
 from .schemas import (
     activate_contact_sensors,
     define_articulation_root_properties,
     define_collision_properties,
+    define_deformable_body_properties,
     define_mass_properties,
     define_rigid_body_properties,
     modify_articulation_root_properties,
     modify_collision_properties,
+    modify_deformable_body_properties,
     modify_fixed_tendon_properties,
     modify_joint_drive_properties,
     modify_mass_properties,
@@ -48,6 +50,7 @@
 from .schemas_cfg import (
     ArticulationRootPropertiesCfg,
     CollisionPropertiesCfg,
+    DeformableBodyPropertiesCfg,
     FixedTendonPropertiesCfg,
     JointDrivePropertiesCfg,
     MassPropertiesCfg,