raisim::DeformableObject

class · #include <raisim/object/deformable/DeformableObject.hpp>

A position-based (XPBD/PBD) deformable body made of particles connected by distance constraints (mesh edges plus optional extra edges) and, for cloth, bending constraints between adjacent triangles. With a Young's modulus, triangle meshes are elastic membranes and tetrahedral meshes elastic solids. Create it with World::addDeformableCloth(), World::addDeformableObject() or World::addDeformableVolume(). Each particle collides as a sphere of radius Material::collisionRadius. localIdx is a particle index. For closed meshes, particles are shifted inward by the collision radius so that the collision surface matches the input mesh; getVisualPosition() returns the unshifted position.

Contacts with rigid bodies, articulated systems and terrain are solved inside the deformable's own substep loop, together with its elastic constraints: the elastic projection cannot pull a particle through a body, and every contact impulse also acts on the (dynamic) body through its apparent inertia at the contact point. These contacts are inelastic, use Coulomb friction, and include speculative ones (Contact::getDepth() > 0) for particles that may reach a body during the step. Contacts between two deformables are solved by the world's contact solver.

Nested classes

struct InternalStrutOptions — Extra distance constraints between interior/surface particles to make volumes stiffer.
struct Material — Material and solver parameters.
struct MeshBuildOptions — Options for building a deformable from an OBJ mesh.
struct MeshParticleOptions — How particles are generated from an OBJ mesh (see loadObj(const std::string&, const std::vector<unsigned int>&, const Material&, const MeshBuildOptions&)).

Public types

SolverMode

cpp

enum class SolverMode

Constraint projection scheme.

Enumerator	Description
`XPBD`	Extended PBD: uses the compliance parameters (time-step independent stiffness).
`PBD`	Plain PBD: constraints are projected rigidly (compliance is ignored).

Triangle

cpp

using Triangle = std::array<unsigned int, 3>

Vertex indices of a triangle.

DistanceEdge

cpp

using DistanceEdge = std::array<unsigned int, 2>

Particle indices of a distance constraint.

Tetrahedron

cpp

using Tetrahedron = std::array<unsigned int, 4>

Vertex indices of a tetrahedron.

Constructors & destructor

DeformableObject

cpp

DeformableObject(
    const std::vector<Vec<3>> &vertices,
    const std::vector<Triangle> &triangles,
    const std::vector<unsigned int> &pinnedVertices,
    const Material &material,
    const std::vector<DistanceEdge> &extraDistanceEdges={})

Parameters

Parameter	Description
`vertices` (in)	particle positions in the world frame (m); at least one
`triangles` (in)	mesh triangles (used for distance and bending constraints and visualization)
`pinnedVertices` (in)	indices of particles held fixed at their initial positions
`material` (in)	material and solver parameters
`extraDistanceEdges` (in)	additional distance constraints (duplicates of mesh edges are skipped)

~DeformableObject

cpp

~DeformableObject() override

out-of-line so that the member vectors, which the library allocates, are also destroyed in the library translation unit

Public member functions

getObjectType

cpp

ObjectType getObjectType() const final

Returns DEFORMABLE.

getMass

cpp

double getMass(size_t localIdx) const final

Parameters

Parameter	Description
`localIdx` (in)	particle index

Returns the particle mass (kg); infinity for pinned particles

getBodyType

cpp

BodyType getBodyType(size_t localIdx) const final

Parameters

Parameter	Description
`localIdx` (in)	particle index

Returns STATIC for pinned particles, DYNAMIC otherwise

updateCollision

cpp

void updateCollision() final

Internal: synchronizes the collision geometry with the current pose.

updateContactAabbs

cpp

void updateContactAabbs() final

Internal: recomputes the world-frame AABBs used by the broadphase.

preContactSolverUpdate1

cpp

void preContactSolverUpdate1(const Vec<3> &gravity, double dt) final

Internal: first per-step update before the contact solver (called by World).

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration (m/s^2)
`dt` (in)	time step (s)

preContactSolverUpdate2

cpp

void preContactSolverUpdate2(
    const Vec<3> &gravity,
    double dt,
    contact::ContactProblems &problems) final

Internal: second per-step update before the contact solver (called by World).

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration (m/s^2)
`dt` (in)	time step (s)
`problems` (in, out)	contact problems of the world

integrate

cpp

void integrate(double dt, class World &world) final

Internal: integrates the state after the contact solve (called by World).

Parameters

Parameter	Description
`dt` (in)	time step (s)
`world` (in)	the owning world

setExternalForce

cpp

void setExternalForce(size_t localIdx, const Vec<3> &force) final

apply forces at the Center of Mass

Parameters

Parameter	Description
`localIdx` (in)	local body index
`force` (in)	force in the world frame (N)

cpp

void setExternalForce(
    size_t localIdx,
    const Vec<3> &pos,
    const Vec<3> &force) final

Same as setExternalForce(size_t, const Vec<3>&): the force acts on the particle and pos is only recorded for visualization.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos` (in)	application point (recorded only)
`force` (in)	force in the world frame (N)

setExternalTorque

cpp

void setExternalTorque(size_t localIdx, const Vec<3> &torque) final

Particles have no rotational state; this call is ignored.

Parameters

Parameter	Description
`localIdx` (in)	unused
`torque` (in)	unused

setConstraintForce

cpp

void setConstraintForce(
    size_t localIdx,
    const Vec<3> &pos,
    const Vec<3> &force) final

Internal: apply a constraint force (expressed in the world frame) at specific location of the body (expressed in the body frame). Unlike setExternalForce(), it is not visualized.

Parameters

Parameter	Description
`localIdx` (in)	local body index
`pos` (in)	application point in the body frame
`force` (in)	force in the world frame (N)

clearExternalForcesAndTorques

cpp

void clearExternalForcesAndTorques() final

Remove all external forces set for the next step.

getPosition

cpp

void getPosition(size_t localIdx, Vec<3> &pos_w) const final

get the position of a local body (its body frame origin) or particle.

Parameters

Parameter	Description
`localIdx` (in)	local body (or particle) index
`pos_w` (out)	position in the world frame (m)

cpp

void getPosition(
    size_t localIdx,
    const Vec<3> &pos_b,
    Vec<3> &pos_w) const final

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos_b` (in)	offset from the particle (world-aligned)
`pos_w` (out)	particle position + pos_b

getVelocity

cpp

void getVelocity(size_t localIdx, Vec<3> &vel_w) const final

get the linear velocity of a local body or particle.

Parameters

Parameter	Description
`localIdx` (in)	local body (or particle) index
`vel_w` (out)	linear velocity in the world frame (m/s)

cpp

void getVelocity(
    size_t localIdx,
    const Vec<3> &pos_b,
    Vec<3> &vel_w) const final

Returns the particle velocity; pos_b is ignored.

Parameters

Parameter	Description
`localIdx` (in)	particle index
`pos_b` (in)	ignored
`vel_w` (out)	velocity in the world frame (m/s)

getOrientation

cpp

void getOrientation(size_t localIdx, Mat<3, 3> &rot) const final

Particles have no orientation state: rot is always the identity.

Parameters

Parameter	Description
`localIdx` (in)	unused
`rot` (out)	identity

getContactPointVel

cpp

void getContactPointVel(size_t pointId, Vec<3> &vel) const final

get the contact point velocity used by the contact solver (the velocity being solved for, not the state before the step). For single bodies, articulated systems and deformable objects, it is expressed in the contact frame (z is the contact normal).

Parameters

Parameter	Description
`pointId` (in)	the contact index. This is an index of a contact in the contact vector that you can retrieve from getContacts().
`vel` (out)	the contact point velocity

getNumParticles

cpp

size_t getNumParticles() const

Returns the number of particles.

getPositions

cpp

const std::vector<Vec<3>> &getPositions() const

Returns particle (collision) positions in the world frame (m).

getVelocities

cpp

const std::vector<Vec<3>> &getVelocities() const

Returns particle velocities in the world frame (m/s).

getTriangles

cpp

const std::vector<Triangle> &getTriangles() const

Returns the mesh triangles (the surface, for a tetrahedral volume).

getTetrahedra

cpp

const std::vector<Tetrahedron> &getTetrahedra() const

Returns the tetrahedra of a volume (empty for a surface).

getVisualPosition

cpp

Vec<3> getVisualPosition(size_t idx) const

Parameters

Parameter	Description
`idx` (in)	particle index

Returns the particle position without the inward collision-radius shift applied to closed meshes (m)

getDistanceConstraintCount

cpp

size_t getDistanceConstraintCount() const

Returns the number of distance constraints.

getBendingConstraintCount

cpp

size_t getBendingConstraintCount() const

Returns the number of bending constraints.

getMaterial

cpp

const Material &getMaterial() const

Returns the material.

getCollisionBodyAt

cpp

CollisionBodyHandlePtr getCollisionBodyAt(size_t idx)

Internal: the collision body used for broadphase registration.

Parameters

Parameter	Description
`idx` (in)	must be 0

Returns the collision body, or nullptr if idx is not 0 or the object was removed

getCollisionBodyCount

cpp

size_t getCollisionBodyCount() const

Returns 1 while the object is in a world, 0 after removal.

setPositionOffset

cpp

void setPositionOffset(const Vec<3> &offset)

Translate all particles (including pinned rest positions).

Parameters

Parameter	Description
`offset` (in)	translation in the world frame (m)

applyRigidTransform

cpp

void applyRigidTransform(
    const Vec<3> &translation,
    const Mat<3, 3> &rotation)

Rotate all particles about the world origin, then translate them. Velocities and pending forces are rotated too.

Parameters

Parameter	Description
`translation` (in)	translation in the world frame (m)
`rotation` (in)	rotation matrix

pinVertex

cpp

void pinVertex(size_t idx)

Pin a particle at its current position (infinite mass).

Parameters

Parameter	Description
`idx` (in)	particle index

unpinVertex

cpp

void unpinVertex(size_t idx, double mass)

Release a pinned particle.

Parameters

Parameter	Description
`idx` (in)	particle index
`mass` (in)	new particle mass (kg), positive

addDistanceConstraint

cpp

void addDistanceConstraint(unsigned int i, unsigned int j)

Add a distance constraint whose rest length is the current distance between the two particles. Ignored if i == j.

Parameters

Parameter	Description
`i` (in)	first particle index
`j` (in)	second particle index

addDistanceConstraints

cpp

void addDistanceConstraints(const std::vector<DistanceEdge> &edges)

Add distance constraints (see addDistanceConstraint()), skipping pairs that already have one.

Parameters

Parameter	Description
`edges` (in)	particle index pairs

addInternalStruts

cpp

void addInternalStruts(const InternalStrutOptions &options)

Add strut constraints computed from the rest positions.

Parameters

Parameter	Description
`options` (in)	strut options

setGravity

cpp

void setGravity(const Vec<3> &gravity)

Internal: gravity used by the solver. World overwrites it with its own gravity every step.

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration (m/s^2)

Static member functions

loadObj static

cpp

static DeformableObject *loadObj(
    const std::string &fileName,
    double scale,
    const std::vector<unsigned int> &pinnedVertices,
    const Material &material)

Create a deformable from an OBJ mesh using its vertices as particles.

Parameters

Parameter	Description
`fileName` (in)	OBJ file
`scale` (in)	uniform scale applied to the vertices
`pinnedVertices` (in)	indices of pinned particles
`material` (in)	material and solver parameters

Returns a new object allocated with new; the caller owns it unless it is handed to a World

cpp

static DeformableObject *loadObj(
    const std::string &fileName,
    const std::vector<unsigned int> &pinnedVertices,
    const Material &material,
    const MeshBuildOptions &options)

Create a deformable from an OBJ mesh with resampled (and optionally filled) particles and optional struts.

Parameters

Parameter	Description
`fileName` (in)	OBJ file
`pinnedVertices` (in)	indices of pinned particles (in the generated particle list)
`material` (in)	material and solver parameters
`options` (in)	particle and strut generation options

Returns a new object allocated with new; the caller owns it unless it is handed to a World

createVolume static

cpp

static DeformableObject *createVolume(
    const std::vector<Vec<3>> &vertices,
    const std::vector<Tetrahedron> &tetrahedra,
    const std::vector<unsigned int> &pinnedVertices,
    const Material &material)

Create an elastic solid from a tetrahedral mesh. Its surface (the faces that belong to one tetrahedron) is used for visualization, and the particles on it are shifted inward by the collision radius like those of a closed triangle mesh (see the class description). The mass is lumped by volume. With a positive Material::youngsModulus the tetrahedra are elastic solid elements; otherwise their edges are distance constraints.

Parameters

Parameter	Description
`vertices` (in)	particle positions in the world frame (m)
`tetrahedra` (in)	vertex indices of the tetrahedra (either orientation)
`pinnedVertices` (in)	indices of particles held fixed at their initial positions
`material` (in)	material and solver parameters

Returns a new object allocated with new; the caller owns it unless it is handed to a World

Inherited members

From raisim::Object: addContactToPerObjectContact, clearPerObjectContact, getContactAabb, getContactAabbCount, getContacts, getExternalForce, getExternalForcePosition, getExternalTorque, getExternalTorquePosition, getId, getIndexInWorld, getName, getRenderRevision, Id, lock, lockMutex, setIndexInWorld, setName, try_lock, unlock, unlockMutex

AlignedAllocator

Rasset

RayCollisionList

World

Compound

Mesh

FileCache

ArticulatedSystem

DeformableTerrain

DeformableObject

GranularPoolSleepController

GranularSystem

Tendon

TendonCoupling

DepthCamera

InertialMeasurementUnit

RGBCamera

SpinningLidar

contact

BisectionContactSolver

mjcf

rscene

server

SceneFileServer

server::scene_files

urdf

raisim::DeformableObject ​

Nested classes ​

Public types ​

SolverMode ​

Triangle ​

DistanceEdge ​

Tetrahedron ​

Constructors & destructor ​

DeformableObject ​

~DeformableObject ​

Public member functions ​

getObjectType ​

getMass ​

getBodyType ​

updateCollision ​

updateContactAabbs ​

preContactSolverUpdate1 ​

preContactSolverUpdate2 ​

integrate ​

setExternalForce ​

setExternalTorque ​

setConstraintForce ​

clearExternalForcesAndTorques ​

getPosition ​

getVelocity ​

getOrientation ​

getContactPointVel ​

getNumParticles ​

getPositions ​

getVelocities ​

getTriangles ​

getTetrahedra ​

getVisualPosition ​

getDistanceConstraintCount ​

getBendingConstraintCount ​

getMaterial ​

getCollisionBodyAt ​

getCollisionBodyCount ​

setPositionOffset ​

applyRigidTransform ​

pinVertex ​

unpinVertex ​

addDistanceConstraint ​

addDistanceConstraints ​

addInternalStruts ​

setGravity ​

Static member functions ​

loadObj static ​

createVolume static ​

Inherited members ​

raisim::DeformableObject

Nested classes

Public types

SolverMode

Triangle

DistanceEdge

Tetrahedron

Constructors & destructor

DeformableObject

~DeformableObject

Public member functions

getObjectType

getMass

getBodyType

updateCollision

updateContactAabbs

preContactSolverUpdate1

preContactSolverUpdate2

integrate

setExternalForce

setExternalTorque

setConstraintForce

clearExternalForcesAndTorques

getPosition

getVelocity

getOrientation

getContactPointVel

getNumParticles

getPositions

getVelocities

getTriangles

getTetrahedra

getVisualPosition

getDistanceConstraintCount

getBendingConstraintCount

getMaterial

getCollisionBodyAt

getCollisionBodyCount

setPositionOffset

applyRigidTransform

pinVertex

unpinVertex

addDistanceConstraint

addDistanceConstraints

addInternalStruts

setGravity

Static member functions

loadObj static

createVolume static

Inherited members