World

raisim::World class creates/manages all resources. All objects defined in the same Wolrd class instance can collide with each other unless otherwise their collision mask and group explicitly disables the collision ().

There are two ways to generate the World instance (i.e., two constuctors). The first way is to load an raisim world configuration file, which is in a form of an XML file. The second way is to generate world dynamically in code. You can also mix the two ways, by loading an XML file and dynamically adding objects.

RaiSim World Configuration File Convention

We provide a few examples here.

The following describes the RaiSim world configuration xml convention. The (optional) tag means that the element is optional given the parent. If the element is not marked (optional), it must exist given that the parent exist. The (multiple) tag means that there can be multiple elements for the same parent.

1. raisim: Top most node.

   1. <attribute> version : Describes the version of RaiSim that created the configuration file. The file might be read by different version.

   2. <child> (optional) materialFor more information and examples, check out here.

      1. <child> (optional) defaultIf it doesn’t exist, the default parameters are as described here.

         1. <attribute> friction [double]

         2. <attribute> restitution [double]

         3. <attribute> restitution_threshold [double]

      2. <child> (optional, multiple) pair_prop

         1. <attribute> name1 [string]

         2. <attribute> name2 [string]

         3. <attribute> friction [double]

         4. <attribute> restitution [double]

         5. <attribute> restitution_threshold [double]

   3. <child> (optional) gravity

      1. <attribute> value [Vec<3>]: default={0, 0, -9.81}

   4. <child> (optional) timestep

      1. <attribute> value [double]: default = 0.005

   5. <child> (optional) erpFor experts only. It is a spring and damper term to the error dynamics.

      1. <attribute> erp : spring term [double]

      2. <attribute> erp2 : damping term[double]

   6. <child> objects : described in “Object XML Description”

   7. <child> constraints : WORKING IN PROGRESS

Object XML Description

sphere

EXAMPLES

attributes: (optional, default=1) collision_group [uint64_t], (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional) body_type [string]: one of {dynamic, kinematic, static}, (optional) name [string], mass [double]

1. <child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]

2. <child> dim: <attribute> radius[double]

3. <child> state: <attribute> pos [Vec<3>], quat [Vec<4>], lin_vel [Vec<3>], ang_vel [Vec<3>]

capsule and cylinder

EXAMPLES

attributes: (optional, default=1) collision_group[uint64_t], (optional, default=-1) collision_mask[uint64_t], (optional) appearance[string], (optional) body_type[string]: one of {dynamic, kinematic, static}, (optional) name[string], mass[double]

1. <child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]

2. <child> dim: <attribute> radius [double], height [double]

3. <child> state: <attribute> pos [Vec<3>], quat [Vec<4>], lin_vel [Vec<3>], ang_vel [Vec<3>]

box

EXAMPLES

attributes: (optional, default=1) collision_group [uint64_t], (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional) body_type [string]: one of {dynamic, kinematic, static}, (optional) name [string], mass [double]

1. <child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]

2. <child> dim: <attribute> x [double], y [double], z [double]

3. <child> state: <attribute> pos [Vec<3>], quat [Vec<4>], lin_vel [Vec<3>], ang_vel [Vec<3>]

compound

EXAMPLES

attributes: (optional, default=1) collision_group [uint64_t], (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional) body_type [string]: one of {dynamic, kinematic, static}, (optional) name [string], com [Vec<3>], mass [double]

1. <child> (optional, default=From geometry assuming uniform density) inertia

   attributes: xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]

2. <child> children

   1. <child> (optional, multiple) sphere

      1. <child> dim

         1. <attribute> radius [double]

      2. <attribute> (optional, default=default) material

   2. <child> (optional, multiple) cylinder

      1. <child> dim

         1. <attribute> radius[double]

         2. <attribute> height[double]

      2. <attribute> (optional, default=default) material

   3. <child> (optional, multiple) capsule

      1. <child> dim

         1. <attribute> radius [double]

         2. <attribute> height [double]

      2. <attribute> (optional, default=default) material

   4. <child> (optional, multiple) box

      1. <child> dim

         1. <attribute> x [double]

         2. <attribute> y [double]

         3. <attribute> z [double]

      2. <attribute> (optional, default=default) material

3. <child> state

   attributes: pos [Vec<3>], quat [Vec<4>], lin_vel [Vec<3>], ang_vel [Vec<3>]

mesh

EXAMPLES

attributes: (optional, default=1) collision_group [uint64_t], (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional) body_type [string]: one of {dynamic, kinematic, static}, (optional) name [string], mass [double], file_name [string], com [Vec<3>], scale [Vec<3>]

1. <child> (optional, default=From geometry assuming uniform density) inertia

   attributes: xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]

2. <child> state

   attributes: pos [Vec<3>], quat [Vec<4>], lin_vel [Vec<3>], ang_vel [Vec<3>]

ground

EXAMPLES

attributes: (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional) name [string], (optional, default=0) height [double]

heightmap

EXAMPLES

Options

1. attributes: (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional, default=default) material [string], (optional) name [string], x_sample [size_t], y_sample [size_t], x_size [double], y_size [double], center_x [double], center_y [double], height [std::vector<double>]

2. attributes: (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional, default=default) material [string], (optional) name [string], x_sample [size_t], y_sample [size_t], x_size [double], y_size [double], center_x [double], center_y [double], z_scale [double], z_offset [double], png [string]

3. attributes: (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional, default=default) material [string], (optional) name [string], center_x [double], center_y [double], text [string]

4. attributes: (optional, default=-1) collision_mask [uint64_t], (optional) appearance [string], (optional, default=default) material [string], (optional) name [string], x_sample [size_t], y_sample [size_t], x_size [double], y_size [double], center_x [double], center_y [double]

   1. <child> terrain_properties

      attributes: z_scale [double], fractal_octaves [size_t], fractal_lacunarity [double], fractal_gain [double], step_size [double], frequency [double], seed [size_t]

articulated_system

EXAMPLES

attributes: (optional, default=1) collision_group [uint64_t], (optional, default=-1) collision_mask [uint64_t], (optional) name [string], (optional, default=the URDF directory) res_dir [string], urdf_path [string]

1. <child> state

   attributes: qpos [VecDyn], qvel [VecDyn]

Adding New Objects

To add a new object of a shape X, a method named addX is used. For example, to add a sphere

raisim::World world;
auto sphere = world.addSphere(0.5, 1.0);

Here sphere is a pointer to the internal resource. It can be used to access or to modify the internal variables.

There are three hidden arguments to all object-creation methods: material, collisionGroup and collisionMask. Descriptions of the collision varaibles are given in “Collision and Contact” chapter. material argument specifies the material which governs contact dynamics. It is further explained in “Material System” chapter.

The list of objects is given in “Object” chapter.

Once an object is added, a name can be set as below

sphere.setName("ball");

A pointer to an object with a specific name can be retrieved as below

auto ball = world.getObject("ball");

An object might contain multiple bodies (i.e., articulated system). To designate each body, local index can be used. To keep the interface consistent, many methods ask for the local index even for simgle body objects. In a single body object case, local index arguments are ignored and users can simply put 0 to comply with the AIP.

Changing Simulation Parameters

The following paramters can be changed using the world API

• Time step

RaiSim uses a fixed time step. The time step obtained and modified using getTimeStep and setTimeStep method.

API

class raisim::World

Public Functions

World()

Create an empty world

World(const std::string &configFile)

Create an world as specified in the xml config file

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

• dir: directory to save the xml file

• fileName: file name

void setTimeStep(double dt)

Parameters

• set: the time step

double getTimeStep() const

Return

the time step

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

Return

pointer to the created box

Parameters

• radius: radius

• mass: mass

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”.

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

Return

pointer to the created box

Parameters

• XLength: x dimension

• YLength: y dimension

• ZLength: z dimension

• mass: mass

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”.

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

Return

pointer to the created cylinder

Parameters

• radius: radius

• height: center-to-center distance

• mass: mass

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”.

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

Return

pointer to the created capsule

Parameters

• radius: radius

• height: center-to-center distance

• mass: mass

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”.

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

Return

pointer to the created ground

Parameters

• zHeight: height of the terrain

• material: material of the height map (which defines the contact dynamics)

• collisionMask: read “Contact and Collision/ Collision Group and Mask”. Note that collision group of a static object is CollisionGroup(1) << 61ul

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 = RAISIM_STATIC_COLLISION_GROUP, CollisionGroup collisionMask = CollisionGroup(-1))

Return

pointer to the created height map

Parameters

• xSamples: how many points along x axis

• ySamples: how many points along y axis

• xSize: x width of the height map

• ySize: y length of the height map

• centerX: x coordinate of the center of the height map

• centerY: y coordinate of the center of the height map

• height: a vector of doubles representing heights. the size should be xSample X ySamples

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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

Return

pointer to the created height map

Parameters

• raisimHeightMapFileName: the raisim text file which will be used to create the height map

• centerX: x coordinate of the center of the height map

• centerY: y coordinate of the center of the height map

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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 = RAISIM_STATIC_COLLISION_GROUP, CollisionGroup collisionMask = CollisionGroup(-1))

Return

pointer to the created height map

Parameters

• pngFileName: the png file which will be used to create the height map

• centerX: x coordinate of the center of the height map

• centerY: y coordinate of the center of the height map

• xSize: x width of the height map

• ySize: y length of the height map

• heightScale: a png file (if 8-bit) has pixel values from 0 to 255. This parameter scales the pixel values to the actual height

• heightOffset: height of the 0-value pixel

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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

Return

pointer to the created height map

Parameters

• centerX: x coordinate of the center of the height map

• centerY: y coordinate of the center of the height map

• terrainProperties: perlin noise parameters which will be used to create the height map

• material: material of the height map (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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

Return

pointer to the created height map

Parameters

• heightmapToBeCloned: Another height map to be cloned

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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())

Return

pointer to the articulated system

Parameters

• filePathOrURDFScript: 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: Path to the resource directory. Leave it empty (“”) if it is the urdf file directory

• jointOrder: 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: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

• option: Currently only support “doNotCollideWithParent”

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.

Return

pointer to the articulated system

Parameters

• child: an instance of Child class which has an articulated system structure.

• resPath: Path to the resource directory. Leave it empty (“”) if it is the urdf file directory

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

• option: Currently only support “doNotCollideWithParent”

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

Return

pointer to the created compound object

Parameters

• children: a vector of CompoundObjectChild which contains each primitive shape’s position, orientation, material and shape parameters

• mass: mass of the composite body

• COM: center of the composite body

• inertia: inertia of the composite body

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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. only the obj format is supported

Return

pointer to the created wire

Parameters

• meshFileInObjFormat: obj file of the mesh

• mass: mass

• inertia: inertia

• COM: the center of the mass

• scale: rescale the mesh

• material: material of the mesh (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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

create mesh collision body. only the obj format is supported

Return

pointer to the created wire

Parameters

• meshToClone: mesh to copy

• material: material of the mesh (which defines the contact dynamics)

• collisionGroup: read “Contact and Collision/ Collision Group and Mask”

• collisionMask: read “Contact and Collision/ Collision Group and Mask”

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.

Return

pointer to the created wire

Parameters

• obj1: the first object the wire is attached to

• localIdx1: the body index (0 for a SingleBodyObject) for the first object

• pos1_b: location of the cable attachment on the first object

• obj2: the second object the wire is attached to

• localIdx2: the body index (0 for a SingleBodyObject) for the second object

• pos2_b: location of the cable attachment on the second object

• length: length of the wire

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.

Return

pointer to the created wire

Parameters

• obj1: the first object the wire is attached to

• localIdx1: the body index (0 for a SingleBodyObject) for the first object

• pos1_b: location of the cable attachment on the first object

• obj2: the second object the wire is attached to

• localIdx2: the body index (0 for a SingleBodyObject) for the second object

• pos2_b: location of the cable attachment on the second object

• length: length of the wire

• stiffness: stiffness of the wire

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

Return

object with the given name. returns nullptr if the object doesn’t exist. The name can be set by Object::setName()

Object *getObject(std::size_t worldIndex)

Return

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

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

Return

returns a non-const vector of the objects

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

Return

a constraint (e.g., wires) with the given name. returns nullptr if the object doesn’t exist. The name can be set by Wire::setName()

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

Return

a wire with the given name. returns nullptr if the object doesn’t exist. The name can be set by Wire::setName()

unsigned long getConfigurationNumber()

Return

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

const RayCollisionList &rayTest(const Eigen::Vector3d &start, const Eigen::Vector3d &direction, double length, bool closestOnly = true, CollisionGroup collisionMask = CollisionGroup(-1))

Returns the internal reference of the ray collision list it contains the geoms (position, normal, object world/local id) and the number of intersections This returns

Return

A reference to the internal container which contains all ray collisions.

Parameters

• [in] start: The start position of the ray.

• [in] direction: The direction of the ray.

• [in] length: The length of the ray.

• [in] closestOnly: Only stores the first collision.

• [in] collisionMask: Collision mask to filter collisions. By default, it records collisions with all collision groups.

void removeObject(Object *obj)

removes an object

Parameters

• obj: object to be removed

void removeObject(StiffLengthConstraint *wire)

removes a stiff wire

Parameters

• wire: the stiff wire to be removed

void removeObject(CompliantLengthConstraint *wire)

removes a compliant wire

Parameters

• wire: the compliant wire to be removed

void integrate()

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

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

void integrate2()

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

const ContactProblems *getContactProblem() const

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

void updateMaterialProp(const MaterialManager &prop)

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

Parameters

• prop: new material prop

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.

Parameters

• mat1: name of the first material (the order of mat1 and mat2 is not important)

• mat2: name of the first material

• friction: the coefficient of friction

• restitution: the coefficient of restitution

• resThreshold: the minimum impact velocity to make the object bounce

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

Parameters

• friction: the coefficient of friction

• restitution: the coefficient of restitution

• resThreshold: the minimum impact velocity to make the object bounce

const Vec<3> &getGravity() const

Return

gravitational acceleration of the world

void setERP(double erp, double erp2 = 0)

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

Parameters

• erp: spring constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning

• erp2: damping constant between object. This constant is scaled by the apparent inertia so it has no well-defined physical meaning

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.”

Parameters

• alpha_init: how aggressive the solver is initially

• alpha_min: how aggressive the solver is after an infinite number of solver iterations

• alpha_decay: how fast alpha converges from alpha_init to alpha_min

• threshold: error threshold for termination

• maxIter: the maximum number of iterations allowed

double getWorldTime() const

Return

the total integrated time (which is updated at every integrate2() call)

void setWorldTime(double time)

manually adjust the world time

Parameters

• the: world time

raisim::contact::BisectionContactSolver &getContactSolver()

Return

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

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

Return

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

const std::string &getConfigFile()

get the config file if the world was created using a xml config file

Return

the path to the xml config file

std::vector<std::unique_ptr<StiffLengthConstraint>> &getStiffWire()

get a vector stiff wires in the world

Return

a vector of unique_ptrs of stiff wires

std::vector<std::unique_ptr<CompliantLengthConstraint>> &getCompliantWire()

get a vector compliant wires in the world

Return

a vector of unique_ptrs of compliant wires

Public Static Functions

void setActivationKey(const std::string &activationKey)

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

Parameters

• licenseFile: path to the license file