Robot definition files (.rob)

A robot definition file ('.rob' file in the 'robots/'-subdirectory) defines the kinematics of a particular robot type, that is, the structure of the kinematic tree of a single robot of this type. (See, e.g., 'robots/puma500.rob'.) The first line in the file must be of the form

  #MPK v<num> robot

where <num> is the current MPK version number, e.g., 1.0. The rest of the file consists of a collection of nodes of types joint, selfcoll and param.

Although these node structures in the robot definition files are syntactically similar to OpenInventor nodes, the two should not be confused. Unlike MPK nodes in the scene definition files (see ), nodes in a robot definition file are not derived from OpenInventor nodes. Instead, a simple specialized parser is used to read '.rob'-files (see file 'basic/mpkBaseRobot.cpp').

A robot definition file typically contains several 'joint' nodes but at most one 'param' and 'selfcoll' node each. (Although an arbitrary number of 'param' or 'selfcoll' nodes is allowed, in most cases, it makes sense to define at most one of each.)

The following list describes the details of each node type in the robot definition file.

joint

A 'joint' structure defines a node in the kinematic tree of the robot.

Syntax:

joint <name> {
  <field-type1> <field-params1>
  <field-type2> <field-params2>
  ...
}

where <name> is a user-defined name for the joint, <field-type> is one of the types listed below, and <field-params> is a correct set of parameters as described for each of the types below.

A 'joint' node can optionally include the following fields (of the form <field-type> <field-params>):

parent <parent-name>

Attach the surrounding 'joint' node as a child to the 'joint' node with name <parent-name>. If this field is omitted, then the 'joint' node defines the root of a new kinematic tree that is fixed in the scene coordinate system. Note that more than one such tree is possible within a '.rob'-file. The transform of a 'joint' node is then the chain of transforms of all nodes on the path back to the (unique) root of the tree.

ConstTransl <x> <y> <z>

Add a constant (local) translation to the node by the vector (<x>, <y>, <z>).

ConstRot <ax-x> <ax-y> <ax-z> <ang>

Add a constant (local) rotation to the node by the angle <ang> (in radians) around the axis (<ax-x>, <ax-y>, <ax-z>). The axis is assumed to go through the origin of the (local) coordinate system.

Transl1 <x> <y> <z> <min> <max>

Add a (local) parameterized translation to the node along the vector (t*(<max> - <min>) + <min>) * (<x>, <y>, <z>) where t is the parameter value in [0,1]. The field 'param' (see below) must be added to specify the index of the parameter (default 0).

Rot1 <ax-x> <ax-y> <ax-z> <min> <max>

Add a (local) parameterized rotation to the node by the angle t*(<max> - <min>) + <min> (in radians) around the axis (<ax-x>, <ax-y>, <ax-z>) where t is a normalized parameter in [0,1]. The axis is assumed to go through the origin of the (local) coordinate system. The field 'param' (see below) must be added to specify the index of the parameter (default 0).

ConstTransl_Rot1 <x> <y> <z> <ax-x> <ax-y> <ax-z> <min> <max>

Add a (local) concatenation of a parameterized rotation by the angle t*(<max> - <min>) + <min> (in radians) around the axis (<ax-x>, <ax-y>, <ax-z>), followed by a constant translation by (<x>, <y>, <z>) to the node. The parameter t is normalized in the interval [0,1]. The axis of rotation is assumed to go through the origin of the (local) coordinate system. The field 'param' (see below) must be added to specify the index of the parameter (default 0).

param <num>

Specifies the index (in the configuration vector of the robot) of the parameter that influences a transform of type 'Transl1', 'Rot1' or 'ConstTransl_Rot1' (see above). Note that at most one such transform can be given per 'joint' node.

model0 <iv-fname>

Read a collision model from the file <iv-fname> (in OpenInventor format). This field is not obligatory. If no collision model is given, the 'joint' node is considered for kinematics computations only but not for collision checking (see, e.g., file 'robots/freeflyingL.rob').

model1 <iv-fname>

Read a second collision model. Some collision checking functions of the MPK library allow specifying which collision model to use. The second model could be a model of smaller complexity that includes the first model 'model0'. While 'model0' is always used for visualization, using another (simpler) model for collision checking may result in a faster collision check. Using a second collision model may be helpful for other purposes as well.

coll [TRUE | FALSE]

Default: TRUE (equals omitting the 'coll' field altogether). If this field is given and set to FALSE, then the collision models are used for visualization only but not checked for any collisions.

tracePoint

If specified, a 'trace point' is added to the 'joint' node. A trace point follows a (static) curve segment (which is, in general, non-linear) in space when the robot moves from one configuration to another. The GUI of MPK can display such curves of selected trace points to illustrate a robot's path. The trace point is by default at the origin of the local coordinate system. To realize another location, define an extra 'joint' node for the trace point that does not contain a collision model.

Note that multiple lines with constant transforms can be given within a single 'joint' node. In this case, all of them will be concatenated in the given order into a single constant transform. However, only a single parameterized transform can be given. To realize a chain of parameterized transforms that affects a single collision model, use a chain of 'joint' nodes, each with a single parameterized transform and without 'model0' or 'model1' entries, except the last one.

Example 1: The following example (taken from 'robots/puma500.rob') defines a 'joint' node with name 'Wrist3' that is attached to the 'joint' node named 'Wrist2'. It can rotate around the (local) axis (0, -1, 0) driven by parameter 5 within the angular bounds (-2.61, 2.61). A single geometric model is read from file 'Puma500/puma_6.iv' and used for both visualization and collision checking.

joint Wrist3 {
  parent Wrist2
  Rot1 0 -1 0 -2.61 2.61
  param 5
  model0 "Puma500/puma_6.iv"
}

Example 2: This example defines a 'trace point' that moves together with the frame of 'joint' node 'Wrist3' but is translated by a (constant) vector (0, 0.09, 0).

joint TracePoint {
  parent Wrist3
  ConstTransl 0 0.09 0
  tracePoint
}

selfcoll

A 'selfcoll' structure lists all pairs of joints whose link models should be checked for 'self-'collisions, that is, collisions of links of the same robot. If this structure is not given, then no self-collisions are checked for the robot.

Syntax:

selfcoll {
  <name1-a> <name1-b> 
  <name2-a> <name2-b> 
  ...
}

where, in each row, <name-a> and <name-b> are the names of two different 'joint' structures (see above) of the same robot. Note that both of these referenced 'joint' nodes should have a collision model defined.

param

The 'param' structure contains information about the individual parameters of the robot. Since a parameter can affect more than one joint, it would not make sense to store this information within each individual 'joint' structure.

Syntax:

param {
  <param1-idx> { <opt1-a> <opt1-b> ... }
  <param2-idx> { <opt2-a> <opt2-b> ... }
  ...
}

where <param-idx> is the index of a parameter in the robots configuration vector (note that these indices start with 0), and <opt-a> <opt-b> ... are options that will affect the indexed parameter. The following options are available:

cyclic

Indicates that the corresponding parameter is cyclic, i.e., it should 'wrap around' when it reaches a boundary of the normalized interval [0,1]. Default: off

passive

Indicates that the corresponding parameter should not be modified during planning. This can be used, e.g., for gripper DOFs to prevent the planner from creating a path on which the gripper randomly opens and closes. However, the animation does interpolate the corresponding parameter such that the gripper can open and close during a motion sequence that consists of several key configurations (see 'doc/fmstudio/index.html' for a definition of 'key configurations').

weight <val>

Assigns the weight <val> to the parameter. Weighted parameters can be useful in certain circumstances, e.g., for defining weighted norms on configurations.

default <val>

Assigns the default value <val> (must be in [0,1]) to the parameter. Unless this option is specified, the default value for all parameters is 0.5.