Skip to content
malter edited this page Nov 16, 2021 · 2 revisions

Overview

MARS scenes are MARS's original scene format encoded in XML. They have been replaced with the introduction of the [SMURF and SMURF scene](SMURF Scenes) formats, but we have maintained backwards compatibility and it is still possible to load MARS scenes.

If for some reasons it is not possible for you to use a SMURF/URDF representation of a robot with MARS, you can still create MARS scenes with Blender using the export scripts and following the [tutorials](@ref tutorials). You can even combine existing MARS scenes with the SMURF scenes format.

In general, we do not recommend the use of MARS scenes, as we will not be working on MARS scenes any more in future development and we may even have to break with backwards compatibility at some point (though we will tag a MARS release before that happens, if it ever does happen).

NOTE: Phobos has an option to import MARS scenes as of version 0.6.5., so that it should be very little work to transform old robot representations. As of version 0.7, this also includes MARS scenes with multiple "entities", such as a heightmap and a robot.

XML Definition

MARS scene files possess the extension .scene and are XML files with following principal structure:

<?xml version="1.0"?>
<!DOCTYPE dfkiMarsSceneFile PUBLIC '-//DFKI/RIC/MARS SceneFile 1.0//EN' ''>
<SceneFile>
  <version>0.2</version>
  <nodelist>
  <jointlist>
  <motorlist>
  <sensorlist>
  <controllerlist>
  <materiallist>
  <graphicOptions>
</SceneFile>

You may have noted that the lists of items correspond to the types of objects needed to represent a robot graphically as well as physically. However, MARS scenes can not merely be used for robots, but also to define an environment a robot can operate in. As it is possible to load multiple MARS scenes in the same MARS simulation, it thus makes sense to save robots and environment in different scene files. This makes it a lot easier to edit the files and to prevent errors in one element of a simulation interfering with another part. It also enables the user to test the same robot in various environments without having to re-edit any of the underlying scenes.

When you load multiple scenes into MARS, make sure that they are all in the same scale.

We will have a closer look at the items in these lists in the following.

Nodes

Nodes are all visible objects in MARS, whether they are physical objects or not. Now

--> show notedata.h

<node name="node_name">
  <origname>
  <filename>
  <index>
  <groupid>
  <physicmode>
  <relativeid>
  <position>
    <x>
    <y>
    <z>
  <rotation>
    <x>
    <y>
    <z>
    <w>
  <extend>
    <x>
    <y>
    <z>
  <pivot>
    <x>
    <y>
    <z>
  <visualsize>
    <x>
    <y>
    <z>
  <movable>
  <mass>
  <density>
  <material_id>
  <coll_bitmask>
Variable Description Possible Values
origname name used in Blender to represent the object any String
filename name of the *.obj or *.bobj file associated with this note any valid file path
index running index of the nodes int ≥ 1
groupid id of the group to which a node belongs int ≥ 1
physicmode primitive object by which the node is represented in physics box, sphere, capsule, cylinder, plane, terrain, mesh
relativeid ? ?
position position of the node in x, y and z coordinates double
rotation rotation of the node in quaternion format double
extend extend of the representing primitive (see physicmode) double
pivot ? ?
visualsize ? ?
movable whether or not the object is fixed in the world true / false
mass mass of the object in kg (note: the mass is only applied if the density is set to 0) double
density density of the object in kg/m³ double
material_id index of the associated material int ≥ 1
coll_bitmask bitmask to define groups of collision objects int < 65536
t_srcname source name for terrain string
t_width width of terrain double
t_height height of terrain double
t_scale scale of terrain double
t_tex_scale texture scale for terrain
t_tex_scale_x texture scale for terrain
t_tex_scale_y texture scale for terrain
visualposition offset of position of visual representation vector
visualrotation rotational offset of visual representation quaternion
visualsize size of visual representation double
cmax_num_contacts maximum number of contacts in ODE of this node int
cerp double
ccfm double
cfriction1 double
cfriction2 double
cmotion1 double
cmotion2 double
cfds1 double
cfds2 double
cbounce double
cbounce_vel double
capprox use of simplified friction pyramid bool
rolling_friction friction value for rolling, if this property is set rolling friction is enabled double
rolling_friction2 friction value for rolling in friction direction2, if not set the value of rolling_friction is used double
inertia whether or not the defined inertias are used bool
i00 double
i01 double
i02 double
i10 double
i11 double
i12 double
i20 double
i21 double
i22 double
linear_damping damping of linear motion double
angular_damping damping of angular motion double
angular_low double
shadow_id shadow id object is associated with int
shadowcaster objects casts shadows bool
shadowreceiver objects subject to shadows bool

Joints

Joints are helper objects defining how nodes or groups of nodes are connected with each other.

<joint name="joint_name">
  <index>
  <type>
  <nodeindex1>
  <nodeindex2>
  <anchorpos>
  <anchor>
    <x>
    <y>
    <z>
  <spring_constant>
  <damping_constant>
  <axis1>
    <x>
    <y>
    <z>
  <angle1_offset>
  <lowStopAxis1>
  <highStopAxis1>
  <damping_const_constraint_axis1>
  <spring_const_constraint_axis1>
  <axis2>
    <x>
    <y>
    <z>
  <angle1_offset>
  <lowStopAxis2>
  <highStopAxis2>
  <damping_const_constraint_axis2>
  <spring_const_constraint_axis2>
Variable Description Possible Values
index running index of the joints int ≥ 1
type type of the joint (note: a ball joint needs spring and damping properties set) hinge, hinge2, slider, ball, universal, fixed
nodeindex1 index of first attached node valid node id
nodeindex2 index of second attached node valid node id
anchorpos node to which the joint is anchored node1, node2, center, custom
anchor use this vector if anchorpos is set to custom x, y, z: double
axis1 axis around / along which joint moves (note: also the ball joint currently needs this property set) x, y, z: double
angle1_offset initial offset of the joint double
lowStopAxis1
highStopAxis1
damping_const_constraint_axis1
spring_const_constraint_axis1
axis2
angle1_offset
lowStopAxis2
highStopAxis2
damping_const_constraint_axis2
spring_const_constraint_axis2

Motors

Motors are associated with joints and can apply forces and torques respectively; for a slider joint, a force is applied while for a hinge joint, motors create a torque. As MARS uses the Open Dynamics Engine for its physics simulation, you can have a look at ODE's documentation to read further on different joint and motor types.

As for the decoding in MARS scenes, motors are described as follows:

<motor name="H.Hip.000">
  <index>
  <jointIndex>
  <jointIndex2>
  <axis>
  <maximumVelocity>
  <motorMaxForce>
  <type>
  <p>
  <i>
  <d>
  <Km>
  <Kn>
  <Ra>
  <Lm>
  <Jm>
  <Rm>
  <U>
  <gear>
  <max_current>
  <r_current>
  <min_val>
  <max_val>
  <value>
Variable Description Possible Values
index index of the motor int ≥ 1
jointIndex index of the joint with which the motor is associated int≥ 1
jointIndex2 ? int
axis around/along which axis of its associated joint the motor turns/slides 1 ≤ int ≤ 3
maximumVelocity maximum velocity with which the motor can move the joint double
motorMaxForce maximum force the motor can apply double
type motor type 1: servo, 2: electric motor
p P value of a PID controller double
i I value of a PID controller double
d D value of a PID controller double
Km
Kn
Ra
Lm
Jm
Rm
U
gear
max_current
r_current
min_val minimum value (see below) ?
max_val maximum value (see below) ?
value ? ?

Sensors

There are a number of different sensors in MARS which can be attached to nodes, joints or motors in order to get readings of certain variables. The valid types are:

Type Data yielded
Camera ?
Joint6DOF ?
JointArray ?
JointAVGTorque ?
JointLoad load of associated joint
JointPosition position of associated joint
JointTorque torque of associated joint
JointVelocity velocity of associated joint
MotorCurrent current of associated motor
NodeAngularVelocity angular velocity of associated node
NodeArray ?
NodeCOM center of mass (COM) of associated node
NodeContactForce contact force of associated node
NodePosition position of associated node
NodeRotation rotation of associated node
NodeVelocity velocity of associated node
RayGrid collision point cloud of ray grid traced in defined direction
Ray collision point of ray traced in defined direction
ScanningSonar ?

Sensors are defined in a scene file as follows:

<sensor name="sensorName" type="sensorType">
  <index>
  <rate>
  <dylib_path>
  <id>
  ...
  <id>
Variable Description Possible Values
sensor.name name of the sensor any valid string
sensor.type type of the sensor any valid sensor type with respect to id
index running index of the sensor int ≥ 1
rate reading rate of sensor double
id id of node, joint or motor any valid id; can be list of multiple ids

Controllers

Controllers ...

<controller>
  <rate>
  <sensorid>
  <sensorid>
  ...
  <motorid>
  <motorid>
  ...
Variable Description Possible values
rate operation rate of the controller ?
sensorid running index of an attached sensor int ≥ 1
motorid running index of an attached motor int ≥ 1

Materials

<material>
  <id>
  <ambientFront>
    <a>
    <r>
    <g>
    <b>
  <diffuseFront>
    <a>
    <r>
    <g>
    <b>
  <specularFront>
    <a>
    <r>
    <g>
    <b>
  <emissionFront>
    <a>
    <r>
    <g>
    <b>
  <ambientBack>
    <a>
    <r>
    <g>
    <b>
  <diffuseBack>
    <a>
    <r>
    <g>
    <b>
  <specularBack>
    <a>
    <r>
    <g>
    <b>
  <emissionBack>
    <a>
    <r>
    <g>
    <b>
  <transparency>
  <shininess>
  <texturename>
  <reflect>
  <bumpmap>
  <tex_scale>
  <brightness>
  <getLight>
  <cullMask>
Variable Description Possible Values
id running index of the materials int ≥ 1
ambientFront ? a, r, g, b: 0 ≤ double ≤ 1
diffuseFront basic color of an object a, r, g, b: 0 ≤ double ≤ 1
emissionFront color of light relfected off of object front faces a, r, g, b: 0 ≤ double ≤ 1
specularFront color of light reflection on object's front faces a, r, g, b: 0 ≤ double ≤ 1
ambientBack ? a, r, g, b: 0 ≤ double ≤ 1
diffuseBack basic color of object back faces a, r, g, b: 0 ≤ double ≤ 1
specularBack color of light reflection on an object's back faces a, r, g, b: 0 ≤ double ≤ 1
emissionBack color of light reflection on object's front faces a, r, g, b: 0 ≤ double ≤ 1
shininess strength of light reflexion 0 ≤ double ≤ 1

Graphic Options

    <clearColor>
      <r>
      <g>
      <b>
      <a>
    <fogEnabled>
    <fogDensity>
    <fogStart>
    <fogEnd>
    <fogColor>
      <r>
      <g>
      <b>
      <a>
Variable Description Possible Values
clearColor ? ?
fogEnabled whether or not there is fog in the simulation true / false
fogDensity density of fog
fogStart distance where the fog starts
fogEnd distance where the fog ends
fogColor rgba values to define fog color