Adds APIs for spawning deformable meshes

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/schemas/__init__.py

@@ -27,8 +27,8 @@
 
 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``
 
 """
 
@@ -38,12 +38,14 @@
     define_collision_properties,
     define_mass_properties,
     define_rigid_body_properties,
+    define_deformable_body_properties,
     modify_articulation_root_properties,
     modify_collision_properties,
     modify_fixed_tendon_properties,
     modify_joint_drive_properties,
     modify_mass_properties,
     modify_rigid_body_properties,
+    modify_deformable_body_properties,
 )
 from .schemas_cfg import (
     ArticulationRootPropertiesCfg,
@@ -52,4 +54,5 @@
     JointDrivePropertiesCfg,
     MassPropertiesCfg,
     RigidBodyPropertiesCfg,
+    DeformableBodyPropertiesCfg,
 )

source/extensions/omni.isaac.lab/omni/isaac/lab/sim/schemas/schemas.py

@@ -9,9 +9,10 @@
 import carb
 import omni.isaac.core.utils.stage as stage_utils
 import omni.physx.scripts.utils as physx_utils
+from omni.physx.scripts import deformableUtils
 from pxr import PhysxSchema, Usd, UsdPhysics
 
-from ..utils import apply_nested, find_global_fixed_joint_prim, safe_set_attribute_on_usd_schema
+from ..utils import apply_nested, find_global_fixed_joint_prim, safe_set_attribute_on_usd_schema, get_all_matching_child_prims
 from . import schemas_cfg
 
 """
@@ -538,7 +539,7 @@ def modify_joint_drive_properties(
     .. caution::
 
         We highly recommend modifying joint properties of articulations through the functionalities in the
-        :mod:`omni.isaac.lab.actuators` module. The methods here are for setting simulation low-level
+        :mod:`omni.isaac.orbit.actuators` module. The methods here are for setting simulation low-level
         properties only.
 
     .. _UsdPhysics.DriveAPI: https://openusd.org/dev/api/class_usd_physics_drive_a_p_i.html
@@ -651,3 +652,157 @@ def modify_fixed_tendon_properties(
             safe_set_attribute_on_usd_schema(physx_tendon_axis_api, attr_name, value, camel_case=True)
     # success
     return True
+
+
+"""
+Deformable body properties.
+"""
+
+
+def define_deformable_body_properties(
+    prim_path: str, cfg: schemas_cfg.DeformableBodyPropertiesCfg, stage: Usd.Stage | None = None
+):
+    """Apply the deformable body schema on the input prim and set its properties.
+
+    See :func:`modify_deformable_body_properties` for more details on how the properties are set.
+
+    Args:
+        prim_path: The prim path where to apply the deformable body schema.
+        cfg: The configuration for the deformable body.
+        stage: The stage where to find the prim. Defaults to None, in which case the
+            current stage is used.
+
+    Raises:
+        ValueError: When the prim path is not valid.
+        TypeError: When the prim already has conflicting API schemas.
+    """
+    # obtain stage
+    if stage is None:
+        stage = stage_utils.get_current_stage()
+    # get USD prim
+    prim = stage.GetPrimAtPath(prim_path)
+    # check if prim path is valid
+    if not prim.IsValid():
+        raise ValueError(f"Prim path '{prim_path}' is not valid.")
+
+    # traverse the prim and get the mesh
+    matching_prims = get_all_matching_child_prims(prim_path, lambda p: p.GetTypeName() == "Mesh")
+    # check if the mesh is valid
+    if len(matching_prims) == 0:
+        raise ValueError(f"Could not find any mesh in '{prim_path}'. Please check asset.")
+    elif len(matching_prims) > 1:
+        # get list of all meshes found
+        mesh_paths = [p.GetPrimPath() for p in matching_prims]
+        raise ValueError(
+            f"Found multiple meshes in '{prim_path}': {mesh_paths}."
+            " Deformable body schema can only be applied to one mesh."
+        )
+
+    # get deformable-body USD prim
+    mesh_prim = matching_prims[0]
+    # check if prim has deformable-body applied on it
+    if not PhysxSchema.PhysxDeformableBodyAPI(mesh_prim):
+        PhysxSchema.PhysxDeformableBodyAPI.Apply(mesh_prim)
+    # set deformable body properties
+    modify_deformable_body_properties(mesh_prim.GetPrimPath(), cfg, stage)
+
+
+@apply_nested
+def modify_deformable_body_properties(
+    prim_path: str, cfg: schemas_cfg.DeformableBodyPropertiesCfg, stage: Usd.Stage | None = None
+):
+    """Modify PhysX parameters for a deformable body prim.
+
+    A `deformable body`_ is a single body that can be simulated by PhysX. Unlike rigid bodies, deformable bodies
+    support relative motion of the nodes in the mesh. Consequently, they can be used to simulate deformations
+    under applied forces.
+
+    PhysX soft body simulation employs Finite Element Analysis (FEA) to simulate the deformations of the mesh.
+    It uses two tetrahedral meshes to represent the deformable body:
+
+    1. **Simulation mesh**: This mesh is used for the simulation and is the one that is deformed by the solver.
+    2. **Collision mesh**: This mesh only needs to match the surface of the simulation mesh and is used for
+       collision detection.
+
+    For most applications, we assume that the above two meshes are computed from the "render mesh" of the deformable
+    body. The render mesh is the mesh that is visible in the scene and is used for rendering purposes. It is composed
+    of triangles and is the one that is used to compute the above meshes based on PhysX cookings.
+
+    The schema comprises of attributes that belong to the `PhysxDeformableBodyAPI`_. schemas containing the PhysX
+    parameters for the deformable body.
+
+    .. note::
+        We assume that the USD file for a deformable body contains a single mesh.
+        If the USD file contains multiple meshes, then the first mesh is used.
+
+    .. _deformable body: https://nvidia-omniverse.github.io/PhysX/physx/5.4.0/docs/SoftBodies.html
+    .. _PhysxDeformableBodyAPI: https://docs.omniverse.nvidia.com/kit/docs/omni_usd_schema_physics/104.2/class_physx_schema_physx_deformable_a_p_i.html
+
+    Args:
+        prim_path: The prim path to the deformable body.
+        cfg: The configuration for the deformable body.
+        stage: The stage where to find the prim. Defaults to None, in which case the
+            current stage is used.
+
+    Returns:
+        True if the properties were successfully set, False otherwise.
+
+    Raises:
+        ValueError: If the input prim path is not valid.
+        ValueError: If the input prim path does not contain a mesh or contains multiple meshes.
+    """
+    # obtain stage
+    if stage is None:
+        stage = stage_utils.get_current_stage()
+
+    # get deformable-body USD prim
+    deformable_body_prim = stage.GetPrimAtPath(prim_path)
+
+    # check if the prim is valid and has the deformable-body API
+    if not deformable_body_prim.IsValid() or not PhysxSchema.PhysxDeformableBodyAPI(deformable_body_prim):
+        return False
+
+    # retrieve the physx deformable-body api
+    physx_deformable_body_api = PhysxSchema.PhysxDeformableBodyAPI(deformable_body_prim)
+    # retrieve the physx deformable api
+    physx_deformable_api = PhysxSchema.PhysxDeformableAPI(physx_deformable_body_api)
+
+    # convert to dict
+    cfg = cfg.to_dict()
+    # set into deformable body API
+    attr_kwargs = {
+        attr_name: cfg.pop(attr_name)
+        for attr_name in [
+            "kinematic_enabled",
+            "collision_simplification",
+            "collision_simplification_remeshing",
+            "collision_simplification_remeshing_resolution",
+            "collision_simplification_target_triangle_count",
+            "collision_simplification_force_conforming",
+            "simulation_hexahedral_resolution",
+            "solver_position_iteration_count",
+            "vertex_velocity_damping",
+            "sleep_damping",
+            "sleep_threshold",
+            "settling_threshold",
+            "self_collision",
+            "self_collision_filter_distance",
+        ]
+    }
+    status = deformableUtils.add_physx_deformable_body(stage, prim_path=prim_path, **attr_kwargs)
+    # check if the deformable body was successfully added
+    if not status:
+        return False
+
+    # obtain the PhysX collision API (this is set when the deformable body is added)
+    physx_collision_api = PhysxSchema.PhysxCollisionAPI(deformable_body_prim)
+
+    # set into PhysX API
+    for attr_name, value in cfg.items():
+        if attr_name in ["rest_offset", "collision_offset"]:
+            safe_set_attribute_on_usd_schema(physx_collision_api, attr_name, value, camel_case=True)
+        else:
+            safe_set_attribute_on_usd_schema(physx_deformable_api, attr_name, value, camel_case=True)
+
+    # success
+    return True