Add cloth object

docs/source/tutorial/create_cloth.rst

@@ -0,0 +1,100 @@
+Creating a cloth simulation
+===========================
+
+.. currentmodule:: embodichain.lab.sim
+
+This tutorial shows how to create a cloth simulation using ``SimulationManager``. It covers procedurally generating a grid mesh, configuring a deformable cloth object, adding a rigid body for interaction, and running the simulation loop.
+
+The Code
+~~~~~~~~
+
+The tutorial corresponds to the ``create_cloth.py`` script in the ``scripts/tutorials/sim`` directory.
+
+.. dropdown:: Code for create_cloth.py
+   :icon: code
+
+   .. literalinclude:: ../../../scripts/tutorials/sim/create_cloth.py
+      :language: python
+      :linenos:
+
+
+The Code Explained
+~~~~~~~~~~~~~~~~~~
+
+Generating the cloth mesh
+--------------------------
+
+Unlike the soft-body tutorial where a pre-existing mesh file is loaded, cloth objects are typically defined by a flat 2-D surface. The helper function ``create_2d_grid_mesh`` generates a rectangular grid mesh procedurally using PyTorch, then saves it to a temporary ``.ply`` file via Open3D so that the simulation can load it.
+
+Loading a mesh from file also works for cloth objects, but generating a grid in code allows for easy customization of the cloth dimensions and resolution. 
+
+The function accepts the physical dimensions (``width``, ``height``) and the number of subdivisions (``nx``, ``ny``). A finer grid gives more cloth-like wrinkle detail at the cost of simulation performance.
+
+.. literalinclude:: ../../../scripts/tutorials/sim/create_cloth.py
+   :language: python
+   :start-at: def create_2d_grid_mesh
+   :end-at:     return verts, faces
+
+Configuring the simulation
+--------------------------
+
+The simulation environment is configured with :class:`SimulationManagerCfg`. For cloth simulation the device must be set to ``cuda``. The ``arena_space`` parameter controls the spacing between parallel environments so that objects in neighboring environments do not overlap.
+
+.. literalinclude:: ../../../scripts/tutorials/sim/create_cloth.py
+   :language: python
+   :start-at: # Configure the simulation
+   :end-at:     print("[INFO]: Scene setup complete!")
+
+Adding a cloth object to the scene
+------------------------------------
+
+The grid mesh generated earlier is saved to disk and then passed to :meth:`SimulationManager.add_cloth_object`. The physical properties of the cloth are controlled through :class:`cfg.ClothObjectCfg` together with :class:`cfg.ClothPhysicalAttributesCfg`:
+
+- :class:`cfg.MeshCfg` — references the ``.ply`` file written to the system temp directory
+- :class:`cfg.ClothPhysicalAttributesCfg` — material parameters:
+
+  - ``mass`` — total mass of the cloth panel (kg)
+  - ``youngs`` / ``poissons`` — elastic stiffness and compressibility
+  - ``thickness`` — collision thickness of the cloth surface
+  - ``bending_stiffness`` / ``bending_damping`` — resistance to and dissipation of bending motion
+  - ``dynamic_friction`` — friction between the cloth and other objects
+  - ``min_position_iters`` — solver iteration count for position constraints
+
+.. literalinclude:: ../../../scripts/tutorials/sim/create_cloth.py
+   :language: python
+   :start-at:     cloth_verts, cloth_faces = create_2d_grid_mesh
+   :end-at:         )
+   :end-before:     padding_box_cfg
+
+Adding a rigid body for interaction
+-------------------------------------
+
+A small cubic rigid body (``padding_box``) is placed beneath the cloth so the cloth drapes over it. It is added with :meth:`SimulationManager.add_rigid_object` using :class:`cfg.RigidObjectCfg` and :class:`cfg.RigidBodyAttributesCfg`:
+
+- :class:`cfg.CubeCfg` — defines the box dimensions
+- ``body_type="dynamic"`` — the box responds to physics; change to ``"static"`` for a fixed obstacle
+- ``static_friction`` / ``dynamic_friction`` — surface friction keeps the cloth from sliding off too easily
+
+.. literalinclude:: ../../../scripts/tutorials/sim/create_cloth.py
+   :language: python
+   :start-at:     padding_box_cfg = RigidObjectCfg(
+   :end-at:     print("[INFO]: Add soft object complete!")
+
+The Code Execution
+~~~~~~~~~~~~~~~~~~
+
+To run the script and see the result, execute the following command:
+
+.. code-block:: bash
+
+   python scripts/tutorials/sim/create_cloth.py
+
+A window should appear showing a cloth panel falling and draping over a small rigid box. To stop the simulation, close the window or press ``Ctrl+C`` in the terminal.
+
+You can also pass arguments to customise the simulation. For example, to run in headless mode with ``n`` parallel environments:
+
+.. code-block:: bash
+
+   python scripts/tutorials/sim/create_cloth.py --headless --num_envs <n>
+
+Now that we have a basic understanding of how to create a cloth scene, let's move on to more advanced topics.

docs/source/tutorial/index.rst

@@ -7,6 +7,7 @@ Tutorials
 
    create_scene
    create_softbody
+   create_cloth
    rigid_object_group
    robot
    add_robot

embodichain/lab/sim/cfg.py

@@ -30,6 +30,7 @@
     VoxelConfig,
     SoftBodyAttr,
     SoftBodyMaterialModel,
+    ClothBodyAttr,
 )
 from embodichain.utils import configclass, is_configclass
 from embodichain.data.constants import EMBODICHAIN_DEFAULT_DATA_ROOT
@@ -384,6 +385,116 @@ def attr(self) -> SoftBodyAttr:
         return attr
 
 
+@configclass
+class ClothPhysicalAttributesCfg:
+    # material properties
+    youngs: float = 1e10
+    """Young's modulus (higher = stiffer)."""
+
+    poissons: float = 0.3
+    """Poisson's ratio."""
+
+    dynamic_friction: float = 0.5
+    """Dynamic friction coefficient."""
+
+    elasticity_damping: float = 0.0
+    """Elasticity damping factor."""
+
+    thickness: float = 0.001
+    """Cloth thickness (m)."""
+
+    bending_stiffness: float = 0.00001
+    """Bending stiffness."""
+
+    bending_damping: float = 0.0
+    """Bending damping."""
+
+    # cloth body properties
+    enable_kinematic: bool = False
+    """If True, (partially) kinematic behavior is enabled."""
+
+    enable_ccd: bool = True
+    """Enable continuous collision detection (CCD)."""
+
+    enable_self_collision: bool = False
+    """Enable self-collision handling."""
+
+    has_gravity: bool = True
+    """Whether the cloth is affected by gravity."""
+
+    self_collision_stress_tolerance: float = 0.9
+    """Stress tolerance threshold for self-collision constraints."""
+
+    collision_mesh_simplification: bool = True
+    """Whether to simplify the collision mesh for self-collision."""
+
+    vertex_velocity_damping: float = 0.005
+    """Per-vertex velocity damping."""
+
+    mass: float = -1.0
+    """Total mass of the cloth. If negative, density is used to compute mass."""
+
+    density: float = 1.0
+    """Material density in kg/m^3."""
+
+    max_depenetration_velocity: float = 1e6
+    """Maximum velocity used to resolve penetrations."""
+
+    max_velocity: float = 100.0
+    """Clamp for linear (or vertex) velocity."""
+
+    self_collision_filter_distance: float = 0.1
+    """Distance threshold for filtering self-collision vertex pairs."""
+
+    linear_damping: float = 0.05
+    """Global linear damping applied to the cloth."""
+
+    sleep_threshold: float = 0.05
+    """Velocity/energy threshold below which the cloth can go to sleep."""
+
+    settling_threshold: float = 0.1
+    """Threshold used to decide convergence/settling state."""
+
+    settling_damping: float = 10.0
+    """Additional damping applied during settling phase."""
+
+    min_position_iters: int = 4
+    """Minimum solver iterations for position correction."""
+
+    min_velocity_iters: int = 1
+    """Minimum solver iterations for velocity updates."""
+
+    def attr(self) -> ClothBodyAttr:
+        """Convert to dexsim ClothBodyAttr."""
+        attr = ClothBodyAttr()
+        attr.youngs = self.youngs
+        attr.poissons = self.poissons
+        attr.dynamic_friction = self.dynamic_friction
+        attr.elasticity_damping = self.elasticity_damping
+        attr.thickness = self.thickness
+        attr.bending_stiffness = self.bending_stiffness
+        attr.bending_damping = self.bending_damping
+        attr.enable_kinematic = self.enable_kinematic
+        attr.enable_ccd = self.enable_ccd
+        attr.enable_self_collision = self.enable_self_collision
+        attr.has_gravity = self.has_gravity
+        attr.self_collision_stress_tolerance = self.self_collision_stress_tolerance
+        attr.collision_mesh_simplification = self.collision_mesh_simplification
+        attr.vertex_velocity_damping = self.vertex_velocity_damping
+        attr.mass = self.mass
+        attr.density = self.density
+        attr.max_depenetration_velocity = self.max_depenetration_velocity
+        attr.max_velocity = self.max_velocity
+        attr.self_collision_filter_distance = self.self_collision_filter_distance
+        attr.linear_damping = self.linear_damping
+        attr.sleep_threshold = self.sleep_threshold
+        attr.settling_threshold = self.settling_threshold
+        attr.settling_damping = self.settling_damping
+        attr.min_position_iters = self.min_position_iters
+        attr.min_velocity_iters = self.min_velocity_iters
+        return attr
+
+
 @configclass
 class JointDrivePropertiesCfg:
     """Properties to define the drive mechanism of a joint."""
@@ -592,6 +703,21 @@ class SoftObjectCfg(ObjectBaseCfg):
     """Mesh configuration for the soft body."""
 
 
+@configclass
+class ClothObjectCfg(ObjectBaseCfg):
+    """Configuration for a cloth body asset in the simulation.
+
+    This class extends the base asset configuration to include specific properties for cloth bodies,
+    such as physical attributes and collision group.
+    """
+
+    physical_attr: ClothPhysicalAttributesCfg = ClothPhysicalAttributesCfg()
+    """Physical attributes for the cloth body."""
+
+    shape: MeshCfg = MeshCfg()
+    """Mesh configuration for the cloth body."""
+
+
 @configclass
 class RigidObjectGroupCfg:
     """Configuration for a rigid object group asset in the simulation.

embodichain/lab/sim/common.py

@@ -24,6 +24,7 @@
 
 from embodichain.lab.sim.cfg import ObjectBaseCfg
 from embodichain.utils import logger
+import dexsim
 from copy import deepcopy
 
 T = TypeVar("T")

embodichain/lab/sim/objects/__init__.py

@@ -22,6 +22,7 @@
     RigidObjectGroupCfg,
 )
 from .soft_object import SoftObject, SoftBodyData, SoftObjectCfg
+from .cloth_object import ClothObject, ClothBodyData, ClothObjectCfg
 from .articulation import Articulation, ArticulationData, ArticulationCfg
 from .robot import Robot, RobotCfg
 from .light import Light, LightCfg