Skip to content

World Creation Tutorial

Jump to bottom
Angela Maio edited this page Mar 3, 2021 · 33 revisions

This tutorial explains how to create an underground world using the SubT Simulator's graphical interface and few shell scripts.

If you have a point cloud of an environment that you'd like to use in simulation, then please take a look at this tutorial for converting a point cloud to a mesh.

A SubT Challenge world has three main components:

  • An SDF file (world.sdf), which is an XML file that Ignition uses to load assets.
  • A graphviz dot file (world.dot), which describes the connectivity of the environment.
  • A visibility dat file (world.dat), which describes the communication model of the environment.

All three files must be present for the SubT Simulator to simulate the world.

Requirements

In order to maximize compatibility, it is necessary for the SDF world to follow certain guidelines.

  • The staging area must be located at the world origin, which may require offsetting the remainder of the world tiles. The base station and artifact origin fiducial should be placed based on the staging area at the origin.
    <!-- The staging area -->
    <include>
      <static>true</static>
      <name>staging_area</name>
      <pose>0 0 0 0 0 0</pose>
      <uri>https://fuel.ignitionrobotics.org/1.0/openrobotics/models/Cave Starting Area Type B</uri>
    </include>

    <!-- The base station -->
    <include>
      <static>true</static>
      <name>base_station</name>
      <pose>-8 0 0 0 0 -1.5708</pose>
      <uri>https://fuel.ignitionrobotics.org/1.0/openrobotics/models/Base Station</uri>
    </include>

    <!-- Fiducial marking the origin for artifacts reports -->
    <include>
      <name>artifact_origin</name>
      <pose>10.0 0.0 0.0 0 0 0</pose>
      <uri>https://fuel.ignitionrobotics.org/1.0/openrobotics/models/Fiducial</uri>
    </include>
  • The world name in the .sdf file should match the filename.
  • World tiles follow the naming convention tile_N, starting at index 1.
  • World tile caps follow the naming convention cap_N, starting at index 1.

Generating the .sdf file

Familiarize yourself with the graphical interface by reading up on the various options and plugins. Experimentation is also highly encouraged.

You can start creating a world from scratch by running ign gazebo -v 4, and then inserting models from the SubT Tech Repo. Click on a model you'd like to insert and use the drag to simulator button on the model's detail page. More information about model insertion can be found here.

Alternatively, you can launch an existing world and make modifications. Try launching a simple cave world to get started, such as ign launch competition.ign worldName:=simple_cave_01 circuit:=cave. Use the model manipulation tools to alter the configuration of the cave.

When you are happy with your world, use the hamburger button in the upper left to access the "Save World" option. Save your world into your catkin workspace in the subt/subt_ign/worlds directory. World files in this directory will be automatically installed when catkin_make install is run.

Artifacts

Up to 20 artifacts can be placed in a world, and these artifacts can be inserted directly from the SubT Tech Repo. Artifacts include:

  1. Common artifacts
    1. Survivor
    2. Cell phone
    3. Backpack
  2. Tunnel Circuit artifacts
    1. Drill
    2. Fire Extinguisher
  3. Urban Circuit artifacts
    1. Gas
    2. Vent
  4. Cave Circuit artifacts
    1. Helmet
    2. Rope
  5. Finals artifact
    1. To Be Announced

Refer to the artifact specification guide for more information about artifacts and their usage.

The name of each artifact in your world must follow a specific scheme to facilitate scoring.

<artifact-type>_<artifact-number>

The set of <artifact-type> names are: rescue_randy, phone, backpack, drill, extinguisher, gas, vent, helmet, and rope. The <artifact-number> field should start from 1.

For example, the first rope artifact would have a model name of rope_1.

Take a look at existing worlds for more examples. Once your artifacts are correctly named in the .sdf file, the Artifact Validator Tool can locate and visualize them.

Dynamic obstacles

Obstacles that move in response to a nearby robot can also be placed in virtual worlds. See how to add falling rocks to a world.

Generating the .dot file

The first step is to generate the connectivity data for the .sdf file.

This is accomplished by using the included dot_generator tool:

source ~/subt_ws/install/setup.bash
rosrun subt_ign dot_generator ~/subt_ws/src/subt/subt_ign/worlds/my_new_world.sdf

The corresponding connections will be output to the console, where they can be visually inspected and then copied into a corresponding .dot file. The output can also be redirected to write the .dot file directly via:

source ~/subt_ws/install/setup.bash
rosrun subt_ign dot_generator ~/subt_ws/src/subt/subt_ign/worlds/my_new_world.sdf > \
                              ~/subt_ws/src/subt/subt_ign/worlds/my_new_world.dot

Verifying the .dot file

In the world, each tile should either be connected to an adjacent tile, or have a cap placed on it. Tile connectivity can be verified by utilizing the Connections Validator Tool. Tile connectivity can also be verified without starting the simulator by using:

  cd ~/subt_ws/
  source ~/subt_ws/install/setup.bash

  # Run a non-GUI version of the connection validator
  ./install/bin/validate_connections my_new_world_without_sdf_extension

For example:

./install/bin/validate_connections simple_cave_01

If there are any issues in the world, they will be reported as follows:

[ConnectionValidatorPrivate.cc:105] Parsing [/home/developer/subt_ws/install/share/subt_ign/worlds/my_new_world.sdf]
[Dbg] [ConnectionValidatorPrivate.cc:127] Parsing [/home/developer/subt_ws/install/share/subt_ign/worlds/my_new_world.dot]
[Wrn] [ConnectionHelper.cc:289] Failed to connect: Cave 4 Way 01 Type A Cave U Turn 01 Type A
[Wrn] [ConnectionHelper.cc:289] Failed to connect: Cave 4 Way 01 Type A Cave 3 Way 01 Type A
[Wrn] [ConnectionHelper.cc:289] Failed to connect: Cave 4 Way 01 Type A Cave Corner 02 Type A
[Dbg] [ConnectionValidatorPrivate.cc:315] Populated 64/67
[Dbg] [ConnectionValidatorPrivate.cc:340] tile_21 1/2 (Cave U Turn 01 Type A)
[Dbg] [ConnectionValidatorPrivate.cc:340] tile_22 2/3 (Cave 3 Way 01 Type A)
[Dbg] [ConnectionValidatorPrivate.cc:340] tile_28 1/2 (Cave Corner 02 Type A)
[Dbg] [ConnectionValidatorPrivate.cc:332] Found cap!
[Dbg] [ConnectionValidatorPrivate.cc:340] tile_5 0/4 (Cave 4 Way 01 Type A)
[Dbg] [ConnectionValidatorPrivate.cc:332] Found cap!
[Dbg] [ConnectionValidatorPrivate.cc:332] Found cap!

In the above example, we can see several tiles that have failed to connect, along with the corresponding types and number of valid connections. These need to be resolved before we can move forward in the generation process.

In general, these errors will appear in the cases where:

  1. There is a tile that is not connected to anything.
  2. There is a tile that is incorrectly rotated, so it no longer makes connection.
  3. There is a failure to account for elevation change between tiles.
  4. There are tile connection points that do not have caps on them.

This process may be iterative and require adjusting the .sdf and .dot files and inspecting the results with both the command line and GUI applications until the world is corrected.

Generating the .dat file

Once the .sdf and .dot files are generated with correct connectivity, the visibility tables can be generated.

This is accomplished by utilizing the visibility.ign launch file:

ign launch visibility.ign worldName:=my_new_world

The visibility table may take several minutes to generate, so grab a warm beverage.

Once it is completed, find the output .dat file in ~/subt_ws/install/share/subt_ign/worlds/ and move it to ~/subt_ws/src/subt/subt_ign/worlds/.

The results may also be verified by following the Breadcrumbs and communication visualization tutorial.

Generating levels

In order to improve simulator performance in large worlds, it may be necessary to generate levels, which allow parts of the environment to be loaded and unloaded based on the location of the robots. This is accomplished via a separate generation stage, which adds levels to the .sdf file:

  cd ~/subt_ws/
  source ~/subt_ws/install/setup.bash
  ./devel/lib/subt_ign/level_generator \
      ~/subt_ws/src/subt/subt_ign/worlds/my_new_world.sdf \
      50 50 50 10 \
      ~/subt_ws/src/subt/subt_ign/worlds/my_new_world.sdf

The arguments to the level generator define the size in x, y, z of the level bounding boxes, as well as the size of the buffer for loading and unloading levels. These may vary based on the size of the environment and the size of the tiles used. The size of the level bounding boxes can be determined by running ign launch visibility.ign circuit:=<circuit> worldName=:=<world name>. This will print out the maximum tile dimensions in each axis right before generating the visibility look-up table. An example print out is shown below:

...
149.382 -199.683 24.4377
tile_51
149.762 -225 26.6893
149.76 -225 26.6893
rescue_randy_4
150.081 -237.067 20.9826
150.081 -237.067 20.3586
cave_cap_4
150 -240.767 24.3113
150 -240.767 24.3113
Max tile dimensions: X = 34.6114 (tile_4) Y = 55.0512 (tile_4) Z = 44.6752 (tile_3)

The values labeled Max tile dimensions can be rounded up and used as the parameters to the level_generator. You can check out the other worlds in ~/subt_ws/src/subt/subt_ign/worlds for examples.

Launching the new world

Now, to launch your world, you only have to rebuild your workspace and launch it using the worldName argument:

  cd ~/subt_ws/
  catkin_make install
  source ~/subt_ws/install/setup.bash
  ign launch -v 4 competition.ign worldName:=my_new_world circuit:=circuit_name

Now you can test your autonomous robots in a custom underground world!

Using the Cave World Generator

The subt repo contains a world_generator_cave tool for auto generation of cave worlds by constructing the environment from a collection of prefab world sections and select individual Cave Type A and Type B tiles.

Here are the command line options:

Usage: world_generator_cave [options]
Options:
    -h		 Print this help message
    -o <file>	 Output sdf filename
    -s <seed>	 Seed
    -c <count>	 Min tile count
    -n <name>	 World name
    -t <type>	 Cave Type:
             	    'anastomotic' or 'a',
             	    'curvilinear' or 'c',
             	    'rectilinear' or 'r'
    -g		 Generate sdf with GUI plugin

You can generate a different world by setting a different seed value and minimum tile count. There are 3 cave types:

  1. anastomotic: creates a world using Type A tiles
  2. rectilinear: creates a world using Type B tiles
  3. curvilinear: creates a world using Type A and Type B tiles

The optional -g arg that lets users generate a world sdf with GUI plugin, which is useful for viewing the world in ign-gazebo without launching the whole subt stack. Leave out the -g arg when generating the final world.

Example usage:

./install/share/subt_ign/world_generator_cave -g -t a -c 60 -n cave_test -s 25 -o cave_test.sdf

The above command generates an anastomotic cave world called cave_test with a minimum of 60 tiles using a seed value of 25 and saves the output to cave_test.sdf.

If you do not have the Cave Type A and Type B tiles in your Fuel cache (~/.ignition/fuel/fuel.ignitionrobotics.org/OpenRobotics/models/), the tool will go and download them from Fuel as it needs to compute bounding box info for these tiles in order to do intersection checks.

To view the generated world in ign-gazebo, run:

ign gazebo -v 4 cave_test.sdf

World Creation Checklist

Your custom world should be complete as long as you have completed these steps.

  • Place tiles or use the procedural generator
  • Place artifact origin and base station models
  • Place artifact models
  • Verify artifact locations using the Artifact Validator Tool
  • Place obstacles and obstacle triggers
  • Verify obstacle triggers by moving robots in/out of the activation region
  • Generate connectivity .dot file
  • Verify connectivity using the Connections Validator Tool
  • Generate communications .dat file
  • Verify communications by visualizing communication range
  • Generate levels to improve performance
Clone this wiki locally