soft_body_creation_and_insertion

A soft-body is described by a SoftBodyBuilder, which constructors build the lattice of the most common shapes (static methods of the SoftBody class, e.g., SoftBody.cloth):

Constructor	Lattice
`SoftBodyBuilder(positions)`	No element at all: only the given particles.
`SoftBody.rope`	Structural and bending edges between the particles of a line.
`SoftBody.cloth`, `SoftBody.cloth_anisotropic`, `SoftBody.cloth_tube`	Structural, shear and bending edges, with a triangle surface.
`SoftBody.cuboid`	Tetrahedral cells filling a box.
`SoftBody.sphere`	A closed surface preserving its volume, with dihedral bending constraints.
`SoftBody.trimesh`	The vertices and edges of a triangle mesh, held by shape matching.
`SoftBody.volumetric`, `SoftBody.volumetric_with`	Cells filling a closed mesh.

Every constructor returns a SoftBodyBuilder, which setters return a modified copy of the builder so they can be chained. These setters can also be given as keyword arguments of the constructors, e.g., SoftBody.rope(a, b, 20, particle_mass=0.1, pinned_particles=[0]).

The volumetric constructor is the one to use for an arbitrary solid: it fills a closed mesh (segments in 2D, triangles in 3D, oriented outward) with cells of about the requested size. The interior of the mesh is triangulated by Delaunay refinement in 2D, whereas in 3D every cell of a lattice the mesh reaches is kept whole: the result contains the mesh instead of following it exactly, and its boundary is as blocky as its cells. The meshing parameters are spelled out by volumetric_with, which takes a VolumeMeshParameters: the size of the cells (cell_size), how much the cover is smoothed (cover_smoothing) and subdivided (cover_subdivisions) around the boundary, i.e., how closely it follows the mesh, and whether the surface alone is covered (enclosure set to MeshEnclosure.CRUST), leaving the interior empty. Both constructors raise a MeshConversionError if the mesh isn't closed, or encloses nothing at that cell size.

# Fill a closed, outward-oriented triangle mesh with tetrahedral cells of about 0.2 in size;
# this raises a `MeshConversionError` if the mesh isn't closed or encloses no volume.
vertices, indices = rp.Cuboid((0.5, 0.25, 0.25)).to_trimesh()
block = rp.SoftBody.volumetric(vertices, indices, 0.2).translated((-3.0, 1.0, 0.0))
block_handle = world.add_soft_body(block)

# The same, with the meshing parameters spelled out: the cover of the mesh is subdivided
# once around its boundary, then smoothed, so it follows the mesh more closely.
params = rp.VolumeMeshParameters(0.2, cover_subdivisions=1, cover_smoothing=4)
smooth_block = rp.SoftBody.volumetric_with(vertices, indices, params)
smooth_block_handle = world.add_soft_body(smooth_block.translated((-3.0, 2.0, 0.0)))

The builder allows the definition of everything else that is specific to one soft-body: the particles held in place (the pinned particles, pinned_particles), the softness of its constraints (softness), the mass of its particles (one mass for every particle with particle_mass, a total mass for the whole body with mass, or one mass per particle with masses), their radius (particle_radius), the collider its surface is made of, and whether that surface is allowed to collide with itself (self_contacts). The particles can also be given a linear damping (linear_damping), a gravity scale (gravity_scale), a dominance group (SoftBodyParticleSettings.dominance_group, given with particle_settings), and be allowed to sleep or not (can_sleep), exactly like a rigid-body. Inserting the soft-body into the world (PhysicsWorld.add_soft_body) will automatically create the rigid-body standing for it (its root body), as well as the colliders covering its surface:

# A world with a ground.
world = rp.PhysicsWorld(gravity=(0.0, -9.81, 0.0))
world.add_collider(rp.Collider.cuboid(10.0, 0.1, 10.0))

# Builder for a rope of 20 particles between two points.
_ = rp.SoftBody.rope((0.0, 3.0, 0.0), (2.0, 3.0, 0.0), 20)
# Builder for a cloth: `nu` by `nv` particles, particle `(i, j)` at `origin + i * du + j * dv`.
_ = rp.SoftBody.cloth((-1.0, 2.0, -1.0), (0.1, 0.0, 0.0), (0.0, 0.0, 0.1), 20, 20)
# Builder for a box of `nx * ny * nz` particles filled with tetrahedral cells.
_ = rp.SoftBody.cuboid((3.0, 1.0, 0.0), (0.5, 0.5, 0.5), 4, 4, 4)
# Builder for a hollow sphere holding its volume (a balloon).
_ = rp.SoftBody.sphere((0.0, 3.0, 3.0), 0.8, 2)
# Builder over raw particle positions; the elements are added by the setters.
_ = rp.SoftBodyBuilder([(0.0, 3.0, 0.0), (1.0, 3.0, 0.0)]).edges([(0, 1)])
n = 20
cloth = (
    rp.SoftBody.cloth((-1.0, 2.0, -1.0), (0.1, 0.0, 0.0), (0.0, 0.0, 0.1), n, n)
    # Particles held in place.
    .pinned_particles([0, n - 1, n * (n - 1), n * n - 1])
    # A uniform softness (natural frequency in Hz, damping ratio) for every constraint.
    .softness(rp.SpringCoefficients(30.0, 1.0))
    # The mass of each particle.
    # Default: 1.0
    .particle_mass(0.05)
    # The thickness of the particles, for collisions.
    # Default: 0.01
    .particle_radius(0.02)
    # The template of the body's colliders: its shape is replaced by the deformable surface.
    .surface_collider(rp.Collider.ball(0.05).friction(0.8))
    # Whether the surface collides with itself.
    # Default: False
    .self_contacts(True)
    # Whether the body may fall asleep.
    # Default: True
    .can_sleep(True)
)
# The setters can also be given as keyword arguments of the constructors.
_ = rp.SoftBody.rope((0.0, 3.0, 0.0), (2.0, 3.0, 0.0), 20, particle_mass=0.1, pinned_particles=[0])
# Insert the soft body: this creates its hidden root rigid body and its colliders.
cloth_handle = world.add_soft_body(cloth)

info

The collider given to SoftBodyBuilder.surface_collider is only a template: its shape is replaced by the deformable surface of the soft-body, and its density is ignored, whereas all its other properties are kept. Therefore this is where the friction, the collision groups, or the active events of the soft-body must be set. A body that should only collide through colliders of your own can be built without any default one (no_surface_collider).

tip

Two builders can be merged into a single soft-body with append, and their pieces sewn together with additional edges (add_edges), which rest length is the distance their particles have when they are added. This is, e.g., how the sleeves of a shirt are attached to its body.