Anatomy of a ‘.world’ file

As Sphinx heavily relies on Gazebo, it accepts as argument a path to a .world file. So, to launch a Sphinx simulation on an existing world, you can type:

$ sphinx <path/to/my.world> <path/to/my.drone>

The .world file comprises directly or indirectly the elements of the scene. It complies with the specification provided by sdformat.org (here). Let’s take an example and go through it into details. This documentation does not aim to be exhaustive, but rather describes the most interesting aspects from the drone simulation perspective.

<?xml version="1.0"?>
<sdf version="1.5">
  <world name="default">
    <gui>
      <camera name="user_camera">
        <pose>-8.89 -14.33 12.97 0.0 0.58 0.84</pose>
        <track_visual>
          <static>true</static>
          <use_model_frame>true</use_model_frame>
          <xyz>-3 0 1</xyz>
          <inherit_yaw>true</inherit_yaw>
        </track_visual>
      </camera>
    </gui>

    <spherical_coordinates>
      <latitude_deg>48.878922</latitude_deg>
      <longitude_deg>2.367782</longitude_deg>
    </spherical_coordinates>

    <physics type="ode">
      <real_time_update_rate>1000</real_time_update_rate>
      <max_step_size>0.001</max_step_size>
      <real_time_factor>1.0</real_time_factor>
      <max_contacts>20</max_contacts>
      <gravity>0 0 -9.81</gravity>
      <magnetic_field>0.1062e-6 20.8038e-6 -43.2881e-6</magnetic_field>
      <ode>
        <solver>
          <type>world</type>
          <min_step_size>0.0001</min_step_size>
          <iters>50</iters>
          <precon_iters>0</precon_iters>
          <sor>1.4</sor>
          <use_dynamic_moi_rescaling>1</use_dynamic_moi_rescaling>
        </solver>
        <constraints>
          <cfm>0</cfm>
          <erp>0.2</erp>
          <contact_max_correcting_vel>100.0</contact_max_correcting_vel>
          <contact_surface_layer>0.001</contact_surface_layer>
        </constraints>
      </ode>
    </physics>

    <atmosphere type="adiabatic">
      <temperature>298.15</temperature>
      <pressure>101325</pressure>
      <temperature_gradient>-0.0065</temperature_gradient>
    </atmosphere>

    <plugin name="fwman" filename="libsphinx_fwman.so">
      <spawn_point name="default">
        <pose>0 0 0.2 0 0 0</pose>
      </spawn_point>
      <spawn_point name="5_meters_forward">
        <pose>5 0 0.2 0 0 0</pose>
      </spawn_point>
    </plugin>

    <include>
      <uri>model://sun</uri>
    </include>
    <include>
      <uri>model://grass_plane</uri>
    </include>

  </world>
</sdf>

The code explained

Each world file is encapsulated by a <world> tag.

<?xml version="1.0"?>
<sdf version="1.5">
  <world name="default">

The optional <gui> tag sets the GUI parameters used by sphinx-client.

<gui>
  <camera name="user_camera">

The initial pose of the user camera is given by the line below. All so-called poses are expressed as [x, y, z, phi, theta, psi] in meters for distances and radians for angles.

<pose>-8.89 -14.33 12.97 0.0 0.58 0.84</pose>

The <track_visual> tag can be used to track a drone from startup with the user camera by adding a <name> tag set with the drone name.

    <track_visual>
      <static>true</static>
      <use_model_frame>true</use_model_frame>
      <xyz>-3 0 1</xyz>
      <inherit_yaw>true</inherit_yaw>
    </track_visual>
  </camera>
</gui>

These GPS coordinates correspond to the point [0 0 0] of the scene. By default, we use the Parrot Headquarter coordinates.

<spherical_coordinates>
  <latitude_deg>48.878922</latitude_deg>
  <longitude_deg>2.367782</longitude_deg>
</spherical_coordinates>

The magnetic field was calculated using the 2015 World Magnetic Model for the geodetic coordinates defined in <spherical_coordinates>.

<physics type="ode">
  <real_time_update_rate>1000</real_time_update_rate>
  <max_step_size>0.001</max_step_size>
  <real_time_factor>1.0</real_time_factor>
  <max_contacts>20</max_contacts>
  <gravity>0 0 -9.81</gravity>
  <magnetic_field>0.1062e-6 20.8038e-6 -43.2881e-6</magnetic_field>

ODE is the physics engine used by Gazebo. The values below are suited for a drone simulation. Change them at your own risk!

  <ode>
    <solver>
      <type>world</type>
      <min_step_size>0.0001</min_step_size>
      <iters>50</iters>
      <precon_iters>0</precon_iters>
      <sor>1.4</sor>
      <use_dynamic_moi_rescaling>1</use_dynamic_moi_rescaling>
    </solver>
    <constraints>
      <cfm>0</cfm>
      <erp>0.2</erp>
      <contact_max_correcting_vel>100.0</contact_max_correcting_vel>
      <contact_surface_layer>0.001</contact_surface_layer>
    </constraints>
  </ode>
</physics>

The <atmosphere> tag specifies the type and properties of the atmosphere model. The adiabatic atmosphere model is based on the troposphere model in the Manual of the ICAO Standard Atmosphere. This model assumes a specific composition of gases, the ideal gas law, hydrostatic equilibrium, and constant gradients of gravity and temperature with respect to altitude.

<atmosphere type="adiabatic">
  <temperature>298.15</temperature>
  <pressure>101325</pressure>
  <temperature_gradient>-0.0065</temperature_gradient>
</atmosphere>

The <plugin> fwman controls the drones’ lifecycle. It may contain a list of spawn points which describe a starting pose in world coordinates for the drones.

<plugin name="fwman" filename="libsphinx_fwman.so">
  <spawn_point name="default">
    <pose>0 0 0.2 0 0 0</pose>
  </spawn_point>
  <spawn_point name="5_meters_forward">
    <pose>5 0 0.2 0 0 0</pose>
  </spawn_point>
</plugin>

By default, all drones start at the “default” location. To start at a different location, one would have to specify the name of the spawn point in the command line:

$ sphinx <path/to/my.world> <path/to/my.drone>::pose=5_meters_forward

All the other objects belonging to the scene are listed below.

    <include>
      <uri>model://sun</uri>
    </include>
    <include>
      <uri>model://grass_plane</uri>
    </include>

  </world>
</sdf>

How to spaw drones into the world

It is recommended to spawn drones into the world by giving a .drone file (Anatomy of a ‘.drone’ file) on the command line:

$ sphinx <path/to/my.world> <path/to/my.drone>

Another way to spawn drones into the world is to insert an optional gazebo <plugin> fwman in your .world file. It may contain one or more <drone> tags whose content obey the same rules as <drone> tags in .drone files. Below is a working example:

<world>
...
<plugin name="fwman" filename="libsphinx_fwman.so">
  <drone
    name="bebop2"
    firmware="http://plf.parrot.com/sphinx/firmwares/ardrone3/milos_pc/latest/images/ardrone3-milos_pc.ext2.zip"
    hardware="milosboard">
    <sdf_params
      low_gpu="false"
      with_front_cam="true" />
    <interface>eth1</interface>
    <stolen_bdaddr>00:00:00:00:00:00</stolen_bdaddr>
  </drone>
  <spawn_point name="default">
    <pose>0 0 0.2 0 0 0</pose>
  </spawn_point>
</plugin>
...
</world>

For more information about the properties used in <drone>, see Anatomy of a ‘.drone’ file.