soft_body_particles
The state of a soft-body is the state of its particles, which are identified by their index in the body. Their positions
and their velocities can be read (particle_position, particle_positions, particle_velocity, particle_velocities) and modified (set_particle_position, set_particle_velocity) at any time, one by one or all at
once. The elements built from them (edges, cells, and boundary) can be read as well, e.g., in order to render the body with your own mesh. The arrays of every particle and of every element are NumPy arrays with one row per particle or per element, e.g., of shape (N, 3) for the positions and (B, 3) for the boundary triangles. All the positions (or velocities) are modified at once by assigning such an array to particle_positions (or particle_velocities). A snapshot of all the properties of a particle (its mass, its rest position, whether it is pinned, etc.) is given by particle.
A particle can also be pinned (set_particle_pinned). A pinned particle is kinematic: it is no longer affected by the forces
nor by the contacts, and it will simply hold its position, or follow the kinematic target
(set_particle_kinematic_target) or the velocity it is given. This is, e.g., how a piece of cloth
is hung on a wall, or how a rope is dragged by the player. Releasing the particle gives it back its nominal mass and
lets it keep its current velocity:
soft_body = world.soft_bodies[cloth_handle]
# Read the particles.
position = soft_body.particle_position(0)
velocity = soft_body.particle_velocity(0)
# All the positions (or velocities) at once, as an (N, 3) NumPy array.
positions = soft_body.particle_positions
assert positions.shape == (soft_body.num_particles, 3)
# Move a particle.
soft_body.set_particle_position(1, position + rp.Vec3(0.0, 0.1, 0.0))
soft_body.set_particle_velocity(1, velocity)
# Pin (or release) a particle; a pinned particle can be driven like a kinematic body.
soft_body.set_particle_pinned(2, True)
soft_body.set_particle_kinematic_target(2, (-1.0, 2.5, -0.8))
# The elements, as NumPy arrays of particle indices: edges, cells and the boundary triangles.
edges = soft_body.edges # Shape (E, 2).
cells = soft_body.cells # Shape (C, 4).
boundary = soft_body.boundary # Shape (B, 3).
assert len(edges) > 0 and len(cells) == 0 and len(boundary) > 0
Setting the position of a particle explicitly teleports it: no contact is taken into account along the way, so a particle can be moved inside of another object this way. Whenever the motion must be seen by the contacts and by the friction (to drag a piece of cloth, for example), it is recommended to pin the particle and to give it a kinematic target instead.
Controlling a region kinematically
A whole region of the body is controlled at once through a cluster covering it. Pinning
the cluster (set_cluster_pinned) pins all of its particles, and its kinematic target
(set_cluster_kinematic_target) moves them
rigidly: each pinned particle is sent where the rest shape of the cluster places it at the target pose, with the
matching velocity. The rest of the body is then simulated as usual, and drags behind the controlled region, e.g., the
hand of a soft character carrying something:
# Pin every particle of the cluster, then move it along a path: the cluster behaves like a
# kinematic rigid part dragging the rest of the body.
jelly = world.soft_bodies[jelly_handle]
jelly.set_cluster_pinned(cluster, True)
jelly.set_cluster_kinematic_target(cluster, rp.Isometry3(translation=(3.0, 2.0, 0.0)))
# Release it: the cluster is simulated again.
jelly.set_cluster_pinned(cluster, False)