Skip to content

World Creation Tutorial

Jump to bottom
Angela Maio edited this page Jun 30, 2023 · 33 revisions

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

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

There are several ways to generate a world .sdf:

Building a World in Ignition Gazebo

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. You can reference the Virtual Tile Compatibility Matrix to help choose tiles that fit together.

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

  • Note if you launch a more complex world that has levels, you will need to pass the levels:=false argument to see all the tiles in the world, e.g. ign launch -v 4 competition.ign worldName:=finals_practice_01 circuit:=finals levels:=false

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.

Using the World Generator

The subt repo contains a set of tools for auto generation of tunnel and cave worlds by constructing the environment from a collection of prefab world sections and select individual tiles.

Here are the command line options for the cave_generator:

Usage: cave_generator [world_type] [options]
Example Generate: cave_generator -g -t a -c 60 -n cave_test -s 25 -o cave_test.sdf
Example Debug: cave_generator -g -d "Cave Split Type A" -n cave_split_type_a -o cave_split_type_a.sdf
Options:
    -h		 Print this help message
    -d <tile>	 Generate a world with a single tile for debugging or unit tests
    -o <file>	 Output sdf filename
    -t <type>	 Cave Type:
             	    'anastomotic' or 'a',
             	    'curvilinear' or 'c',
             	    'rectilinear' or 'r'
    -s <seed>	 Seed
    -c <count>	 Min tile count
    -n <name>	 World name
    -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

When creating a tunnel world, you can use the tunnel_generator with the same arguments, except the tunnel subdomain consists only of 1 tile type and omits the -t flag.

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/lib/subt_ign/cave_generator -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

Creating New Tiles

The SubT Tech Repo has a number of readily available tile models for you to create a world. However, if you would like to use your own tile mesh, you can follow this tutorial for converting the mesh that you created to a model in Ignition and and uploading that model to Ignition Fuel.

Here are some guidelines to follow:

  • The origin of the tile should be at the bottom center of the mesh.
  • The tiles do not all need to have the same dimensions but it is recommended to set a base tile size, e.g. 10m, and have the x, y, and z lengths of the tile be multiples of this value.
  • To connect a tile to another, the tile should have at least one opening, which we refer to as a connection point. The connection points should be located at the center of the four sides of the tile boundary, see below for illustration of a tile bounding box from a top-down view (x-y plane). They should not be at the corners of the tile. 
    ----- c -----
|           |
c     o     c
|           |
----- c -----
c - connection point, and o - tile origin

Once you have the connection point, note down their position offset from the center of the model. You will then need to add your new tile and connection points to the ConnectionHelper's list of connectionPoints and connectionTypes. This will be used by our connection validator, dot generator, and world generator tools.

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. Cube

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.

  • You may notice a few Unrecognized model type[...] msgs, e.g. [BaseStation], [Fiducial], and names of artifacts. Warning messages for these model types are safe to ignore as they are not a "tile" with valid connection points in the world and do not need to be included to the connectivity file (one exception is the Base Station, and the dot_generator has special logic to add this in the 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/lib/subt_ign/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 -v 4 visibility.ign worldName:=my_new_world

The visibility table may take anywhere from several minutes to a couple of hours to generate depending on the size of the world, so grab a warm beverage and take a break.

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!

Launch file configurations

There are a few configurations that you can tune in the launch file. You can take a look at the competition.ign launch file and modify as needed.

  • Robot spawn pose offset: By default the the staging area is at the origin of the world facing +x direction. If you decide to use a custom staging area model that is different from the ones in the existing circuits, you may have to update the robots' spawn pose offsets. Recall that up to a max of 20 robots can be spawned, which are spaced at 2m apart in 4 rows and 5 columns. The offset refers to the center of this spawn region.

  • Communication model parameters: Each launch file should have a CommsBrokerPlugin that controls the radio propagation behavior that affects communication between robots and when a robot reports artifacts for scoring. See the Communication Model tutorial for more information on how it works. One of the key parameters that you may need to change if you are using your own custom tiles is the <comms_cost_max> parameter. There is a cost associated with propagating radio signal from one tile to another. The more complex the tile is (i.e. turns and intersections), the cost of traversing to and from this tile type is higher: The tile traversal costs are:

      Straight tile -> Straight tile : 1
  Straight tile -> Turn tile     : 3
  Turn tile     -> Turn tile     : 6

    So if your world is composed of a large number of small tiles, you will likely need to increase the comms_cost_max value.

Now you are ready to run robots through your world! Consider sharing your world on Fuel so others can test their robots against it too!

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