smurf

SMURF

SMURF stands for Supplementable, Mostly Universal Robot Format and extends the information incoorporated by an URDF.

It defines a hierarchy of files given in YAML format. A basic smurf file at least contains the robot URDF, but can hold additional information about physic engine parameters, collisions, motors, controllers and any parameter the user wants to define.

# main SMURF file of model "iiwa_7"
# created with Phobos 0.7 - https://github.com/rock-simulation/phobos

SMURF version: 0.7
modelname: iiwa_7
date: '20180403_12:02'
files:
- ../urdf/iiwa_7.urdf
- iiwa_7_materials.yml
- iiwa_7_motors.yml
- iiwa_7_dynamics.yml

Within these individual files, e.g. visual materials, information is given as a dict like structure.

#materials definition SMURF file for "iiwa_7", 20180403_12:02

materials:
- ambientColor:
    b: 0.00309
    g: 0.19179
    r: 0.8
  diffuseColor:
    b: 0.00309
    g: 0.19179
    r: 0.8

SMURF Scenes

Phobos is developed to be able to export robot models in the SMURF format. SMURF can however only store a single robot, but its principle of hierarchically combining files can be extended to describe scenes. Enter SMURF scenes (or SMURFS), a scene format building on the definition of SMURF by grouping objects in a scene as entities.

Such entities can be anything from a heightmap representing the ground to a light source or a SMURF-defined robot. Thus, SMURF scenes allow to use existing SMURF models and combine them in a scene by defining a position and orientation for each model, as well as an anchor, specifying where and how a model is "anchored" (it could be fixed to the world or free to move around), and a pose defining the configuration of the joints of a model (see Poses).

SMURF Scenes structure

As mentioned above, SMURF scenes consist of a list of entities, the data of which is - as most of SMURF itself (the only exception being the URDF file) - encoded in YAML format. The smallest example we can create has a list with just one element:

entities:
  - name: Eve
    file: myrobot.smurf

This minimalist entry for our robot called "Eve" contains its name and the URI of its SMURF file. SMURFs allow to parse the type of an entity from the file extension of the file, but it is generally clearer to state it explicitly:

entities:
  - name: Eve
    file: myrobot.smurf
    type: smurf

Adding a second robot based on the same SMURF in one scene is easy since entities are distinguished by name:

entities:
  - name: Eve
    file: myrobot.smurf
    type: smurf
  - name: Adam
    file: myrobot.smurf
    type: smurf

Placing Entities

There is a problem with the above scene containing Adam and Eve: they will both be created at the global origin. Biblical references aside, this is not very practical. We should therefore get some distance between the two models:

entities:
  - name: Eve
    type: smurf
    file: myrobot.smurf
    position: [5.0, 0, -0.8]    # [x, y, z]
    rotation: [1.5, 20.0, 0.0]  # euler angles: [x, y, z]
  - name: Adam
    type: smurf
    file: myrobot.smurf
    position: [-2.0, 3.5, 0]
    rotation: [0.7071, 0.0, -0.7071, 0.0]  # quaternion [w, x, y, z]

While position is always noted as a list of three floats, rotation can be provided as either Euler angles or a rotation quaternion.

Anchoring Entities

Our two robots have been free to move around in our simulated world so far (though admittedly, there is no ground for them to move around yet). Sometimes models of a robot or other entities are supposed to be static, or, "anchored to the world":

   entities:
     - name: Eve
       type: smurf
       file: myrobot.smurf
       position: [5.0, 0, -0.8]    # [x, y, z]
       rotation: [1.5, 20.0, 0.0]  # euler angles: [x, y, z]
     - name: Adam
       type: smurf
       file: myrobot.smurf
       position: [-2.0, 3.5, 0]
       rotation: [0.7071, 0.0, -0.7071, 0.0]  # quaternion [w, x, y, z]
     - name: Lazy Bob
       file: lazybot.smurf
       anchor: world

This anchor: world statement should lead to the root link of the underlying URDF model being statically anchored in the defined position and orientation, while all joints of the anchored model will maintain mobility.

Anchoring a robot in place can be useful for debugging a model in simulation, as it will not be affected by forces caused by internal collisions or similar simulation errors. It's also the best way to anchor robots such as manipulator arms to a platform or wall. But since the borders between robots and non-robot-machines are fuzzy, it also allows to build stationary machinery of your simulation environment in the SMURF format, for instance doors, levers or traffic lights, which may not move with respect to the world, but may still have moving parts or sensors. Even fully static elements of the environment such as houses or trees can be represented in SMURF and anchored in the simulation.

Editing Scenes in Phobos

We are currently working on fully integrating SMURF scenes in the Phobos workflow. Phobos 0.7 currently allows to specify a custom property called anchor with a value world in the root link of a robot, resulting in anchoring a robot to the world. Placement of entities in a scene is also supported as long as each entity is a valid SMURF model.

We want to greatly improve this functionality in the near future.

Related To Do's

Code

Wiki

• Add additional information about the usage in MARS
• Add examples how Phobos parses information into SMURF