Map Registration Tutorial

Introduction

This tutorial is meant to show how to use the map registration application. For more information on how it works, please see the page detailing the theory, or if you are feeling brave, browse the code

This tutorial covers all features as of 8755415. Some screenshots are from older versions.

Running

map_registration is a ROS-less python package. To run, simply change into its directory and type:

cd <directory of map_registration>
python demo.py <location of semantic map image> <location of SLAM yaml file>

For more information on dependencies, see this page

The Interface

On the left is the provided semantic map. Here, it is a simple outline of our lab. On the right is the SLAM map generated by the robot. This SLAM map was generated in our lab using a Turtlebot. Both these image previews are zoomable. Scrolling with the mouse wheel will zoom in. Use the scrollbars on the side to pan the image.

The far right is the tools panel. Here you have tool relating to the transformation and zones. The buttons here will let you import and export your transformation and preview it with a draggable 'robot'

Defining a Transformation

The transformation between the maps is represented by a set of affine transformations on a triangular mesh. This mesh is a triangulation of matched points, supplied by the user.

Adding and Deleting Points

To match a point, simply left click on either map. A colored square will appear where you clicked.

You may right-click a point to delete it. You can also delete unmatched points or clear all points using the buttons in the tools panel.

Points may be imported from a previous run. Click the "Load Points" button and browse to the location of the map registration. Open the map registration (a directory ending in .mreg) and find the file called "registration.yaml". This file contains all the information needed to load points onto the map.

Matching Points

The points are matched according to the order they are clicked, so the first point you click in the semantic map corresponds to the first point you click in the slam map. The color indicates which points correspond. Once three or more points have been set in both maps, a transformation may be defined and the three buttons on the top of the tools panel will enable.

Here is a fully registered map.

Previewing the Transformation

There are two ways of previewing the transformation. When you click the "Preview" button in the tools panel, a new window will appear. This will disappear when any key is pressed. This shows the slam map transformed into the shape of the semantic map.

the other way is by dragging a virtual robot through either map. You must click "Preview Transform" or "Export" in order to enable the "Show Robot" checkbox. Click "Show Robot" and a blue square will appear in the top left corner of the semantic map. You may drag it around and it will show up in the corresponding location in the slam map. If you are not satisfied with the transformation, simply add more points and click "Preview Transform" or "Export" again. If the robot goes into an area where it does not have transformation information, it will not update the position in the other map.

Exporting

While running, map registration will create temporary files in a folder called register/ in the working directory. Clicking the "Export" button will save these in a better location. It will open a file dialog and prompt for a Map Registration File (*.mreg). Browse to the location you want it to save and type the name. This will create a directory with the specified name and the map registration extension. Inside this folder is everything needed to transform between maps. For a complete description of the output, see here

Dealing with Zones

Zones from the privacy_zones package may be imported into the application. To do this, go to the "Zones" tab on the tools panel. Click "Import Zones". A dialogue will appear where you can select the correct yaml file. The "File Preview" box will populate with the information from that file. The "Show Zones" checkbox will also become enabled.

Clicking the "Show Zones" checkbox will show the zones defined with the zone tool both in the semantic and slam maps. If the transformation is not defined for any zone corner, the zones will not be drawn in the SLAM map. The zones are color-coded according to their privacy specification. Green corresponds to public areas, red to private, and grey to unspecified. Clicking the export button will open a dialogue window where you may choose the location to save the new zones file. This file is the same as the original zones file but gives the points in relation to the map frame (in the real world).