Community:Science/Robotics/ComponentsFileFormat

The "simulation component" file format

This page is a proposal for a file format that represents a "simulation component".

A component is a simulated entity with an autonomous behaviour from the simulator perspective (ie, a component should be able to produce output or consume inputs by itself, without interaction with other components). Each component has an execution core, written as a Python script, and executed by the Blender GameEngine.

Examples of components include cameras, robot bodies, legs, ...

A component can output data (or use inputs) of different kind, according to its specification. For instance, a stereocamera component could output two video streams (image L and image R) or a single 3D depth map. Another example: a mobile robotic body could be controlled by sending speed commands for each motors or a global (theta, v) command.

Generic component file model

myRobot.tar.gz
    |
    |-mesh/--default/--myRobot.blend
    |      |
    |      |-hires/--myRobot_hires.blend
    |      |
    |      |-lowres/--myRobot_lowres.blend
    |
    |-myRobot.gen
    |
    |-codels/--codel1.py
    |        |
    |        |-codel2.py
    |        |    .
    |        |    .
    |        |    .
    |
    |-conf/--instance.conf.py
           |
           |-global.conf.py

A component is made of:

• One or several .blend file that contains geometrical and physical models (at possible different resolutions) of the component,
• A .gen file that describe in a formal way the inputs and outputs of the component, as well as the involved datatypes. The .gen file uses the Genom syntax, which rely on IDL to describe datatypes and allows to specify both "ports" (which are output streams of data, like a video stream) and "services" (ie RPC). See here for details on "what is done with the .gen file", and this page for a description of Genom syntax.)
• One or several so-called codels that implement the actual behaviour of the components, in Python, within Blender (for instance, make a mesh move, grab a camera image, etc.). These codels can as well call external C/C++ libraries if needed, as any Python application (one possible example: call an external noise generator). The .gen file describe how codels are links to ports and services. Usually, each service or port has one codel, but it can be more or less.
• Some configuration files that are actually Blender panels. In most cases, the "instance" configuration will be required. Sometimes, a "global" configuration (that sets parameters for all components of the same kind) can be needed as well.

An example: the GPS component

Example for a generic GPS sensor, that would have two data output streams: one is supposed without noise, one has a noise function applied on the output.

We create a gps.tar.gz file that is an gzipped archive with the following structure:

gps.tar.gz
    |
    |-mesh/--gps.blend
    |
    |-gps.gen
    |
    |-codels/--gps_raw.py
    |        |
    |        |-gps_noisy.py
    |
    |-conf/--instance.conf.py
           |
           |-global.conf.py

1. gps.blend: contains essentially the GPS mesh (ie, nothing or a simple cube)
2. gps.gen: describes dataypes (for instance, 2 floats: latitude and longitude) and the two ports, with or without noise.
3. gps_raw.py is a Python function that calculate a GPS-like position of the GPS mesh in the scene (relative to a geo-reference).
4. gps_noisy.py does the same and add some uncertainty to the position, based on a given noise function.
5. instance.conf.py contains the UI code (cf panels in Blender 2.5) to configure each single instance of a GPS sensor (for instance, the noise model we want to use or which stream is enabled).
6. global.conf.py contains the UI code to configure global parameters for this class of component. In the case of GPS, we need for instance to setup a geo-referenced frame (latitude, longitude) that would be used by each instance of GPS to compute their relative positions.

Associated workflow

As every "OpenRobots components" (available in a component repository), the GPS appears in Blender UI in the components library tree.

When you design a robot, you can drag and drop the GPS component on the main editor window to link it to the robot model you're building. When you drop it, it opens a new panel where you can configure this new instance of GPS (noise model, etc.).

Once it's done, you can save your robot (ie myRobot.blend).

When you later build the scene, you import your "myRobot.blend", and if (and only if) this model introduces the first GPS instance in the scene, the panel to configure the global parameters for the GPSs opens. You can setup a global frame of geo-reference.