Overview and motivation

Introduction

Scene files allow you to define geometry (and more) which can be loaded into peekabot, without writing any code! Scene files are specified in human-readable XML mark-up and have a potential number of benefits over doing everything from your client(s):

• Provides a good way of interoperating with existing datasets stored in similar formats.
• Facilitates easy reuse and sharing.
• The visual appearance of robots/environments/etc. can changed without changing the client.
• Use can use the same scene file with clients written in any language (if the peekabot client library is ported to other languages in the future, that is)

Furthermore, not all things are currently exposed in the client library.

Typical use case for scene files are:

• Defining the visual appearance and degrees of freedoms of a robotic arm.
• Defining a reference map of the environment the robot is operating in.

A scene file contains elements for instantiating objects and their properties. The general layout of a scene file is:

<?xml version="1.0"?> <!-- required -->
<scene> <!-- required -->
  <object_type1>
    <object_prop1>...</object_prop1>
    <object_prop2>...</object_prop2>

    <children>
      <object_type2>...</object_type2>
    </children>
  </object_type1>
</scene>

Of course, there are plenty of exceptions to this general rule of thumb. For example, layer and color is specified by enclosing an object (or indeed several objects) in a <layer> or <color> tag, e.g.:

<?xml version="1.0"?>
<scene>
  <color r="0" g="0" b="1">
    <sphere/>
    <cube/>
  </color>
</scene>

Object instantiations, layer and color aside, there is a handful other elements that can be used - which are discussed in the section Advanced topics.

An example - defining a pan-tilt unit

The example below shows a real-life example of what a definition file might look like. It combines three models into a complete pan-tilt unit with 2 rotational DOFs that can be controlled from clients.

<?xml version="1.0"?>
<scene>
  <model>
    <!-- file is specific to the model object, and simply defines 
         which model to load -->
    <file>dp-ptu-d46/bottom.pbmf</file>
    <!-- set the name of the object to "ptu_bottom" -->
    <name>ptu_bottom</name>
  </model>

  <joint>
    <name>pan</name>
    <!-- set the joint's rotational axis -->
    <axis>0 0 1</axis>
    <children>
      <!-- add a few children to the joint... -->
      <model>
        <file>dp-ptu-d46/middle.pbmf</file>
        <name>ptu_middle</name>
      </model>

      <joint>
        <name>tilt</name>
        <axis>0 1 0</axis>

        <transform>
          <!-- move the joint 9.11 cm along the Z-axis -->
          <translate>0 0 0.0911</translate>
        </transform>

        <children>
	      <model>
	        <file>dp-ptu-d46/top.pbmf</file>
	        <name>ptu_top</name>
          </model>
        </children>
      </joint>
    </children>
  </joint>
</scene>