raisim::World

class · #include <raisim/World.hpp>

The simulation world. It owns every object, wire and tendon added to it: the raw pointers returned by the add* methods stay valid until the object is removed (removeObject()) or the world is destroyed, and must not be deleted by the caller. Advance the simulation with integrate() (or integrate1() followed by integrate2()). A World is not thread-safe; see lockMutex() for sharing it with another thread (e.g. a visualizer server).

Nested classes

class Checkpoint — An immutable, reusable in-memory checkpoint of this world's runtime state.
struct CollisionCounters — Diagnostic collision counters of the last integration step.
struct DepthCameraFrame — Output of captureDepthCamera().
struct DepthCameraProperties — Settings of the CPU ray-cast depth camera used by captureDepthCamera().
struct ParameterContainer — A template parameter: every @@name token in the template text is replaced by param.
struct RayCastBody — Collision geometry of one body, exactly as rayTest() and rayTestLidar() test it.
struct SingleBodySnapshot — Snapshot of a single-body object's runtime state and collision properties.
struct SleepSettings — Sleeping-island configuration (see setSleepingParameters()).

Public types

ObjectId

cpp

using ObjectId = Object::Id

Stable runtime object id (Object::getId()). Ids are not reused within a World.

Constructors & destructor

World

cpp

explicit World(uint64_t headerLayoutStamp=detail::headerLayoutStamp())

Create an empty world. The defaulted parameter is an ABI guard: it is evaluated in the caller's translation unit from the headers the application compiled with, and the library compares it with its own value. A mismatch means the application was built against headers whose object layout differs from the loaded libraisim (e.g. stale object files after a reinstall) — a state that otherwise corrupts memory silently. Do not pass this argument manually.

Parameters

Parameter	Description
`headerLayoutStamp` (in)	ABI guard value; leave it defaulted

cpp

explicit World(
    const std::string &configFile,
    const std::vector<ParameterContainer> &params={})

Create a world from a file. The format is chosen from the extension and content: .usd/.usda/.usdc/.usdz (USD articulation, see addUsdArticulatedSystem()), .rscene (RaiSim Engine scene, see getRscene()), otherwise an XML file whose content contains a <mujoco> (MJCF) or <raisim> (RaiSim world config) element. A RaiSim world config can include one .rscene scene with <include value="scene.rscene"/>, e.g. to keep a robot separate from the scene it runs in.

Parameters

Parameter	Description
`configFile` (in)	path to the file
`params` (in)	template parameters substituted into a RaiSim XML config (`@@name` tokens). Ignored for other formats

cpp

World(const World &world) = delete

~World

cpp

~World()

Public member functions

exportToXml

cpp

void exportToXml(const std::string &dir, const std::string &fileName)

export the world to an xml config file, which can be loaded using a constructor

Parameters

Parameter	Description
`dir` (in)	directory to save the xml file
`fileName` (in)	file name

cpp

void exportToXml(const std::string &pathIn)

export the world to an xml config file, which can be loaded using a constructor

Parameters

Parameter	Description
`pathIn` (in)	path to save the xml file

exportMeshAssetsToObj

cpp

std::vector<std::string> exportMeshAssetsToObj(
    const std::string &directory,
    const std::string &prefix="mesh") const

Exports every Mesh object in the world as an OBJ file named "\<prefix\>_\<object name or index\>_\<mesh index\>.obj". The directory is created if needed.

Parameters

Parameter	Description
`directory` (in)	output directory
`prefix` (in)	file name prefix

Returns paths of the written files, in the world's object list order

setTimeStep

cpp

void setTimeStep(double dt)

set the time step. Fatal if dt is not finite and positive.

Parameters

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

getTimeStep

cpp

double getTimeStep() const

Returns the time step (s)

addSphere

cpp

Sphere *addSphere(
    double radius,
    double mass,
    const std::string &material="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Add a dynamic sphere centered at the origin. Set its pose with SingleBodyObject::setPosition() etc.

Parameters

Parameter	Description
`radius` (in)	radius (m)
`mass` (in)	mass (kg)
`material` (in)	material of the sphere (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask".

Returns pointer to the created sphere, owned by the world

addBox

cpp

Box *addBox(
    double xLength,
    double yLength,
    double zLength,
    double mass,
    const std::string &material="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Add a dynamic box centered at the origin.

Parameters

Parameter	Description
`xLength` (in)	full length along the body x axis (m)
`yLength` (in)	full length along the body y axis (m)
`zLength` (in)	full length along the body z axis (m)
`mass` (in)	mass (kg)
`material` (in)	material of the box (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask".

Returns pointer to the created box, owned by the world

addCylinder

cpp

Cylinder *addCylinder(
    double radius,
    double height,
    double mass,
    const std::string &material="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Add a dynamic cylinder centered at the origin, with its axis along the body z axis.

Parameters

Parameter	Description
`radius` (in)	radius (m)
`height` (in)	full height (m)
`mass` (in)	mass (kg)
`material` (in)	material of the cylinder (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask".

Returns pointer to the created cylinder, owned by the world

addCapsule

cpp

Capsule *addCapsule(
    double radius,
    double height,
    double mass,
    const std::string &material="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Add a dynamic capsule centered at the origin, with its axis along the body z axis.

Parameters

Parameter	Description
`radius` (in)	radius of the hemispheres and the cylinder (m)
`height` (in)	distance between the two hemisphere centers (m)
`mass` (in)	mass (kg)
`material` (in)	material of the capsule (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask".

Returns pointer to the created capsule, owned by the world

addGround

cpp

Ground *addGround(
    double zHeight=0.0,
    const std::string &material="default",
    CollisionGroup collisionMask=CollisionGroup(-1))

Add an infinite static ground plane (a half space below z = zHeight).

Parameters

Parameter	Description
`zHeight` (in)	height of the plane (m)
`material` (in)	material of the ground (which defines the contact dynamics)
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask". The collision group of the ground is always RAISIM_STATIC_COLLISION_GROUP

Returns pointer to the created ground, owned by the world

addHeightMap

cpp

HeightMap *addHeightMap(size_t xSamples, size_t ySamples, double xSize, double ySize, double centerX, double centerY, const std::vector<double> &height, const std::string &material="default", CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Create a heightmap, copying every height sample unchanged, including NaN and infinity. The sample count and geometry must be valid.

Parameters

Parameter	Description
`xSamples` (in)	how many points along x axis
`ySamples` (in)	how many points along y axis
`xSize` (in)	x width of the height map
`ySize` (in)	y length of the height map
`centerX` (in)	x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
`centerY` (in)	y coordinate of the grid center in the height map frame
`height` (in)	heights (m), which may be NaN or infinity to leave holes (see HeightMap). Its size must be xSamples * ySamples (fatal otherwise).
`material` (in)	material of the height map (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created height map, owned by the world

cpp

HeightMap *addHeightMap(const std::string &raisimHeightMapFileName, double centerX, double centerY, const std::string &material="default", CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Parameters

Parameter	Description
`raisimHeightMapFileName` (in)	the raisim text file which will be used to create the height map
`centerX` (in)	x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
`centerY` (in)	y coordinate of the grid center in the height map frame
`material` (in)	material of the height map (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created height map

cpp

HeightMap *addHeightMap(const std::string &pngFileName, double centerX, double centerY, double xSize, double ySize, double heightScale, double heightOffset, const std::string &material="default", CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Parameters

Parameter	Description
`pngFileName` (in)	the png file which will be used to create the height map
`centerX` (in)	x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
`centerY` (in)	y coordinate of the grid center in the height map frame
`xSize` (in)	x width of the height map
`ySize` (in)	y length of the height map
`heightScale` (in)	a png file (if 8-bit) has pixel values from 0 to 255. This parameter scales the pixel values to the actual height
`heightOffset` (in)	height of the 0-value pixel
`material` (in)	material of the height map (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created height map

cpp

HeightMap *addHeightMap(double centerX, double centerY, TerrainProperties &terrainProperties, const std::string &material="default", CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Parameters

Parameter	Description
`centerX` (in)	x coordinate of the grid center in the height map frame, which starts at the world origin (see HeightMap)
`centerY` (in)	y coordinate of the grid center in the height map frame
`terrainProperties` (in)	perlin noise parameters which will be used to create the height map
`material` (in)	material of the height map (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created height map

cpp

HeightMap *addHeightMap(const HeightMap *heightmapToBeCloned, CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Create a copy of another height map (samples, size, center, heights and material) with the same pose.

Parameters

Parameter	Description
`heightmapToBeCloned` (in)	Another height map to be cloned. Fatal if nullptr
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created height map

addDeformableTerrain

cpp

DeformableTerrain *addDeformableTerrain(size_t xSamples, size_t ySamples, double xSize, double ySize, double centerX, double centerY, const std::vector<double> &heights, const DeformableTerrain::Material &soil=DeformableTerrain::Material(), const std::string &material="default", CollisionGroup collisionGroup=(CollisionGroup(1)<<63), CollisionGroup collisionMask=CollisionGroup(-1))

Create a triangulated deformable soil surface. See DeformableTerrain for the material model, units and spatial accuracy. The world owns it; it is a HEIGHTMAP for rendering. Heights must be finite. The terrain is static in pose and deforms along its local Z axis.

addArticulatedSystem

cpp

ArticulatedSystem *addArticulatedSystem(
    const std::string &filePathOrURDFScript,
    const std::string &resPath="",
    const std::vector<std::string> &jointOrder={},
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    ArticulatedSystemOption options=ArticulatedSystemOption())

Parameters

Parameter	Description
`filePathOrURDFScript` (in)	Path to urdf file or a URDF string. Depending on the contents of the string, RaiSim will interpret it as an xml string or a file path.
`resPath` (in)	Path to the resource directory. Leave it empty ("") if it is the urdf file directory
`jointOrder` (in)	this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"
`options` (in)	Supports "doNotCollideWithParent" and "convexifyCollisionMeshes"

Returns pointer to the articulated system

cpp

ArticulatedSystem *addArticulatedSystem(
    const std::string &filePathOrURDFScript,
    const std::vector<std::string> &modules,
    const std::string &resPath="",
    const std::vector<std::string> &jointOrder={},
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    ArticulatedSystemOption options=ArticulatedSystemOption())

Parameters

Parameter	Description
`filePathOrURDFScript` (in)	Path to urdf file or a URDF string. Depending on the contents of the string, RaiSim will interpret it as an xml string or a file path.
`modules` (in)	Optional URDF modules to include (URDF fragments).
`resPath` (in)	Path to the resource directory. Leave it empty ("") if it is the urdf file directory
`jointOrder` (in)	this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"
`options` (in)	Supports "doNotCollideWithParent" and "convexifyCollisionMeshes"

Returns pointer to the articulated system

cpp

ArticulatedSystem *addArticulatedSystem(
    const std::string &xmlFileTemplate,
    const std::vector<ParameterContainer> &params,
    const std::string &resPath="",
    const std::vector<std::string> &jointOrder={},
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    ArticulatedSystemOption options=ArticulatedSystemOption())

Parameters

Parameter	Description
`xmlFileTemplate` (in)	xml template file.
`params` (in)	parameters for the xml file.
`resPath` (in)	Path to the resource directory. Leave it empty ("") if it is the urdf file directory
`jointOrder` (in)	this can be used to redefine the joint order. A child cannot precede its parent. Leave it empty ({}) to use the joint order defined in the URDF file.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"
`options` (in)	Supports "doNotCollideWithParent" and "convexifyCollisionMeshes"

Returns pointer to the articulated system

cpp

ArticulatedSystem *addArticulatedSystem(
    const Child &child,
    const std::string &resPath="",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    ArticulatedSystemOption options=ArticulatedSystemOption())

This method programmatically creates an articulated system without an URDF file.

Parameters

Parameter	Description
`child` (in)	an instance of Child class which has an articulated system structure.
`resPath` (in)	Path to the resource directory. Leave it empty ("") if it is the urdf file directory
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"
`options` (in)	Supports "doNotCollideWithParent" and "convexifyCollisionMeshes"

Returns pointer to the articulated system

addUsdArticulatedSystem

cpp

ArticulatedSystem *addUsdArticulatedSystem(
    const std::string &usdPath,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    ArticulatedSystemOption options=ArticulatedSystemOption())

Imports a USD Physics articulation scene.

Parameters

Parameter	Description
`usdPath` (in)	Path to a .usd/.usda/.usdc/.usdz file with a PhysicsArticulationRootAPI.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"
`options` (in)	Supports "doNotCollideWithParent" and "convexifyCollisionMeshes"

Returns pointer to the imported articulated system

addCompound

cpp

Compound *addCompound(
    const std::vector<Compound::CompoundObjectChild> &children,
    double mass,
    Vec<3> COM,
    const Mat<3, 3> &inertia,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Add a single body which is composed of multiple primitive collision shapes

Parameters

Parameter	Description
`children` (in)	a vector of CompoundObjectChild which contains each primitive shape's position, orientation, material and shape parameters
`mass` (in)	mass of the composite body
`COM` (in)	center of mass of the composite body, in the body frame
`inertia` (in)	inertia of the composite body about its center of mass, in the body frame
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created compound object

addMesh

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    const Mat<3, 3> &inertia,
    const Vec<3> &COM,
    double scale=1,
    const std::string &material="",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

create mesh collision body. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`inertia` (in)	inertia
`COM` (in)	the center of the mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created convexified mesh, or original mesh if CoACD fails

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    const Mat<3, 3> &inertia,
    const Vec<3> &COM,
    double scale,
    const std::string &material,
    MeshCollisionMode collisionMode,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    const CoacdOptions &coacdOptions=CoacdOptions())

create mesh collision body with an explicit mesh collision mode. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD. MeshCollisionMode::ORIGINAL_MESH keeps the non-convex triangle mesh. MeshCollisionMode::CONVEX_HULL creates one convex hull. MeshCollisionMode::CONVEXIFY creates a CoACD convex decomposition using coacdOptions; if the decomposition fails, it warns and uses one convex hull instead.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`inertia` (in)	inertia
`COM` (in)	the center of the mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`collisionMode` (in)	original mesh, convex hull, or convex decomposition
`coacdOptions` (in)	convex decomposition parameters. Used only with MeshCollisionMode::CONVEXIFY.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created mesh

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    const Mat<3, 3> &inertia,
    const Vec<3> &COM,
    double scale,
    const std::string &material,
    const CoacdOptions &coacdOptions,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

create mesh collision body approximated by CoACD convex decomposition.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`inertia` (in)	inertia
`COM` (in)	the center of the mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`coacdOptions` (in)	convex decomposition parameters
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created mesh

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    double scale=1,
    const std::string &material="",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

create mesh collision body. Any mesh format supported by Assimp can be used; USD files are loaded through OpenUSD. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created convexified mesh, or original mesh if CoACD fails

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    double scale,
    const std::string &material,
    MeshCollisionMode collisionMode,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1),
    const CoacdOptions &coacdOptions=CoacdOptions())

create mesh collision body with an explicit mesh collision mode. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box. MeshCollisionMode::ORIGINAL_MESH keeps the non-convex triangle mesh. MeshCollisionMode::CONVEX_HULL creates one convex hull. MeshCollisionMode::CONVEXIFY creates a CoACD convex decomposition using coacdOptions; if the decomposition fails, it warns and uses one convex hull instead.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`collisionMode` (in)	original mesh, convex hull, or convex decomposition
`coacdOptions` (in)	convex decomposition parameters. Used only with MeshCollisionMode::CONVEXIFY.
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created mesh

cpp

Mesh *addMesh(
    const std::string &meshFileInObjFormat,
    double mass,
    double scale,
    const std::string &material,
    const CoacdOptions &coacdOptions,
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

create mesh collision body approximated by CoACD convex decomposition. Inertia and COM are estimated by computing the axis-aligned bounding box of the (scaled) mesh and treating it as a uniform-density box.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	mesh file of the object
`mass` (in)	mass
`scale` (in)	rescale the mesh
`material` (in)	material of the mesh (which defines the contact dynamics)
`coacdOptions` (in)	convex decomposition parameters
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created mesh

cpp

Mesh *addMesh(
    const Mesh *meshToClone,
    const std::string &material="",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

create a mesh collision body that copies another mesh object

Parameters

Parameter	Description
`meshToClone` (in)	mesh to copy (file, mass, inertia, COM and scale are reused)
`material` (in)	material of the new mesh; empty uses the source mesh's material
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created mesh, owned by the world

addDeformableCloth

cpp

DeformableObject *addDeformableCloth(
    const std::vector<Vec<3>> &vertices,
    const std::vector<DeformableObject::Triangle> &triangles,
    const std::vector<unsigned int> &pinnedVertices={},
    const DeformableObject::Material &material=DeformableObject::Material(),
    const std::string &contactMaterial="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Create a deformable cloth/shell object from vertices and triangle indices. The first implementation uses XPBD/PBD distance constraints generated from triangle edges and one spherical collision proxy per vertex.

Parameters

Parameter	Description
`vertices` (in)	particle positions in world coordinates
`triangles` (in)	triangle vertex indices
`pinnedVertices` (in)	vertices held fixed in world coordinates
`material` (in)	deformable solver and material parameters
`contactMaterial` (in)	material used by collision proxies
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created deformable object

cpp

DeformableObject *addDeformableCloth(
    const std::string &meshFileInObjFormat,
    double scale=1.0,
    const std::vector<unsigned int> &pinnedVertices={},
    const DeformableObject::Material &material=DeformableObject::Material(),
    const std::string &contactMaterial="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Create a deformable cloth/shell object from an OBJ triangle mesh. Polygon faces are triangulated as a fan. Texture and normal indices are ignored.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	OBJ file path
`scale` (in)	vertex scale
`pinnedVertices` (in)	vertices held fixed in world coordinates
`material` (in)	deformable solver and material parameters
`contactMaterial` (in)	material used by collision proxies
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created deformable object

addDeformableVolume

cpp

DeformableObject *addDeformableVolume(
    const std::vector<Vec<3>> &vertices,
    const std::vector<DeformableObject::Tetrahedron> &tetrahedra,
    const std::vector<unsigned int> &pinnedVertices={},
    const DeformableObject::Material &material=DeformableObject::Material(),
    const std::string &contactMaterial="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Create a deformable solid from a tetrahedral mesh (see DeformableObject::createVolume()). With a positive DeformableObject::Material::youngsModulus it is an elastic solid.

Parameters

Parameter	Description
`vertices` (in)	particle positions in the world frame (m)
`tetrahedra` (in)	vertex indices of the tetrahedra
`pinnedVertices` (in)	vertices held fixed in world coordinates
`material` (in)	deformable solver and material parameters
`contactMaterial` (in)	material used by collision proxies
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created deformable object, owned by the world

addDeformableObject

cpp

DeformableObject *addDeformableObject(
    const std::string &meshFileInObjFormat,
    const DeformableObject::Material &material,
    const DeformableObject::MeshBuildOptions &options,
    const std::vector<unsigned int> &pinnedVertices={},
    const std::string &contactMaterial="default",
    CollisionGroup collisionGroup=1,
    CollisionGroup collisionMask=CollisionGroup(-1))

Create a deformable object from an OBJ mesh and particle generation options. Surface mode uses the mesh vertices as particles. Filled mode requires a closed triangle mesh and adds interior particles (an elastic solid of tetrahedra when the material has a Young's modulus). Internal struts can be generated automatically through DeformableObject::MeshBuildOptions.

Parameters

Parameter	Description
`meshFileInObjFormat` (in)	OBJ file path
`material` (in)	deformable solver and material parameters
`options` (in)	particle generation options
`pinnedVertices` (in)	vertices held fixed in world coordinates
`contactMaterial` (in)	material used by collision proxies
`collisionGroup` (in)	read "Contact and Collision/ Collision Group and Mask"
`collisionMask` (in)	read "Contact and Collision/ Collision Group and Mask"

Returns pointer to the created deformable object, owned by the world

addGranularParticles

cpp

GranularSystem *addGranularParticles(
    const std::vector<Vec<3>> &positions,
    const std::vector<double> &radii,
    const GranularSystem::Material &material=GranularSystem::Material())

Create a native granular particle system. Particles are stored and stepped as one object instead of thousands of independent Sphere objects. Particle-particle DEM contacts are handled internally; particles also collide with the world's spheres, boxes, capsules, cylinders, compounds, meshes, height maps and articulated systems, and optionally with a horizontal ground plane (GranularSystem::setGroundPlane(); the world's Ground object is not used) or a box container.

Parameters

Parameter	Description
`positions` (in)	initial particle positions in the world frame (m)
`radii` (in)	particle radii (m), one per position
`material` (in)	particle material parameters

Returns pointer to the created granular system, owned by the world

addGranularBox

cpp

GranularSystem *addGranularBox(
    const GranularSystem::BoxOptions &options,
    const GranularSystem::Material &material=GranularSystem::Material())

Create a granular system filled with equal particles on a regular grid inside an axis-aligned box (see GranularSystem::BoxOptions). Every particle gets the options' velocity, angular velocity, material id and fixed flag.

Parameters

Parameter	Description
`options` (in)	box extent, particle radius, grid spacing and initial particle state
`material` (in)	particle material parameters

Returns pointer to the created granular system, owned by the world

getObject

cpp

Object *getObject(const std::string &name)

Parameters

Parameter	Description
`name` (in)	object name, set by Object::setName()

Returns the first object with the given name, or nullptr if none exists

cpp

Object *getObject(std::size_t worldIndex)

World indices change when an object is removed (the last object takes the removed index); use getObjectById() for a stable handle.

Parameters

Parameter	Description
`worldIndex` (in)	index in [0, getObjectCount()). Not bounds-checked

Returns object with the given index. This index can be retrieved by Object::getIndexInWorld()

addStiffWire

cpp

StiffLengthConstraint *addStiffWire(
    Object *obj1,
    size_t localIdx1,
    Vec<3> pos1_b,
    Object *obj2,
    size_t localIdx2,
    Vec<3> pos2_b,
    double length)

Stiff unilateral constraint. It cannot push. It can only pull.

Parameters

Parameter	Description
`obj1` (in)	the first object the wire is attached to
`localIdx1` (in)	the body index (0 for a SingleBodyObject) for the first object
`pos1_b` (in)	location of the cable attachment on the first object
`obj2` (in)	the second object the wire is attached to
`localIdx2` (in)	the body index (0 for a SingleBodyObject) for the second object
`pos2_b` (in)	location of the cable attachment on the second object
`length` (in)	length of the wire

Returns pointer to the created wire

addCompliantWire

cpp

CompliantLengthConstraint *addCompliantWire(
    Object *obj1,
    int localIdx1,
    Vec<3> pos1_b,
    Object *obj2,
    int localIdx2,
    Vec<3> pos2_b,
    double length,
    double stiffness)

soft unilateral constraint. It cannot push. It can only pull.

Parameters

Parameter	Description
`obj1` (in)	the first object the wire is attached to
`localIdx1` (in)	the body index (0 for a SingleBodyObject) for the first object
`pos1_b` (in)	location of the cable attachment on the first object
`obj2` (in)	the second object the wire is attached to
`localIdx2` (in)	the body index (0 for a SingleBodyObject) for the second object
`pos2_b` (in)	location of the cable attachment on the second object
`length` (in)	length of the wire
`stiffness` (in)	stiffness of the wire

Returns pointer to the created wire

addCustomWire

cpp

CustomLengthConstraint *addCustomWire(
    Object *obj1,
    int localIdx1,
    Vec<3> pos1_b,
    Object *obj2,
    int localIdx2,
    Vec<3> pos2_b,
    double length)

Custom wire that applies user-set tension between two points.

Parameters

Parameter	Description
`obj1` (in)	the first object the wire is attached to
`localIdx1` (in)	the body index (0 for a SingleBodyObject) for the first object
`pos1_b` (in)	location of the cable attachment on the first object
`obj2` (in)	the second object the wire is attached to
`localIdx2` (in)	the body index (0 for a SingleBodyObject) for the second object
`pos2_b` (in)	location of the cable attachment on the second object
`length` (in)	length of the wire. You can use this to compute how much it stretched from a nominal length. It might not be necessary for some wire types.

Returns pointer to the created wire

addSpatialTendon

cpp

Tendon *addSpatialTendon(
    const std::string &name,
    const std::vector<Tendon::PathElement> &path,
    const Tendon::Properties &properties=Tendon::Properties())

Adds a spatial tendon: a massless cable routed through sites and wrapped around sphere or cylinder obstacles, optionally split into pulley branches. Spatial branches start/end at sites; consecutive obstacles require a via site.

Parameters

Parameter	Description
`name` (in)	unique tendon name. Used by getTendon() and in exported XML
`path` (in)	ordered route elements (see Tendon::PathElement)
`properties` (in)	spring, limit, friction, armature and visualization settings

Returns pointer to the created tendon. The world owns it

addFixedTendon

cpp

Tendon *addFixedTendon(
    const std::string &name,
    const std::vector<Tendon::JointTerm> &joints,
    const Tendon::Properties &properties=Tendon::Properties())

Adds a fixed tendon whose length is a weighted sum of scalar joint coordinates.

Parameters

Parameter	Description
`name` (in)	unique tendon name
`joints` (in)	joint terms (articulated system, joint name, coefficient)
`properties` (in)	spring, limit, friction, armature and visualization settings

Returns pointer to the created tendon. The world owns it

addTendonCoupling

cpp

TendonCoupling *addTendonCoupling(
    const std::string &name,
    Tendon *first,
    Tendon *second=nullptr,
    const TendonCoupling::Properties &properties=TendonCoupling::Properties())

Couples the lengths of two tendons through a polynomial relation (see TendonCoupling::Properties).

Parameters

Parameter	Description
`name` (in)	unique coupling name
`first` (in)	the tendon whose length is constrained
`second` (in)	the driving tendon. nullptr fixes the first tendon's length
`properties` (in)	polynomial coefficients, compliance and error correction

Returns pointer to the created coupling. The world owns it

getTendon

cpp

Tendon *getTendon(const std::string &name) const

Parameters

Parameter	Description
`name` (in)	tendon name

Returns the tendon with the given name, or nullptr if none exists

getTendons

cpp

const std::vector<std::unique_ptr<Tendon>> &getTendons() const

Returns all tendons in the world, in creation order

onGranularParticleRemoved

cpp

void onGranularParticleRemoved(
    GranularSystem *grains,
    size_t removedIndex,
    size_t lastIndex)

Internal: keep tendon attachments valid when granular storage swaps a particle.

Parameters

Parameter	Description
`grains` (in)	the granular system
`removedIndex` (in)	removed particle
`lastIndex` (in)	particle moved into removedIndex

onGranularParticlesReplacing

cpp

bool onGranularParticlesReplacing(const GranularSystem *grains) const

Internal: called before granular storage replaces all its particles (loadGranularState()).

Parameters

Parameter	Description
`grains` (in)	the granular system

Returns true if a tendon is attached to grains; onGranularParticlesReplaced() then follows

Exceptions

Exception	Description
`std::logic_error`	during a split integration step if a tendon is attached to grains

onGranularParticlesReplaced

cpp

void onGranularParticlesReplaced(
    GranularSystem *grains,
    const std::vector<uint64_t> &previousStableIds)

Internal: keep tendon attachments on the same particles, by stable id, after granular storage replaced its particles; a tendon attached to a particle no longer there is removed.

Parameters

Parameter	Description
`grains` (in)	the granular system
`previousStableIds` (in)	stable ids before the replacement

getTendonCouplings

cpp

const std::vector<std::unique_ptr<TendonCoupling>> &getTendonCouplings() const

Returns all tendon couplings in the world, in creation order

removeTendon

cpp

void removeTendon(Tendon *tendon)

removes a tendon, every coupling that references it, and any legacy wire adapter bound to it

Parameters

Parameter	Description
`tendon` (in)	the tendon to be removed

removeTendonCoupling

cpp

void removeTendonCoupling(TendonCoupling *coupling)

removes a tendon coupling

Parameters

Parameter	Description
`coupling` (in)	the coupling to be removed

getConstraint

cpp

Constraints *getConstraint(const std::string &name)

Parameters

Parameter	Description
`name` (in)	wire name, set by LengthConstraint::setName()

Returns a constraint (e.g., wires) with the given name. returns nullptr if it doesn't exist. This is equivalent to getWire(const std::string&)

getWire

cpp

LengthConstraint *getWire(const std::string &name)

Parameters

Parameter	Description
`name` (in)	wire name, set by LengthConstraint::setName()

Returns a wire with the given name. returns nullptr if it doesn't exist

getWires

cpp

std::vector<std::unique_ptr<LengthConstraint>> &getWires()

Returns the legacy wire adapters (stiff, compliant and custom wires). Their physics runs on tendons

removeObject

cpp

void removeObject(LengthConstraint *wire)

removes a wire (i.e., LengthConstraint) and the tendon that implements it

Parameters

Parameter	Description
`wire` (in)	the wire to be removed

cpp

void removeObject(Object *obj)

removes and deletes an object. Wires attached to it and tendon references to it are removed as well. The last object in the world list takes the removed object's world index. The contacts of the last step (Object::getContacts() and getContactProblem()) are cleared; the next step finds them again. Prints a message and does nothing else if the object is not in this world.

Parameters

Parameter	Description
`obj` (in)	object to be removed. The pointer is invalid afterwards

Exceptions

Exception	Description
`std::logic_error`	between integrate1() and integrate2(), which works on the contacts and constraint rows integrate1() made for every object

getObjectCount

cpp

std::size_t getObjectCount() const

Returns the number of objects in the world

getObjectById

cpp

Object *getObjectById(ObjectId id)

Parameters

Parameter	Description
`id` (in)	stable runtime id (Object::getId())

Returns object with the stable runtime id, or nullptr if the object no longer exists.

cpp

const Object *getObjectById(ObjectId id) const

Parameters

Parameter	Description
`id` (in)	stable runtime id (Object::getId())

Returns object with the stable runtime id, or nullptr if the object no longer exists.

isObjectAlive

cpp

bool isObjectAlive(ObjectId id) const

Parameters

Parameter	Description
`id` (in)	stable runtime id (Object::getId())

Returns true if an object with the stable runtime id currently exists in the world.

getObjList

cpp

std::vector<Object *> &getObjList()

Returns returns a non-const vector of the objects

getConfigurationNumber

cpp

unsigned long getConfigurationNumber()

Returns the configuration number. this number is updated every time an object is added or removed

getLifetimeIdentity

cpp

const std::shared_ptr<const int> &getLifetimeIdentity() const

Stable identity for this World's lifetime, independent of address reuse. Keeping the identity alive does not keep the World or its objects alive.

getLastCollisionCounters

cpp

const CollisionCounters &getLastCollisionCounters() const

Returns the collision counters of the last step. Only updated while counters are enabled

setCollisionCountersEnabled

cpp

void setCollisionCountersEnabled(bool enabled)

Enable or disable collection of CollisionCounters (disabled by default).

Parameters

Parameter	Description
`enabled` (in)	true to collect counters

getCollisionCountersEnabled

cpp

bool getCollisionCountersEnabled() const

Returns true if CollisionCounters are being collected

captureCheckpoint

cpp

Checkpoint captureCheckpoint() const

Capture between complete integration steps. Includes controls, pending forces, sensors, sleeping islands and solver history. Object/constraint/sensor topology must remain unchanged until restore. Checkpoints belong to this World instance; they are not portable files. Throws std::logic_error during a split step (between integrate1() and integrate2()).

Returns the captured checkpoint

restoreCheckpoint

cpp

bool restoreCheckpoint(
    const Checkpoint &checkpoint,
    std::string *error=nullptr)

Restore a checkpoint for rewind/resume. Rejected checkpoints leave the world unchanged and return an explanation in error. External controllers, renderer state and application-owned random generators are outside the World. Rejected when called during a split step, for an empty checkpoint, a checkpoint of another World, or after the object/constraint/sensor/collision topology changed.

Parameters

Parameter	Description
`checkpoint` (in)	checkpoint captured from this World
`error` (out)	if not nullptr, receives the reason of a rejection

Returns true if the checkpoint was restored

setObjectCollisionFilter

cpp

bool setObjectCollisionFilter(
    Object *object,
    CollisionGroup collisionGroup,
    CollisionGroup collisionMask,
    size_t localIdx=size_t(-1))

Updates collision group and mask for all collision bodies on an object, or for a specific local body. Call this between simulation steps.

Parameters

Parameter	Description
`object` (in)	object in this world
`collisionGroup` (in)	new collision group
`collisionMask` (in)	new collision mask
`localIdx` (in)	local body index, or size_t(-1) for all bodies of the object

Returns false if the object is not in this world or no collision body matched

setObjectMaterial

cpp

bool setObjectMaterial(
    Object *object,
    const std::string &material,
    size_t localIdx=size_t(-1))

Updates the collision material for all collision bodies on an object, or for a specific local body. Call this between simulation steps.

Parameters

Parameter	Description
`object` (in)	object in this world
`material` (in)	new material name
`localIdx` (in)	local body index, or size_t(-1) for all bodies of the object

Returns false if the object is not in this world or no collision body matched

captureSingleBodySnapshot

cpp

bool captureSingleBodySnapshot(
    const SingleBodyObject *object,
    SingleBodySnapshot &snapshot) const

Captures a single-body runtime state snapshot.

Parameters

Parameter	Description
`object` (in)	object in this world
`snapshot` (out)	receives the state

Returns false (snapshot untouched) if the object is not in this world

restoreSingleBodySnapshot

cpp

bool restoreSingleBodySnapshot(
    SingleBodyObject *object,
    const SingleBodySnapshot &snapshot,
    bool restoreCollisionProperties=true)

Restores a single-body runtime state snapshot. If restoreCollisionProperties is true, collision group, mask, and material are restored as well.

Parameters

Parameter	Description
`object` (in)	object in this world, of the same ObjectType as the snapshot
`snapshot` (in)	state to restore
`restoreCollisionProperties` (in)	also restore material, collision group and mask

Returns false if the object is not in this world or its type differs from the snapshot

cpp

bool restoreSingleBodySnapshot(
    ObjectId id,
    const SingleBodySnapshot &snapshot,
    bool restoreCollisionProperties=true)

Restores a single-body runtime state snapshot by stable object id.

Parameters

Parameter	Description
`id` (in)	stable object id
`snapshot` (in)	state to restore
`restoreCollisionProperties` (in)	also restore material, collision group and mask

Returns false if no single-body object with the id exists or its type differs from the snapshot

cloneSingleBodyObject

cpp

SingleBodyObject *cloneSingleBodyObject(
    const SingleBodyObject *source,
    const std::string &name="")

Clones primitive single-body objects with pose, velocity, mass, body type, material, collision filter, and appearance. Supported types are sphere, box, cylinder and capsule.

Parameters

Parameter	Description
`source` (in)	object in this world
`name` (in)	name of the clone; empty keeps the default name

Returns the new object (owned by the world), or nullptr for unsupported types or an object not in this world

rayTest

cpp

const RayCollisionList &rayTest(
    const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &start,
    const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &direction,
    double length,
    size_t objectId=size_t(-10),
    size_t localId=size_t(-10),
    CollisionGroup collisionMask=CollisionGroup(-1))

Casts a ray and returns the closest hit. The returned list holds zero or one item, and it is overwritten by the next ray test.

Parameters

Parameter	Description
`start` (in)	The start position of the ray in the world frame (m).
`direction` (in)	The direction of the ray in the world frame. It is normalized internally; a zero vector is treated as +z.
`length` (in)	The length of the ray (m). A non-positive length returns no hit.
`objectId` (in)	Collision with the body whose object world index (Object::getIndexInWorld()) and local body index match objectId and localId is ignored. Both must be set (not size_t(-10)) for this to take effect. This can be useful if the sensor is attached to a robot.
`localId` (in)	Local body index of the ignored body. See objectId.
`collisionMask` (in)	Collision mask to filter collisions. By default, it records collisions with all collision groups.

Returns A reference to the world's internal hit list.

cpp

const RayCollisionList &rayTest(
    std::initializer_list<double> start,
    std::initializer_list<double> direction,
    double length,
    size_t objectId=size_t(-10),
    size_t localId=size_t(-10),
    CollisionGroup collisionMask=CollisionGroup(-1))

Same as the Eigen overload, with start and direction given as {x, y, z}. Fatal if a list does not have 3 elements.

Parameters

Parameter	Description
`start` (in)	ray start in the world frame (m)
`direction` (in)	ray direction in the world frame
`length` (in)	ray length (m)
`objectId` (in)	world index of the object whose body is ignored (see the Eigen overload)
`localId` (in)	local index of the ignored body
`collisionMask` (in)	collision mask to filter hits

Returns the world's internal hit list (zero or one item)

cpp

const RayCollisionList &rayTest(
    std::initializer_list<double> start,
    const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &direction,
    double length,
    size_t objectId=size_t(-10),
    size_t localId=size_t(-10),
    CollisionGroup collisionMask=CollisionGroup(-1))

Same as the Eigen overload, with start given as {x, y, z}. Fatal if start does not have 3 elements.

Parameters

Parameter	Description
`start` (in)	ray start in the world frame (m)
`direction` (in)	ray direction in the world frame
`length` (in)	ray length (m)
`objectId` (in)	world index of the object whose body is ignored (see the Eigen overload)
`localId` (in)	local index of the ignored body
`collisionMask` (in)	collision mask to filter hits

Returns the world's internal hit list (zero or one item)

cpp

const RayCollisionList &rayTest(
    const Eigen::Ref<const Eigen::Vector3d, Eigen::Unaligned> &start,
    std::initializer_list<double> direction,
    double length,
    size_t objectId=size_t(-10),
    size_t localId=size_t(-10),
    CollisionGroup collisionMask=CollisionGroup(-1))

Same as the Eigen overload, with direction given as {x, y, z}. Fatal if direction does not have 3 elements.

Parameters

Parameter	Description
`start` (in)	ray start in the world frame (m)
`direction` (in)	ray direction in the world frame
`length` (in)	ray length (m)
`objectId` (in)	world index of the object whose body is ignored (see the Eigen overload)
`localId` (in)	local index of the ignored body
`collisionMask` (in)	collision mask to filter hits

Returns the world's internal hit list (zero or one item)

rayTestLidar

cpp

void rayTestLidar(
    const Mat<3, 3> &rot,
    const Vec<3> &pos,
    double yawStartAngle,
    double yawIncrement,
    size_t yawCount,
    double pitchStartAngle,
    double pitchIncrement,
    size_t pitchCount,
    double rangeMin,
    double rangeMax,
    size_t objectId,
    size_t localId,
    CollisionGroup collisionMask,
    std::vector<Vec<3>, AlignedAllocator<Vec<3>, 32>> &scan)

Ray-cast helper for spinning lidar scans. Applies a frustum-based broadphase before running per-ray collision tests.

Parameters

Parameter	Description
`rot` (in)	Sensor orientation (sensor frame to world frame).
`pos` (in)	Sensor position in world frame.
`yawStartAngle` (in)	First yaw angle in radians.
`yawIncrement` (in)	Signed yaw increment in radians.
`yawCount` (in)	Number of yaw samples.
`pitchStartAngle` (in)	First pitch angle in radians.
`pitchIncrement` (in)	Pitch increment in radians.
`pitchCount` (in)	Number of pitch samples.
`rangeMin` (in)	Minimum range in meters.
`rangeMax` (in)	Maximum range in meters.
`objectId` (in)	Object id to ignore (sensor owner).
`localId` (in)	Local body id to ignore (sensor owner).
`collisionMask` (in)	Collision mask to filter collisions.
`scan` (out)	Output scan points in the sensor frame.

getRayCastBodies

cpp

void getRayCastBodies(std::vector<RayCastBody> &bodies)

Collects the collision bodies that ray tests see, with their current world poses. A ray test with collision mask m skips a body when (body.collisionGroup & m) == 0 or body.collisionMask == 0. The referenced mesh and heightmap data stay valid until the owning object is removed or changed.

Parameters

Parameter	Description
`bodies` (out)	cleared, then filled with one entry per collision body

captureDepthCamera

cpp

void captureDepthCamera(
    const Vec<3> &pos,
    const Mat<3, 3> &rot,
    const DepthCameraProperties &properties,
    DepthCameraFrame &frame,
    size_t objectId=size_t(-10),
    size_t localId=size_t(-10),
    CollisionGroup collisionMask=CollisionGroup(-1))

Captures a deterministic CPU ray-based depth camera frame. The camera uses the same convention as RaiSim depth sensors: +X is forward, +Y is left, and +Z is up in the camera frame. Depth is the distance along the camera forward axis, segmentation is the hit object's world index, and -1 denotes background. Each pixel is one rayTest() call, so this is costly for large images. Fatal if the properties are invalid (see DepthCameraProperties).

Parameters

Parameter	Description
`pos` (in)	camera position in the world frame (m)
`rot` (in)	camera orientation (camera frame to world frame)
`properties` (in)	image size, clipping, field of view, outputs and noise
`frame` (out)	receives the captured buffers
`objectId` (in)	world index of an object body to ignore (see rayTest())
`localId` (in)	local index of the body to ignore (see rayTest())
`collisionMask` (in)	collision mask to filter hits

integrate

cpp

void integrate()

integrate the world It is equivalent to "integrate1(); integrate2();"

integrate1

cpp

void integrate1()

It performs 1) deletion contacts from previous time step 2) collision detection 3) register contacts to each body 4) calls "preContactSolverUpdate1()" of each object

integrate2

cpp

void integrate2()

It performs 1) calls "preContactSolverUpdate2()" of each body 2) run collision solver 3) calls "integrate" method of each object

integrateNoContactDetection

cpp

void integrateNoContactDetection()

It performs 1) deletion contacts from previous time step 2) updates collision objects 3) calls "preContactSolverUpdate1()" of each object It skips contact detection and contact problem construction.

getContactProblem

cpp

const contact::ContactProblems *getContactProblem() const

Returns the contact problems (one per contact) built in the last integrate1() call. Owned by the world and overwritten in the next step

setGravity

cpp

void setGravity(const Vec<3> &gravity)

Set gravity

Parameters

Parameter	Description
`gravity` (in)	gravitational acceleration of the world in the world frame (m/s^2)

updateMaterialProp

cpp

void updateMaterialProp(const MaterialManager &prop)

this deletes the existing material props and replace them with the argument

Parameters

Parameter	Description
`prop` (in)	new material prop

setMaterialPairProp

cpp

void setMaterialPairProp(
    const std::string &mat1,
    const std::string &mat2,
    double friction,
    double restitution,
    double resThreshold)

Add a new material pair property. In RaiSim, material property is defined by the pair. The static friction coefficient is set to friction and the static friction velocity threshold to 1e-3 m/s.

Parameters

Parameter	Description
`mat1` (in)	name of the first material (the order of mat1 and mat2 is not important)
`mat2` (in)	name of the second material
`friction` (in)	the coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce

cpp

void setMaterialPairProp(
    const std::string &mat1,
    const std::string &mat2,
    double friction,
    double restitution,
    double resThreshold,
    double staticFriction,
    double staticFrictionThresholdVelocity)

Add a new material pair property. In RaiSim, material property is defined by the pair.

Parameters

Parameter	Description
`mat1` (in)	name of the first material (the order of mat1 and mat2 is not important)
`mat2` (in)	name of the second material
`friction` (in)	the dynamic coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce
`staticFriction` (in)	the static coefficient of friction
`staticFrictionThresholdVelocity` (in)	if the relative velocity of two points is bigger than this value, then the dynamic coefficient of friction is applied. Otherwise, the coefficient of friction is interpolated between the static and dynamic one proportional to the relative velocity.

cpp

void setMaterialPairProp(
    const std::string &mat1,
    const std::string &mat2,
    double friction,
    double restitution,
    double resThreshold,
    double staticFriction,
    double staticFrictionThresholdVelocity,
    double rollingFriction,
    double spinningFriction)

Add a material pair property with rolling and spinning friction. The rolling and spinning coefficients are zero by default in existing overloads, which keeps the standard contact solver path unchanged.

Parameters

Parameter	Description
`mat1` (in)	name of the first material (the order of mat1 and mat2 is not important)
`mat2` (in)	name of the second material
`friction` (in)	the dynamic coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce
`staticFriction` (in)	the static coefficient of friction
`staticFrictionThresholdVelocity` (in)	static-to-dynamic friction transition speed (m/s), see the overload above
`rollingFriction` (in)	the coefficient of rolling friction
`spinningFriction` (in)	the coefficient of spinning friction

setDefaultMaterial

cpp

void setDefaultMaterial(
    double friction,
    double restitution,
    double resThreshold)

this default material property is used if a material pair property is not defined for the specific collision. The static friction coefficient is set to friction and the static friction velocity threshold to 1e-3 m/s.

Parameters

Parameter	Description
`friction` (in)	the coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce

cpp

void setDefaultMaterial(
    double friction,
    double restitution,
    double resThreshold,
    double staticFriction,
    double staticFrictionThresholdVelocity)

this default material property is used if a material pair property is not defined for the specific collision

Parameters

Parameter	Description
`friction` (in)	the coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce
`staticFriction` (in)	the static coefficient of friction
`staticFrictionThresholdVelocity` (in)	if the relative velocity of two points is bigger than this value, then the dynamic coefficient of friction is applied. Otherwise, the coefficient of friction is interpolated between the static and dynamic one proportional to the relative velocity.

cpp

void setDefaultMaterial(
    double friction,
    double restitution,
    double resThreshold,
    double staticFriction,
    double staticFrictionThresholdVelocity,
    double rollingFriction,
    double spinningFriction)

Same as above, with rolling and spinning friction for the default material.

Parameters

Parameter	Description
`friction` (in)	the coefficient of friction
`restitution` (in)	the coefficient of restitution
`resThreshold` (in)	the minimum impact velocity (m/s) to make the object bounce
`staticFriction` (in)	the static coefficient of friction
`staticFrictionThresholdVelocity` (in)	static-to-dynamic friction transition speed (m/s)
`rollingFriction` (in)	the coefficient of rolling friction
`spinningFriction` (in)	the coefficient of spinning friction

getGravity

cpp

const Vec<3> &getGravity() const

Returns gravitational acceleration of the world in the world frame (m/s^2)

setERP

cpp

void setERP(double erp, double erp2=0)

Changes the Error Reduction Parameter. It often has very minimalistic impact on simulation

Parameters

Parameter	Description
`erp` (in)	spring constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning
`erp2` (in)	damping constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning

setContactSolverParam

cpp

void setContactSolverParam(
    double alpha_init,
    double alpha_min,
    double alpha_decay,
    int maxIter,
    double threshold)

Changes the contact solver parameter. For details, please check "Hwangbo, Jemin, Joonho Lee, and Marco Hutter. "Per-contact iteration method for solving contact dynamics." IEEE Robotics and Automation Letters 3.2 (2018): 895-902." We found that the three default alpha values are always the best. So they are hardcoded now. So only the maxIter and threshold will affect the simulation. The three input alpha values will be ignored

Parameters

Parameter	Description
`alpha_init` (in)	NOT_USED_ANYMORE (default: 1.0) how aggressive the solver is initially
`alpha_min` (in)	NOT_USED_ANYMORE (default: 1.0) how aggressive the solver is after an infinite number of solver iterations
`alpha_decay` (in)	NOT_USED_ANYMORE (default: 1.0) how fast alpha converges from alpha_init to alpha_min
`threshold` (in)	(default: 1e-8) error threshold for termination
`maxIter` (in)	(default: 150) the maximum number of iterations allowed

setContactSettings

cpp

void setContactSettings(const ::contact::ContactSettings &settings)

Configure contact detection (broadphase/narrowphase) settings. Call this when the world is not stepping.

Parameters

Parameter	Description
`settings` (in)	Contact detector settings.

setSleepingEnabled

cpp

void setSleepingEnabled(bool enabled)

Enable or disable sleeping islands. Disabling wakes every sleeping object.

Parameters

Parameter	Description
`enabled` (in)	true to enable

isSleepingEnabled

cpp

bool isSleepingEnabled() const

Returns true if sleeping islands are enabled.

setSleepingParameters

cpp

void setSleepingParameters(
    double linearVelThreshold,
    double angularVelThreshold,
    int quietSteps)

Configure sleeping thresholds. Both speed thresholds must be satisfied for quietSteps consecutive steps. Motion above either threshold or a user modification resets the counter. The quiet duration is quietSteps times the simulation time step.

Parameters

Parameter	Description
`linearVelThreshold` (in)	linear speed threshold (m/s); negative values are clamped to 0
`angularVelThreshold` (in)	angular speed threshold (rad/s); negative values are clamped to 0
`quietSteps` (in)	required consecutive quiet steps; values below 1 are clamped to 1

getSleepingParameters

cpp

const SleepSettings &getSleepingParameters() const

Returns the current sleeping configuration.

setSleepingVelocityThresholds

cpp

void setSleepingVelocityThresholds(
    double linearVelThreshold,
    double angularVelThreshold)

Update only the sleeping velocity thresholds.

Parameters

Parameter	Description
`linearVelThreshold` (in)	linear speed threshold (m/s); negative values are clamped to 0
`angularVelThreshold` (in)	angular speed threshold (rad/s); negative values are clamped to 0

wakeObject

cpp

void wakeObject(Object *object)

Wake a specific object (and its island) on the next step.

Parameters

Parameter	Description
`object` (in)	object in this world

wakeAll

cpp

void wakeAll()

Wake all objects.

isObjectSleeping

cpp

bool isObjectSleeping(const Object *object) const

Parameters

Parameter	Description
`object` (in)	object in this world

Returns true if the object is currently sleeping. Always false while sleeping is disabled.

cpp

bool isObjectSleeping(std::size_t objectIndex) const

Parameters

Parameter	Description
`objectIndex` (in)	world index of the object

Returns true if the object is currently sleeping. False for an out-of-range index or while sleeping is disabled.

setBroadphaseSettings

cpp

void setBroadphaseSettings(const ::contact::BroadphaseSettings &settings)

Configure broadphase settings only. Call this when the world is not stepping.

Parameters

Parameter	Description
`settings` (in)	Broadphase settings.

getContactSettings

cpp

const ::contact::ContactSettings &getContactSettings() const

Returns current contact detection settings.

getBroadphaseSettings

cpp

const ::contact::BroadphaseSettings &getBroadphaseSettings() const

Returns current broadphase settings.

getWorldTime

cpp

double getWorldTime() const

Returns the total integrated time (s), advanced by the time step at every integrate2() call

setWorldTime

cpp

void setWorldTime(double time)

manually adjust the world time

Parameters

Parameter	Description
`time` (in)	the world time (s)

setSensorNoiseSeed

cpp

void setSensorNoiseSeed(uint64_t seed)

Restart attached sensor random streams using a deterministic environment seed. Call between complete steps, preferably before adding robots. Seed zero is the default. Sensor seed zero also derives a stream from its name and owning object's id; nonzero sensor seeds select explicit streams. Measurements and IMU model history are preserved. Checkpoints and world XML preserve this seed.

Parameters

Parameter	Description
`seed` (in)	Environment seed; all 64 bits participate.

getSensorNoiseSeed

cpp

uint64_t getSensorNoiseSeed() const

Returns The environment seed mixed into attached sensor streams.

getContactSolver

cpp

raisim::contact::BisectionContactSolver &getContactSolver()

Returns a non-const ref of the contact solver. contact::BisectionContactSolver::setOrder(bool) can be used to make the solver deterministic

cpp

const raisim::contact::BisectionContactSolver &getContactSolver() const

Returns a const ref of the contact solver. Internal states can be retrieved using this method

setContactSolverIterationOrder

cpp

void setContactSolverIterationOrder(bool order)

This sets the iteration order (e.g., forward and backward) of the contact solver. Given this order, Raisim is deterministic. Without an explicit order, the order flips in every integrate call.

Parameters

Parameter	Description
`order` (in)	True to keep a fixed iteration order for determinism.

getConfigFile

cpp

const std::string &getConfigFile()

get the config file if the world was created from a file (World(const std::string&, ...))

Returns the path to the config file, or an empty string

getRscene

cpp

const rscene::Scene *getRscene() const

The scene read by World(path) from a RaiSim Engine .rscene file, or included by a RaiSim world config (<include value="scene.rscene"/>), or null. It carries the render settings and instanced visuals a viewer applies (rayrai: a raisin::RayraiWindow on this world shows them by itself); the physics bodies are already in the world.

Returns the parsed scene, owned by the world, or nullptr if the world has no .rscene scene

getSharedRscene

cpp

const std::shared_ptr<const rscene::Scene> &getSharedRscene() const

Shared ownership of the immutable getRscene() scene, for readers that may outlive this world, such as a renderer's copy of a frame.

Returns the scene, or null if the world has no .rscene scene

getMaterialPairProperties

cpp

const MaterialPairProperties &getMaterialPairProperties(
    const std::string &mat1,
    const std::string &mat2) const

get the material pair properties. The order of materials does not matter. Unknown material names are treated as "default".

Parameters

Parameter	Description
`mat1` (in)	material name
`mat2` (in)	material name

Returns material pair properties, or the default material properties if no pair is defined

lockMutex

cpp

void lockMutex()

locks the world mutex. This can be used if you use raisim in a multi-threaded environment. The world does not lock it itself; every thread that accesses the world must lock it.

lock

cpp

void lock()

Same as lockMutex(). Lets World be used with std::lock_guard / std::unique_lock.

try_lock

cpp

bool try_lock()

Returns true if the world mutex was acquired without blocking (Lockable requirement)

unlockMutex

cpp

void unlockMutex()

unlock the world mutex. This can be used if you use raisim in a multi-threaded environment.

unlock

cpp

void unlock()

Same as unlockMutex(). Lets World be used with std::lock_guard / std::unique_lock.

updateSelfCollisionCache

cpp

void updateSelfCollisionCache()

Refresh contact body metadata after collision filter changes.

loadMjcfFile

cpp

void loadMjcfFile(const std::string &configFile)

Load a single self-contained MuJoCo XML file into this world. Equivalent to the dispatch that World(configFile) does internally when the file's root is <mujoco>; intended for callers (e.g. the rayrai TCP viewer's drag-drop inspector) that already have a constructed World and want to populate it from an MJCF path. The world should normally be empty before calling — MJCF files often declare ground planes, worldbody lights, and option blocks that overwrite world-level state.

Parameters

Parameter	Description
`configFile` (in)	path to the MJCF file

Static member functions

setActivationKey static

cpp

static void setActivationKey(const std::string &activationKey)

Set the path of the license (activation key) file. Call it before creating a World.

Parameters

Parameter	Description
`activationKey` (in)	path to the license file

abiGuard static

cpp

static void abiGuard(uint64_t headerLayoutStamp)

Internal: fatals when the caller's header layout stamp disagrees with the library's (header/library ABI mismatch). Called from constructors.

Parameters

Parameter	Description
`headerLayoutStamp` (in)	the caller's detail::headerLayoutStamp()

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::World ​

Nested classes ​

Public types ​

ObjectId ​

Constructors & destructor ​

World ​

~World ​

Public member functions ​

exportToXml ​

exportMeshAssetsToObj ​

setTimeStep ​

getTimeStep ​

addSphere ​

addBox ​

addCylinder ​

addCapsule ​

addGround ​

addHeightMap ​

addDeformableTerrain ​

addArticulatedSystem ​

addUsdArticulatedSystem ​

addCompound ​

addMesh ​

addDeformableCloth ​

addDeformableVolume ​

addDeformableObject ​

addGranularParticles ​

addGranularBox ​

getObject ​

addStiffWire ​

addCompliantWire ​

addCustomWire ​

addSpatialTendon ​

addFixedTendon ​

addTendonCoupling ​

getTendon ​

getTendons ​

onGranularParticleRemoved ​

onGranularParticlesReplacing ​

onGranularParticlesReplaced ​

getTendonCouplings ​

removeTendon ​

removeTendonCoupling ​

getConstraint ​

getWire ​

getWires ​

removeObject ​

getObjectCount ​

getObjectById ​

isObjectAlive ​

getObjList ​

getConfigurationNumber ​

getLifetimeIdentity ​

getLastCollisionCounters ​

raisim::World

Nested classes

Public types

ObjectId

Constructors & destructor

World

~World

Public member functions

exportToXml

exportMeshAssetsToObj

setTimeStep

getTimeStep

addSphere

addBox

addCylinder

addCapsule

addGround

addHeightMap

addDeformableTerrain

addArticulatedSystem

addUsdArticulatedSystem

addCompound

addMesh

addDeformableCloth

addDeformableVolume

addDeformableObject

addGranularParticles

addGranularBox

getObject

addStiffWire

addCompliantWire

addCustomWire

addSpatialTendon

addFixedTendon

addTendonCoupling

getTendon

getTendons

onGranularParticleRemoved

onGranularParticlesReplacing

onGranularParticlesReplaced

getTendonCouplings

removeTendon

removeTendonCoupling

getConstraint

getWire

getWires

removeObject

getObjectCount

getObjectById

isObjectAlive

getObjList

getConfigurationNumber

getLifetimeIdentity

getLastCollisionCounters

setCollisionCountersEnabled

getCollisionCountersEnabled

captureCheckpoint

restoreCheckpoint

setObjectCollisionFilter

setObjectMaterial

captureSingleBodySnapshot

restoreSingleBodySnapshot

cloneSingleBodyObject

rayTest

rayTestLidar

getRayCastBodies

captureDepthCamera

integrate

integrate1

integrate2

integrateNoContactDetection

getContactProblem

setGravity

updateMaterialProp

setMaterialPairProp

setDefaultMaterial

getGravity

setERP

setContactSolverParam

setContactSettings