User manual

old releases - latest release - trunk

Syntax reference

Layer and color

The layer and color elements may be contained directly within the <scene> element, within a scene object element, or inside each other (color inside layer, or layer inside color):

<layer number="x"> ... </layer>
All objects declared inside this element will be added to layer $x \in \{1,2, \dots, 16\}$, unless overriden by another layer element. The default layer, used when no layer tag is present, is layer 1.
<color r="R" g="G" b="B"> ... </color>
All objects declared inside this element will have the color specified by the given RGB triplet. $R,G,B \in [0,1]$.

External

See External blocks for more information about external.

Syntax
...
<external>
  <!-- any well-formed XML -->
</external>

Include

Syntax
...
<include file="source_file">
  <inject at="injection_path"> <!-- optional -->
    <!-- any number of object definitions, includes or external tags are allowed here -->
  </inject>
  ...
  <inject at="injection_path">
    ...
  </inject>
</include>
The inject tags are optional. Aside from the inject tag, external tags are also allowed inside include elements.

For more information about include injection, see Injecting data in included files.

Properties common to all objects

The definition of an object of any type can contain the following tags, which must come in the order they are specified here. None of these elements are required.

<name> ... </name>
Specifies the name of the object. Names may contain all characters except periods. Remember that object names must be unique among siblings.
If no name is explicitly specified the object will be named according to its type and enumerated as needed to preserve name uniqueness among its siblings. For example, with this scheme, a <sphere>-element might yield an object named sphere5.
<meta_name> ... </meta_name>
Specifies the meta name of the object - a more descriptional name used only for informational purposes.
<opacity absolute="x">a</opacity>
Specifies the opacity of an object. x must be true or false, where false is the default. a is a number in the interval $[0, 1]$ specifying the object's absolute opacity, or its opacity relative its parent node.
<hidden/>
If this tag is present, the object and all its children will be hidden by default.
<transform> ... </transform>
Specifies any transforms that are to be applied to the object - more on this later.
<children> ... </children>
May contain any number of scene object (or derived types), color or layer elements. The objects defined in this element will be the children of the current object.

Position and orientation

Inside the transform element, any of the following elements may appear in any order (they will be applied in the order they appear):

<translate system="s"> x y z </translate>
Moves the object by the vector (x, y, z) along to the axes of coordinate system s, which can be parent, world (the root of the scene file) or local, where world is the default.
<rotate> ... </rotate>
Rotates the object as specified by the subelements:
<axis system="s"> x y z </axis>
The vector (x, y, z) specifies the axis of rotation, and may be specified in different coordinate systems as with the <translate> element. The default value is (1, 0, 0) and world coordinates.
<pivot system="s"> x y z </pivot>
Specifies the pivot point around which to rotate the object. The system 's' is specified as with the <translate> tag. The default is (0, 0, 0) and local coordinates. 
<radians> r </radians> or <degrees> d </degrees>
Specifies magnitude of rotation in either radians or degrees.
Example
<transform>
  <translate>0 0 1.2</translate>
  <rotate>
    <axis>0 1 0</axis>
    <degrees>45</degrees>
  </rotate>
</transform>
The matrix element, specified with the syntax given below, loads a transformation matrix, describing the object's transformation in the given coordinate system s.

<matrix system="s">
  x1 x2 x3 x4
  y1 y2 y3 y4
  z1 z2 z3 z4
  0   0  0  1
</matrix>
s may be either world or parent, where the latter is the default. The first, second and third column vectors represent the x-, y- and z-axis respectively. The fourth column vector is the translation relative the coordinate system's origin.
The upper left 3x3 submatrix must specify an orthonormal basis of $R^3$.

Scale

Most objects (geometric primitives, mostly) allow adjusting the scale along the local axes using the <scale>-element.

<scale>x y z</scale>
Where x, y and z are the scale factors for the different axes.

Line parameters

For primitives comprised of lines (line clouds, grids, etc.) the width and the pattern of the lines can be changed.

The line style parameters are optional and the default is solid lines of width one.

Syntax
<line_width>w</line_width>
<line_style factor="x">solid|dotted|dash-dot|dash-dot-dot</line_style> <!-- x = 1,2,... -->
Where w is a floating point number and x is an integer describing how often the line pattern repeats.

Cameras

Camera object declarations may contain the following properties in addition to those common to all scene objets:

<orthographic/>
If present, the view mode of the camera is set to orthographic (perspective mode is the default).
<fov>
  <degrees>d</degrees>
  OR
  <radians>d</radians>
</fov>
Sets the vertical field of view of the camera to d degrees or radians. d must be in the range $(0,180)$ degrees.

Groups

Prodives a way to group similar objects without adding new graphical elements to the scene.

Example
<group>
  ... 
  <children>...</children>
</group>

Spheres, cylinders, cubes and circles

The sphere, cylinder, cube and circle elements are all scalable objects. Except for the optional scale parameters, neither of them add any extra markup.

Example
<sphere>
  <children>
    <cylinder>
      <scale>0.5 0.5 2</scale> <!-- diameter=1, height=2 -->
    </cylinder>
  </children>
</sphere>

Polygons, point clouds and line clouds

The point-cloud, line-cloud and polygon objects share a few important traits: they're are all scalable and their geometry is defined by vertices.

The <vertices> element is used to specify which vertices the object is comprised of:

<vertices>
  <vertex>x1 y1 z1</vertex>
  <vertex>x2 y2 z2</vertex>
  ...
</vertices>

Vertex order
For planes and polygons, vertices must be specified in counter clockwise order, otherwise the result is undefined.

Models

Models are scalable and require one additional element to be present:

<file> ... </file>
The <file> tag specifies which model file to use. See the tutorial for information on which locations peekabot searches for models in. See the section on model conversion for information on which model formats that are supported by peekabot.

Grids

Syntax
<grid>
  ...
  <type> regular|radial|angular </type> <!-- optional, default: regular -->
  <segments> X </segments> <!-- required, X must be an integer larger than 0 -->
  <central_angle> <!-- optional, default: 360 degrees -->
    <degrees>Y</degrees>
    OR
    <radians>Y</radians>
  </central_angle>
</grid>
The grid type is specified with the <type> element and defaults to regular if the type element is left out.

Common to all grid types is that the number of segements in the grid must be specified somehow, more specifically, using the <segments> element. A regular grid with 10 segments will have 10*10 = 100 grid elements and a radial grid with 10 segments will consist of 10 concentric circular segments.

The optional <central_angle> element determines how far radial and angular grids extend - it has no effect on regular grids. If left out, it defaults to 360 degrees.

Examples
<!-- A 10x10 m cartesian grid with a resolution of 10 cm -->
<grid>
  <scale>0.1 0.1 0.1</scale>
  <segments>100</segments>
</grid>
<!-- An 8 m radius radial grid with a resolution of 1 m -->
<grid>
  <type>radial</type>
  <segments>8</segments>
</grid>
<!-- An 8 m radius angular, 180 degree grid with 10 degree resolution -->
<grid>
  <scale>8 8 8</scale>
  <type>angular</type>
  <segments>18</segments>
  <central_angle>
    <degrees>180</degrees>
  </central_angle>
</grid>

Labels

Syntax
<label>
  ...
  <text>label text</text> <!-- optional -->
  <align>left | right | center</align> <!-- optional -->
</label>
By default, labels are left-aligned and empty.

Sensors

Syntax
<sensor type="type">
  <params> <!-- optional -->
    ...
  </params>
</sensor>
Where type is the type of the sensor (see this section for a list of the available sensor types).
In addition to the elements used in all object-defining elements, sensor definitions can also contain a <params> element that's used to setup certain properties of the sensor. The <params> element can contain int, float string, bool and color elements, each of which has a name attribute to specify which parameter is being specified.

Except for color, the parameter data is specified in the CDATA. For color elements, the data is specified with three attributes (r,g,b).

Example
<sensor type="X">
  ... 
  <params>
    <int name="samples">361</int>
    <color name="foobar" r="0" g="0" b="1"/>
    ...
  </params>
</sensor>
Documentation of available parameters along with their datatypes and semantics is found in the documentation pertaining to the relevant sensor type.

Degrees of freedoms

All DOF (degree of freedom) types have a few common properties: The DOF value offset should be used if the configuration of the DOF/manipulator in the definition file is not the zero configuration. E.g. if the configuration of a 3-DOF arm in the definition file corresponds to "0, -90, 0" the offset should be set to 0, -90 and 0 for the three DOFs respectively.

Joints

Joints are a rotational DOFs that result in rotation in the plane perpendicular to the given rotational axis. All rotations are done about the specified pivot point.

Syntax
<joint>
  ...
  <min>
    <radians>a</radians> or <degrees>a</degrees>
  </min>
  <max>
    <radians>b</radians> or <degrees>b</degrees>
  </max>
  <initial>
    <radians>c</radians> or <degrees>c</degrees>
  </initial>
  <offset>
    <radians>c</radians> or <degrees>c</degrees>
  </offset>

  <axis system="s">
    x y z
  </axis>

  <pivot system="s">
    x y z
  </pivot>
</joint>
Where s is the coordinate system the point/vector is given in. s can be any of local, parent and world.
The order of the elements is not relevant and all elements are optional. The defaults are listed below:

Tracks

Tracks are a translational DOFs that move all child objects along the axis specified by the <axis> element.

Syntax
<track>
  ...
  <min>a</min>
  <max>b</max>
  <initial>c</initial>
  <offset>c</offset>

  <axis system="s">
    x y z
  </axis>
</track>
Where s is the coordinate system the point/vector is given in. s can be any of local, parent and world.
The order of the elements is not relevant and all elements are optional. The defaults are listed below:

Robots

Robot objects are no different from ordinary groups - the only difference is a fancier icon. For historical reasons and backwards compatibility, robot objects still exists.

Syntax
<robot>
  <name>...</name> <!-- optional -->
  ... <!-- <the usual set of allowed tags go here> -->
</robot>