Objects

Body types

RaiSim uses BodyType to describe whether a body or particle is integrated as a dynamic state, moved kinematically, or treated as static collision geometry. There are three available body types:

DYNAMIC: can have a velocity, has finite mass
KINEMATIC: can have a velocity, has infinite mass (e.g., conveyor belt)
STATIC: cannot have a velocity, has infinite mass (e.g., wall)

SingleBodyObject instances can be any of the three body types. ArticulatedSystem instances are dynamic, except fixed-base systems can report static base bodies. DeformableObject particles are dynamic unless they are pinned, in which case the pinned particle reports STATIC. GranularSystem particles are dynamic unless they are marked fixed, in which case the fixed particle reports STATIC.

Every object provides getBodyType() and getBodyType(localIdx). For multi-body or multi-particle objects, pass the local body or particle index to getBodyType(localIdx) to query a specific element. SingleBodyObject additionally provides setBodyType(BodyType type).

Object Identity And Indices

Every object has both a world index and a stable id:

getIndexInWorld() is the object’s current position in the world’s object list (World::getObjList(), World::getObject(index)). It is useful for iterating the current world state, but it can change when an object is removed: the last object in the list moves into the removed object’s index.
getId() is assigned by World and remains stable for the lifetime of the object. Use it for runtime scene editing, visualizer bookkeeping, or application-side maps that must survive object removal.

Local indices are separate from both of these. A SingleBodyObject has local index 0. ArticulatedSystem local indices refer to links. DeformableObject and GranularSystem local indices refer to particles.

Name

All objects can be named. These names are used by visualizers. raisim::World::getObject(name) retrieves an object by name and returns nullptr if no object has that name. Here is an example.

auto sphere = world.addSphere(1,1);
sphere->setName("sphere");
std::string name = sphere->getName();
auto same_sphere = world.getObject("sphere");

Types

The common base class is raisim::Object. Concrete object families include:

ArticulatedSystem: URDF/MJCF-style multi-body robots and mechanisms (Articulated Systems).
SingleBodyObject: primitive, compound, and mesh rigid bodies with one body index (Single-Body Objects). The static Ground and HeightMap terrain objects are single-body objects as well (Height Map).
DeformableObject: XPBD/PBD cloth, shell, and coarse soft-body objects (Deformable Objects).
GranularSystem: many spherical grains stored and stepped as one object (Granular Media).

Contacts And External Forces

getContacts() returns the contacts accumulated on an object during the last world step. For rigid SingleBodyObject instances and articulated systems, contact point ids stored in the solver correspond to entries in this contact list. For particle-like objects such as DeformableObject and GranularSystem, solver contact point ids identify particles instead. Do not assume a solver point id can always be used as an index into getContacts().

getContactPointVel(pointId, vel) returns the contact-point velocity that the contact solver works with (the velocity being solved for, not the state before the step). Pass the solver point id described above. For single bodies, articulated systems, and deformable objects, the velocity is expressed in the contact frame, whose z axis is the contact normal; for a granular system it is the particle’s linear velocity in the world frame. For world-frame body velocities, use getVelocity(localIdx, vel_w) or getVelocity(localIdx, pos_b, vel_w). For particle-like objects, local body and force APIs use particle indices.

External forces and torques use local body or particle indices. Forces and torques are expressed in the world frame and act during the next world step:

object->setExternalForce(localIdx, {0.0, 0.0, 5.0});   // at the center of mass
object->setExternalTorque(localIdx, {0.0, 0.0, 0.2});
object->clearExternalForcesAndTorques();

For rigid bodies and articulated links, setExternalForce(localIdx, pos, force) applies a world-frame force at a position expressed in the body frame. For particle-like objects such as deformables and granular systems, use the particle index as localIdx.

Threaded Visualization

Object exposes lockMutex/unlockMutex and lock/unlock for applications that update object state while a visualizer or another thread is reading it. Prefer std::scoped_lock in user code so exceptions or early returns do not leave the object locked:

std::scoped_lock guard(*object);
object->setName("updated_name");

API

class Object

Abstract base class of everything that can be added to a raisim::World: single bodies, terrains, articulated systems, deformable objects and granular systems. Objects are created and owned by the World. Functions taking a localIdx address a body (articulated systems) or a particle (deformable/granular); single bodies ignore it (use 0).

Subclassed by raisim::ArticulatedSystem, raisim::DeformableObject, raisim::GranularSystem, raisim::SingleBodyObject

Public Types

using Id = std::uint64_t: Stable object id type (see getId()).

Public Functions

explicit Object(): Objects are created through World (e.g., World::addSphere()).

void clearPerObjectContact(): Internal: clears the contact list (called by World before collision detection).

void addContactToPerObjectContact(Contact &contact)

Internal: appends a contact to the contact list.

Parameters:: contact – [in] the contact to copy

void setIndexInWorld(size_t indexInWorld_)

Internal: set by World when the object list changes.

Parameters:: indexInWorld_ – [in] the new index in World::getObjList()

size_t getIndexInWorld() const

get the world index. raisim::World::getObjects() returns a vector of object pointers. This is method returns the index of this object in the vector.

Returns:: the world index

inline Id getId() const

Returns a stable object id assigned by the world. Unlike getIndexInWorld(), this id is not changed when world indices are compacted after removals.

Returns:: the object id

const std::vector<Contact> &getContacts() const

get a vector of all contacts on the object.

Returns:: contacts on the body

std::vector<Contact> &getContacts()

Returns:: mutable contacts on the body (see the const overload).

virtual void updateCollision() = 0: Internal: synchronizes the collision geometry with the current pose.

virtual void updateContactAabbs() = 0: Internal: recomputes the world-frame AABBs used by the broadphase.

virtual void preContactSolverUpdate1(const Vec<3> &gravity, double dt) = 0

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

Parameters:

gravity – [in] gravitational acceleration (m/s^2)
dt – [in] time step (s)

virtual void preContactSolverUpdate2(const Vec<3> &gravity, double dt, contact::ContactProblems &problems) = 0

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

Parameters:

gravity – [in] gravitational acceleration (m/s^2)
dt – [in] time step (s)
problems – [inout] contact problems of the world

virtual void integrate(double dt, class World &world) = 0

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

Parameters:

dt – [in] time step (s)
world – [in] the owning world

virtual void setExternalForce(size_t localIdx, const Vec<3> &force) = 0

apply forces at the Center of Mass

Parameters:

localIdx – [in] local body index
force – [in] force in the world frame (N)

virtual void setExternalTorque(size_t localIdx, const Vec<3> &torque) = 0

apply torque on a body

Parameters:

localIdx – [in] local body index
torque – [in] torque in the world frame (Nm)

virtual void setExternalForce(size_t localIdx, const Vec<3> &pos, const Vec<3> &force) = 0

apply force (expressed in the world frame) at specific location of the body (expressed in the body frame)

Parameters:

localIdx – [in] local body index
pos – [in] application point in the body frame
force – [in] force in the world frame (N)

virtual void setConstraintForce(size_t localIdx, const Vec<3> &pos, const Vec<3> &force) = 0

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:

localIdx – [in] local body index
pos – [in] application point in the body frame
force – [in] force in the world frame (N)

virtual double getMass(size_t localIdx) const = 0

Parameters:: localIdx – [in] local body (or particle) index
Returns:: the mass of the local body (kg)

virtual ObjectType getObjectType() const = 0

get the object type. Possible types are SPHERE, BOX, CYLINDER, CONE, CAPSULE, MESH, HALFSPACE, COMPOUND, HEIGHTMAP, ARTICULATED_SYSTEM, DEFORMABLE, GRANULAR

Returns:: the object type

virtual void getPosition(size_t localIdx, Vec<3> &pos_w) const = 0

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

Parameters:

localIdx – [in] local body (or particle) index
pos_w – [out] position in the world frame (m)

virtual void getVelocity(size_t localIdx, Vec<3> &vel_w) const = 0

get the linear velocity of a local body or particle.

Parameters:

localIdx – [in] local body (or particle) index
vel_w – [out] linear velocity in the world frame (m/s)

virtual void getOrientation(size_t localIdx, Mat<3, 3> &rot) const = 0

get the orientation of a local body.

Parameters:

localIdx – [in] local body index
rot – [out] body-to-world rotation matrix

virtual void getPosition(size_t localIdx, const Vec<3> &pos_b, Vec<3> &pos_w) const = 0

get the world position of a point fixed to a local body.

Parameters:

localIdx – [in] local body index
pos_b – [in] the point in the body frame
pos_w – [out] the point in the world frame (m)

virtual void getVelocity(size_t localIdx, const Vec<3> &pos_b, Vec<3> &vel_w) const = 0

get the world velocity of a point fixed to a local body.

Parameters:

localIdx – [in] local body index
pos_b – [in] the point in the body frame
vel_w – [out] the point velocity in the world frame (m/s)

inline virtual BodyType getBodyType(size_t localIdx) const

get the body type of a local body. Available types are: DYNAMIC (movable and finite mass), STATIC (not movable and infinite mass), KINEMATIC (movable and infinite mass)

Parameters:: localIdx – [in] local body index (ignored by objects with a single body type)
Returns:: the body type

inline virtual BodyType getBodyType() const

get the object body type. Available types are: DYNAMIC (movable and finite mass), STATIC (not movable and infinite mass), KINEMATIC (movable and infinite mass).

Returns:: the body type

virtual void getContactPointVel(size_t pointId, Vec<3> &vel) const = 0

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:

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

inline const ::contact::AABB &getContactAabb(size_t idx) const

Internal: broadphase bounding box.

Parameters:: idx – [in] AABB index, less than getContactAabbCount()
Returns:: the world-frame AABB

inline size_t getContactAabbCount() const

Internal:

Returns:: the number of broadphase AABBs.

inline void setName(const std::string &name)

set the name of the object. You can retrieve an object by name using raisim::World::getObject()

Parameters:: name – [in] name of the object.

inline const std::string &getName() const

get the name of the object

Returns:: name of the object

inline std::uint64_t getRenderRevision() const

Revision for renderer-visible object state. It changes when user-visible pose/appearance state is modified or when physics integration moves the object.

Returns:: the render revision

inline const std::vector<Vec<3>> &getExternalForce() const

Returns:: External forces currently applied for visualization (world frame).

inline const std::vector<Vec<3>> &getExternalForcePosition() const

Returns:: Positions where external forces are applied (world frame).

inline const std::vector<Vec<3>> &getExternalTorque() const

Returns:: External torques currently applied for visualization (world frame).

inline const std::vector<Vec<3>> &getExternalTorquePosition() const

Returns:: Positions where external torques are applied (world frame).

virtual void clearExternalForcesAndTorques() = 0: Clears the recorded external forces/torques. The exact effect depends on the object type; World does not call it automatically.

inline void lockMutex(): locks the object mutex. This can be used if you use raisim in a multi-threaded environment.

inline void lock(): Same as lockMutex(); lets std::lock_guard / std::unique_lock be used with an object.

inline bool try_lock()

Try to lock the mutex without blocking.

Returns:: true if the lock was acquired.

inline void unlockMutex(): unlocks the object mutex. This can be used if you use raisim in a multi-threaded environment.

inline void unlock(): Same as unlockMutex().