README

Traffic Editor

A graphical editor for robot traffic flows. The intent is to make it easy to annotate building floorplans with the desired robot traffic lanes and generate simulation models to test and evaluate different traffic schemes.

Quality Declaration

This package claims to be in the Quality Level 3 category. See the Quality Declaration for more details.

System Requirements

This program is developed and tested on Ubuntu 18.04 LTS, using Qt 5 and yaml-cpp.

Compiling Instructions

Traffic Editor is now structured as a Colcon package. After installing ROS 2 Eloquent, the following command sequence will create a colcon workspace in ~/colcon_workspace and build traffic-editor there:

sudo apt update
sudo apt install libyaml-cpp-dev qt5-default \
  libopencv-dev libopencv-videoio-dev
mkdir -p ~/colcon_workspace/src
cd ~/colcon_workspace/src
git clone https://github.com/open-rmf/rmf_traffic_editor
cd ~/colcon_workspace
source /opt/ros/eloquent/setup.bash
colcon build --packages-select rmf_traffic_editor

The companion traffic_editor_assets package contains a nifty bunch of useful assets to use with rmf_traffic_editor. It is included in the above checkout.

Then you should be able to run traffic-editor by sourcing the install space of that workspace, in a new “clean” terminal:

source ~/colcon_workspace/install/setup.bash
traffic-editor

Quick Start

If it’s the first time you are running it, starting the editor with traffic-editor should bring up a blank window.

First, you’ll need to make sure that traffic-editor knows where the model thumbnails are found. If you installed traffic_editor_assets, rmf_traffic_editor should find it automatically. The thumbnails are top-view renderings of various art assets that can be added to the environments, such as chairs.

Click Edit->Preferences... and see if the path provided in the “Thumbnail Path” box looks reasonable.

If necessary, the “Find…” button can be used to browse the filesystem to point to any desired thumbnail directory.

(If you installed the recommended traffic_editor_assets package, you will find its thumbnail directory in its install space at <workspace_dir>/install/traffic_editor_assets/share/assets/thumbnails.)

Creating a new Project and an empty Building Map

Click Project->New... and save your new project as test.project.yaml

Click Edit->Project Properties... and enter “test” as the project name and test.building.yaml as the building path. Then click OK.

Click Edit->Building Properties... and enter “test” as the building name. Click OK.

Creating a level and adding some stuff

Click the “Add…” button in the “levels” tab on the far right side of the main editor window. This will pop up a dialog where you can create a new level. Enter L1 for the name and click OK. This will create a 10 meter square level.

You can zoom in and out using the mouse wheel on the rendering on the left side of the main window. You can pan around by dragging the mouse around with the mouse wheel (or middle button) depressed.

Now, you should be able to click the green dot toolbar icon, which is the “Add Vertex” tool (or press V) and click a few vertices in the white area. Press the [Escape] key to return to the “Select” tool.

Now, you should be able to click the add wall tool (or press W) and drag from one vertex to another vertex to add wall segments.

To delete wall segments or vertices, first press [Escape] to enter Select mode. Then, click on a wall segment or vertex, and press [Delete].

Save your work

Click Project->Save or press Ctrl+S to save the project and building map.

Adding real-world measurements to set the scale

To set the scale of the drawing, click the add measurement tool (or press M) and drag from one vertex to another to add a real-world measurement line, which should show up as a pink line. Then click the select tool (or press Esc) and click on the line with the left button. This should populate the property-editor in the lower-right pane of the editor window. You can then specify the real-world length of the measurement line in meters. If you set more than one measurement line on a drawing, the editor will compute an average value of pixels-per-meter from all supplied measurements.

Currently you need to re-load the document (closing the editor and re-opening) to re-compute the scale. This is not ideal, but is hopefully not a frequently-used feature. Typically the scale of a map is only set one time.

Adding lifts

Click the “Add…” button in the “lifts” tab on the far right side of the main editor window. This will pop up a dialog where you can create a new lift. You can specify the name, position, size, and reference floor in the dialog.

Note: Do include the keywork “lift” in the lift name as for now this is how slotcars recognize lift models.

You can add lift doors by lick the “Add…” button below the box showing the lift. Set Door type to “Double sliding” (The only supported type for now!), and align the doors to the edge of the lift (represented by the green box). After that, select which door you want to use on each floor by simply checking the boxes on the left.

Lift waypoints at the center of the lift on each level can also be generated using the “Add lift waypoints” button in the dialog. Note that waypoints will only be generated on levels that the lift is serving (has a door opening on that level).

Generating Custom Thumbnails

Model thumbnails are used in rmf_traffic_editor. To generate a thumbnail, a simple working example is shown here to generate a SUV:

# Run as gz plugin, set --a for help options printout
gzserver -s libthumbnail_generator.so empty.world --input ~/.gazebo/models/SUV/model.sdf --output .

After execution, you will notice a newly created SUV.png in your current working directory. This can be further placed into traffic_editor_assets/assets/thumbnails.

To generate multiple model thumbnails listed in model_list.yaml, run this:

export GAZEBO_MODEL_PATH=/PATH/TO/MODELS; ./scripts/generate_thumbnails.py /PATH/TO/MODELS test/model_list.yaml ~/output

User can also change the script default configs: img_size, cam_height and fhov, which will alter the meters_per_pixel value.

Similarly, the generated thumbnails in ~/output can then be added to traffic_editor_assets/assets/thumbnails, while also append model_list.yaml.

Utilities

A new model list .yaml file can be generated using the utility script, where an optional blacklisted model names can be added, to avoid creating moving models or agents,

# e.g. MODEL_DIR = '~/.gazebo/models'
./scripts/generate_model_list.py output_model_list.yaml -d MODEL_DIR -b test/model_blacklist.yaml

In the event that merging multiple model lists is required, a different utility script can be used,

./scripts/merge_model_lists.py output_model_list.yaml -s test/model_list.yaml

To sort the model list .yaml file,

./scripts/sort_model_list.py model_list.yaml