wiki:Plugins/amcl
Last modified 6 years ago Last modified on 17.09.2012 18:09:10

Adaptive Monte Carlo Localization (AMCL)

This plugin implements Adaptive Monte Carlo Localization (AMCL) based on "Probabilistic Robotics" by Thrun, Burgard, and Fox. It essentially wraps a plugin interface around an AMCL library ported from the ROS AMCL package and originating from the Player amcl driver. It assumes a grid map and one or more laser scans, and odometry updates as input. The Fawkes plugin currently can only pass a single laser scan at the moment, which most often suffices.

The map is usually generated once before running amcl, for example "by hand", e.g. drawing a map according to an existing plan of the building or measurements, or automated for example using CARMEN. A number of configuration parameters can be tuned to balance accuracy and computational demands as well as convergence behavior or to cope with differing sensor or odometry precision.

At run-time, laser scans and odometry are frequently passed to AMCL. The odometry is used as motion model to update and move the localization samples (see the book), the laser is used to weigh hypotheses and make the algorithm converge to ideally a single position. Two modes of initialization of the positions are possible: uniform resampling, which randomly samples the free space with a uniform distribution, or a gaussian reset, where samples are drawn with a gaussian distribution around a specified starting position.

Currently, the most convenient way to initialize the localization is to run Fawkes with the amcl plugin and the ROS integration. Then ROS' rviz can be used to set an initial position. Another very convenient way is to set a known starting position in the configuration. Once AMCL is started a gaussian reset is done at the specified position.

There are some performance improvements that disable updating the filter unless certain configurable conditions are met. These are a positional and angular odometry thresholds and a certain time after a motion. The latter is a specific improvement in the Fawkes amcl plugin (and not available in the ROS package). It is particularly useful to improve convergence on platforms with small computational resources.

Requires

Config Values

Besides the configuration values listed above, certain transformations must exist. In particular, there must be a transform from the laser sensor to the base frame. More information about the configuration values can also be found on the ROS amcl page.

PathTypeDescriptionDefaultR
/plugins/amcl/map_filestringImage file containing the map, must be a PNG file and a path relative to the config dirmap.png*
/plugins/amcl/resolutionfloatResolution of the map; meters per pixel 0.05*
/plugins/amcl/origin_xfloatThe X coordinate of the 2-D pose of the lower-left pixel in the map, as (x, y, yaw), with yaw as counterclockwise rotation (yaw=0 means no rotation) around Z axis. Many parts of the system currently ignore yaw.; m0.0*
/plugins/amcl/origin_yfloatThe Y coordinate of the 2-D pose of the lower-left pixel in the map, as (x, y, yaw), with yaw as counterclockwise rotation (yaw=0 means no rotation) around Z axis. Many parts of the system currently ignore yaw.; m0.0*
/plugins/amcl/origin_thetafloatThe yaw of the 2-D pose of the lower-left pixel in the map, as (x, y, yaw), with yaw as counterclockwise rotation (yaw=0 means no rotation) around Z axis. Many parts of the system currently ignore yaw.; rad0.0*
/plugins/amcl/occupied_thresholdfloatPixels with occupancy probability greater than this threshold are considered completely occupied. Occupancy probability is the luminance value divided by 255.0.65*
/plugins/amcl/free_thresholdfloatPixels with occupancy probability less than this threshold are considered completely free.0.2*
/plugins/amcl/save_pose_ratefloatSave Pose Rate0.5*
/plugins/amcl/laser_min_rangefloatLaser Minimum Range0.01*
/plugins/amcl/laser_max_rangefloatLaser Maximum Range5.6*
/plugins/amcl/max_beamsunsigned intLaser Maximum Beams30*
/plugins/amcl/min_particlesunsigned intMinimum Particles100*
/plugins/amcl/max_particlesunsigned intMaximum Particles2000*
/plugins/amcl/kld_errfloatPf error0.01*
/plugins/amcl/kld_zfloatPf Z Value0.99*
/plugins/amcl/alpha1floatOdometry model parameter, specifies the expected noise in odometrys rotation estimate from the rotational component of the robots motion.0.2*
/plugins/amcl/alpha2floatOdometry model parameter, specifies the expected noise in odometrys rotation estimate from translational component of the robots motion. 0.2*
/plugins/amcl/alpha3floatOdometry model parameter, specifies the expected noise in odometrys translation estimate from the translational component of the robots motion.0.2*
/plugins/amcl/alpha4floatOdometry model parameter, pecifies the expected noise in odometrys translation estimate from the rotational component of the robots motion.0.2*
/plugins/amcl/alpha5floatOdometry model parameter, Translation-related noise parameter (only used if model is "omni")0.2*
/plugins/amcl/z_hitfloatZ Hit0.95*
/plugins/amcl/z_shortfloatZ Short0.1*
/plugins/amcl/z_maxfloatZ Max0.05*
/plugins/amcl/z_randfloatZ Rand0.05*
/plugins/amcl/sigma_hitfloatSigma Hit0.2*
/plugins/amcl/lambda_shortfloatLambda Short0.1*
/plugins/amcl/laser_likelihood_max_distfloatLikelihood Maximum Laser Distance2.0*
/plugins/amcl/laser_interface_idstringLaser interface IDLaser urg filtered*
/plugins/amcl/pose_interface_idstringPose interface IDPose*
/plugins/amcl/laser_model_typestringLaser Model type, either beam or likelihood_fieldlikelihood_field*
/plugins/amcl/odom_model_typestringOdometry Model type - diff or omniomni*
/plugins/amcl/d_threshfloatUpdate minimum D Thresh; m0.2*
/plugins/amcl/a_threshfloatUpdate minimum A Thresh; rad0.5*
/plugins/amcl/t_threshfloatTime to keep updating after stopping; sec3.0*
/plugins/amcl/odom_frame_idstringOdometry Frame ID/odom*
/plugins/amcl/base_frame_idstringBase Frame ID/base_link*
/plugins/amcl/global_frame_idstringGlobal Frame ID/map*
/plugins/amcl/laser_frame_idstringLaser Frame ID/base_laser*
/plugins/amcl/resample_intervalunsigned intResample Interval1*
/plugins/amcl/transform_tolerancefloatTransform Tolerance; sec2.0*
/plugins/amcl/alpha_slowfloatAlpha Slow Recovery0.0*
/plugins/amcl/alpha_fastfloatAlpha Fast Recovery0.0*
/plugins/amcl/init_pose_xfloatInitial Position x0.0*
/plugins/amcl/init_pose_yfloatInitial Position y0.0*
/plugins/amcl/init_pose_afloatInitial Position yaw0.0*
/plugins/amcl/angle_incrementfloatAngle increment between two rays in degree1.0*

Provides

BlackBoard Interfaces

  • Position3DInterface::Pose: Position of the robot in global frame coordinates.

Transforms

  • Provides a transform from the global to the odometry frame (usually /map to /odom) in such a way that the base frame (usually /base_link) position is at the correct position in the global frame.

Requirements

BlackBoard Interfaces

  • Laser360Interface::<Laser Interface ID>: Input laser data, the interface ID is read from the config file.

Transforms

  • Laser frame to base frame: position of laser relative to base frame (e.g. /base_link to /base_laser)
  • Odometry to base frame: position of base frame relative to odometry frame (e.g. /odom to /base_link)

Usage Instructions

First prepare a map of the environment to localize in. Start with a small map, preferably hand-made, with a resolution of 0.05cm. Then configure your static transforms, laser, and possibly laser-filter. Set a valid initial position in the configuration and make sure that all static and dynamic transforms are properly published, in particular the laser transform and odometry. It is best to setup the ROS integration and visualize the environment using rviz. Add visualizations for the map, the laser scan, and the pose array. Once the plugin is loaded (and configured at the proper position), you should quickly see the localization converge at the given point. By default it will stop updating after three seconds unless moving. As long as the odometry is properly updated moving the robot should still have the correct position in the map.

More documentation on mapping and usage needs to be written.