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.

RaiSim uses a preprocessor to generate an xml. An example of an xml script that uses the preprocessor can be found here. Currently, you can use two features.

Array: Array is like a forloop in C++. It can be used in any nodes
Math expresion: Inside of {}, you can define a one-liner math expression.

An example of the two features are shown below.

<array idx="@@idx" start="0" end="80" increment="1">
    <sphere name="sphere_array_@@idx"  mass="1">
        <dim radius="{0.5+@@idx*0.001}" />
        <state pos="{cos(0.1*@@idx)*(@@idx*0.2+0.1)} {sin(0.1*@@idx)*(@@idx*0.2+0.1)} {@@sphere_height_offset+@@idx*1.0}"/>
    </sphere>
    <box name="box" mass="1">
        <dim x="0.5" y="0.5" z="1"/>
        <inertia xx="0.1" xy="0" xz="0" yy="0.1" yz="0" zz="0.1" />
        <state pos="{cos(0.1*@@idx)*(@@idx*0.3+0.2)} {sin(0.1*@@idx)*(@@idx*0.3+0.2)} {@@sphere_height_offset+@@idx*1.0}"/>
    </box>
</array>

Note that these feature are node independent. You can use them anywhere in the xml script. You have to be careful not to generate multiple object with the same name. Otherwise, the RaisimUnity will not work probably.

The main xml structure is shown below

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. 1. <child> params : list of parameters to generate the xml script, EXAMPLE. Parameters are handled by the preprocessor. 2. <child> (optional) material : For more information and examples, check out here.
<child> (optional) defaultIf it doesn’t exist, the default parameters are as described here.

<attribute> friction [double]

<attribute> restitution [double]

<attribute> restitution_threshold [double]

<child> (optional, multiple) pair_prop

<attribute> name1 [string]

<attribute> name2 [string]

<attribute> friction [double]

<attribute> restitution [double]

<attribute> restitution_threshold [double]
1. <child> (optional) gravity
  
  <attribute> value [Vec<3>]: default={0, 0, -9.81}
2. <child> (optional) timestep
  
  <attribute> value [double]: default = 0.005
3. <child> (optional) erpFor experts only. It is a spring and damper term to the error dynamics.
  
  <attribute> erp : spring term [double]
  
  <attribute> erp2 : damping term [double]
4. <child> objects : described in “Object XML Description”
5. <child> wireDESCRIPTION, EXAMPLES
  
  <attribute> name [string]: wire name
  
  <attribute> type [string]: wire type. “stiff”, “compliant”, or “custom”
  
  <attribute> stretch_type [string]: stretch type
  
  <child> object1 and object2the object to which the wire is attached
  First option 1. <attribute> local_index [int]: The body index for the wire attachment. 0 for singleBodyObject. 2. <attribute> pos [Vec<3>]: The position in the local body frame to where the wire is attached. Second option, for articulated system only 1. <attribute> frame [string]: The name of the frame to where the wire is attached.

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]

<child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]
<child> dim: <attribute> radius[double]
<child> state: <attribute> pos [Vec<3>], (optional, default=1,0,0,0) quat [Vec<4>], (optional, default=0,0,0) lin_vel [Vec<3>], (optional, default=0,0,0) 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]

<child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]
<child> dim: <attribute> radius [double], height [double]
<child> state: <attribute> pos [Vec<3>], (optional, default=1,0,0,0) quat [Vec<4>], (optional, default=0,0,0) lin_vel [Vec<3>], (optional, default=0,0,0) 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]

<child> (optional, default=From geometry assuming uniform density) inertia : <attribute> xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]
<child> dim: <attribute> x [double], y [double], z [double]
<child> state: <attribute> pos [Vec<3>], (optional, default=1,0,0,0) quat [Vec<4>], (optional, default=0,0,0) lin_vel [Vec<3>], (optional, default=0,0,0) 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]

<child> (optional, default=From geometry assuming uniform density) inertia
attributes: xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]
<child> children
1. <child> (optional, multiple) sphere
  
  <child> dim
  
  <attribute> radius [double]
  
  <attribute> (optional, default=default) material
2. <child> (optional, multiple) cylinder
  
  <child> dim
  
  <attribute> radius[double]
  
  <attribute> height[double]
  
  <attribute> (optional, default=default) material
3. <child> (optional, multiple) capsule
  
  <child> dim
  
  <attribute> radius [double]
  
  <attribute> height [double]
  
  <attribute> (optional, default=default) material
4. <child> (optional, multiple) box
  
  <child> dim
  
  <attribute> x [double]
  
  <attribute> y [double]
  
  <attribute> z [double]
  
  <attribute> (optional, default=default) material
<child> state
attributes: pos [Vec<3>], (optional, default=1,0,0,0) quat [Vec<4>], (optional, default=0,0,0) lin_vel [Vec<3>], (optional, default=0,0,0) 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>]

<child> (optional, default=From geometry assuming uniform density) inertia
attributes: xx [double], xy [double], xz [double], yy [double], yz [double], zz [double]
<child> state
attributes: pos [Vec<3>], (optional, default=1,0,0,0) quat [Vec<4>], (optional, default=0,0,0) lin_vel [Vec<3>], (optional, default=0,0,0) 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

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>]
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]
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]
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]

<child> state
attributes: qpos [VecDyn], (optional, default=zeros) 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.

Save world to an XML file¶

raisim::World::exportToXml() lets you save the world to an XML file. EXAMPLES

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