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|dashed|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, polylines, point clouds and line clouds

The point-cloud, line-cloud, polyline 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>

N vertices yields N points for a point cloud, N/2 lines a line cloud, an open polygonal chain with N-1 lines for a polyline and a closed polygon with N sides for a polygon.

Vertex order
For polygons, vertices must be specified in counterclockwise order.

Tri-meshes

Tri-meshes are specified through a set of vertices, just like polygons and line clouds, but also require a sequence of index triplets which define which vertices that should form triangles. The syntax for specifying the vertices is the same as for polygons.

The <triangles> element is used to specify which vertices to connect together into triangles:

<triangles>
  <vertex>index-1 index-2 index-3</vertex>
  <vertex>index-1 index-2 index-3</vertex>
  ...
</triangles>

The indices are zero-indexed.

Polygon winding
The triangles are specified in counterclockwise order.

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.

Joints

All joint types have a few common properties:

The joint value offset should be used if the configuration of the joint 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 joints respectively.

Hinges

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

Syntax
<hinge>
  ...
  <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>
</hinge>
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:

Sliders

Sliders (also commonly called prismatic joints) provide translational DOFs, that move all child objects along the axis specified by the <axis> element.

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

  <axis system="s">
    x y z
  </axis>
</slider>
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:

Generated on Sun Jan 30 2011 for peekabot by  doxygen 1.7.1