PF mapping utility (pmap_test)

The pmap_test utility demonstrates the basic functionality of the pmap library and serves a handy mapping utility in its own right. Given a Player logfile containing odometry and laser data, pmap_test will produce an occupancy grid map of the environment.

pmap_test screenshot

Note that there are two distinct phases to the mapping process. In the first or coarse phase, data is read from a Player logfile and processed through the lodo and pmap libraries to produce a rough map. In the second or fine phase, this map is refined using the rmap library. The stopping conditions for the second phase are entirely arbitrary (the quality of the map will improve asymptotically over time). This phase can be quite time consuming, so please be patient.

Usage

Basic usage is as follows:

$ pmap_test [options] <logfilename>

where the supported options are:

• -g : disable the GUI (run in console mode only).
• --range_max : maximum effective range for the laser (m).
• --position_index : index of odometry device in logfile (e.g., 0 for device position:0).
• --laser_index : index of laser device in logfile.
• --num_samples : number of samples in particle filter.
• --resample_interval : number of scans between resampling steps.
• --resample_sigma : width of resampling gaussian.
• --num_cycles : number of optimization cycles in the fine phase.
• --robot_x, --robot_y, --robot_rot : initial robot pose.
• --grid_width, --grid_height : grid dimensions (m).
• --grid_scale : grid scale (m/cell).

Keyboard/mouse controls

The pmap_test utility has a simple GLUT-based GUI for monitoring and controlling the map generation process. The following keyboard/mouse controls are supported:

• Left-mouse drag: pan map in window.
• T : show/hide sample trajectories.
• G : show/hide the current best map.
• +/- : zoom in/out.
• S : single step through the logfile.
• SPACE : pause/unpause logfile playback.
• W : save the current best map.
• Control-C : save the current best map and exit.

Note that hiding the sample trajectories and current best map can result in significant speed-ups on some GLUT implementations. The entire GUI can be disabled using the -g option on the command line.

Tips for generating logfiles

The key principle to remember when generating maps is: garbage in, garbage out. Here are some tips for generating good data sets:

• The laser must be firmly afixed (i.e., bolted) to the robot; gaffer tape and velcro will simply not cut it for this application. Ideally, the laser will be mounted and aligned such that it coincides with the the nominal odometric "center" of the robot. If the laser is offset or oriented, the relative pose of the laser must be supplied to the program (see Usage).

• For SICK LMS200 lasers, the laser must be set to 1 degree, 10 mm, 10Hz mode. In this mode, the laser generates 181 range readings per scan, and can theoretically detect obstacles out to 80m. "Do not" use the default 0.5 degree mode, as this is really two 1 degree scans that have been interlaced and offet by 0.5 degrees (this produces horrible artifacts and provids no additional data).

• The rotational speed of the robot should be limited to less than 30 degree/sec; rapid turns are more likely to cause scan mis-alignment.

• When exploring, recover the gross toplogy of the environment first; i.e., traverse the major corridors and intersections before exploring rooms. Loops should be closed with a significant overlap (e.g., travel at least one-and-a-quarter times around the loop).

Tips for generating maps

The pmap_test utility is generally used in a iterative fashion to find the best settings for the map generation process.

• To check the validity of the data set, run pmap_test with the number of particles set to one:

  $ pmap_test --num_samples 1 <logfile>
  

  The map produced by this test should be locally correct (i.e., no individually mis-aligned scans), but globaly inconsistent (i.e., exhibiting cummulative drift).

• Based on the result of first test, set the size of the desired map and re-run with a larger sample set; e.g.:

  $ pmap_test --num_samples 100 --grid_width 50 --grid_height 25 <logfile>
  

  This command specifies a map that is 50 by 25 m in size. The initial robot pose within the map can also be specified (see Usage). If the map contains gross topological errors, try re-running with more samples (but be careful not to exceed the available physical memory; things will get very, very slow if you do).

• The program can also be run in console mode (no GUI) for faster mapping and/or batch processing.

  $ pmap_test -g --num_samples 500 --grid_width 50 --grid_height 25 <logfile>
  

---