SMURF Scenes

SMURF scenes (.smurfs) are one step up on the hierarchical letter compared to SMURF files (.smurf) themselves. They allow you to arrange multiple SMURFs in a scene, i.e. placing SMURFs and other entities in an absolute coordinate system and with defined constraints (effectively defining a joint to the world). Phobos allows you to arrange such scenes in Blender and then export them directly, including export of all individual SMURFs if required.

Entities

SMURF scenes are made from simulation entities. Entities are very vaguely defined in MARS, but generally represent some form of unit of simulation objects. A single robot defined in SMURF is loaded as an entity. A house, a fence or a tree could each be individual entities placed in a scene, but could also be combined to one "environment" entity. It is essentially up to the user to define the set of entities in a scene which make the most sense in a specific use case. A general rule is that any independently moving simulation object (or group of objects) should be its own entity.

The best way to create entities in MARS is via EntityFactories. It is possible to create a MARS plugin which creates a number of objects in simulation and combines them to create a new entity "off the record". However, if the same type of entity is consistently (re-)used, an EntityFactory should be created. The EntityFactoryInterface allows a plugin to register an entity type in the EntityFactoryManager, which allows the SMURF loader to pass the data for a specific entity to the respective factory class.

Graph of how it works

SMURF scenes

SMURF scenes are defined in YAML format. Here is an example:

# an example SMURF scene file

entities:
    - name: SpaceClimber
      file: spaceclimber/SpaceClimber.smurf
      position: [0, 0, 0]
      orientation: [0, 0, 0, 1]
    - name: rst_1
      file: environment/random_stepping_field_1.yml
      position: [1, 0, 0]
      orientation: [1, 0, 0, 0]
      type: random_stepping_field

Each entity has at least one parameter: name. If additionally, position and orientation are provided, the entity is placed at the respective position, otherwise it is placed at the global origin. Additional parameters can be specified in a separate file; in the case of a SMURF, this would be the SMURF file, in case of another entity class, it would most likely be the YAML file containing its defining parameters. Furthermore, a definition of each entity's type is required, so the EntityFactoryManager knows which EntityFactory to feed the data. If the type can be derived from the file extension of a provided file, the type parameter does not have to be provided, however the type interpreted from the file extension is overwritten if it is provided nonetheless.