Home

Awesome

Grid Map

Overview

This is a C++ library with ROS interface to manage two-dimensional grid maps with multiple data layers. It is designed for mobile robotic mapping to store data such as elevation, variance, color, friction coefficient, foothold quality, surface normal, traversability etc. It is used in the Robot-Centric Elevation Mapping package designed for rough terrain navigation.

Features:

This is research code, expect that it changes often and any fitness for a particular purpose is disclaimed.

The source code is released under a BSD 3-Clause license.

Author: Péter Fankhauser<br /> Affiliation: ANYbotics<br /> Maintainer: Maximilian Wulf, mwulf@anybotics.com, Magnus Gärtner, mgaertner@anybotics.com<br /> With contributions by: Simone Arreghini, Tanja Baumann, Jeff Delmerico, Remo Diethelm, Perry Franklin, Magnus Gärtner, Ruben Grandia, Edo Jelavic, Dominic Jud, Ralph Kaestner, Philipp Krüsi, Alex Millane, Daniel Stonier, Elena Stumm, Martin Wermelinger, Christos Zalidis

This projected was initially developed at ETH Zurich (Autonomous Systems Lab & Robotic Systems Lab).

This work is conducted as part of ANYmal Research, a community to advance legged robotics.

Grid map example in RViz

Publications

If you use this work in an academic context, please cite the following publication:

P. Fankhauser and M. Hutter, "A Universal Grid Map Library: Implementation and Use Case for Rough Terrain Navigation", in Robot Operating System (ROS) – The Complete Reference (Volume 1), A. Koubaa (Ed.), Springer, 2016. (PDF)

@incollection{Fankhauser2016GridMapLibrary,
  author = {Fankhauser, P{\'{e}}ter and Hutter, Marco},
  booktitle = {Robot Operating System (ROS) – The Complete Reference (Volume 1)},
  title = {{A Universal Grid Map Library: Implementation and Use Case for Rough Terrain Navigation}},
  chapter = {5},
  editor = {Koubaa, Anis},
  publisher = {Springer},
  year = {2016},
  isbn = {978-3-319-26052-5},
  doi = {10.1007/978-3-319-26054-9{\_}5},
  url = {http://www.springer.com/de/book/9783319260525}
}

Documentation

An introduction to the grid map library including a tutorial is given in this book chapter.

The C++ API is documented here:

Installation

Installation from Packages

To install all packages from the grid map library as Debian packages use

sudo apt-get install ros-$ROS_DISTRO-grid-map

Building from Source

Dependencies

The grid_map_core package depends only on the linear algebra library Eigen.

sudo apt-get install libeigen3-dev

The other packages depend additionally on the ROS standard installation (roscpp, tf, filters, sensor_msgs, nav_msgs, and cv_bridge). Other format specific conversion packages (e.g. grid_map_cv, grid_map_pcl etc.) depend on packages described below in Packages Overview.

Building

To build from source, clone the latest version from this repository into your catkin workspace and compile the package using

cd catkin_ws/src
git clone https://github.com/anybotics/grid_map.git
cd ../
catkin_make

To maximize performance, make sure to build in Release mode. You can specify the build type by setting

catkin_make -DCMAKE_BUILD_TYPE=Release

Packages Overview

This repository consists of following packages:

Additional conversion packages:

Unit Tests

Run the unit tests with

catkin_make run_tests_grid_map_core run_tests_grid_map_ros

or

catkin build grid_map --no-deps --verbose --catkin-make-args run_tests

if you are using catkin tools.

Usage

Demonstrations

The grid_map_demos package contains several demonstration nodes. Use this code to verify your installation of the grid map packages and to get you started with your own usage of the library.

For more information about grid map filters, see grid_map_filters.

<img src="grid_map_core/doc/interpolationSineWorld.gif" width="256" height="252"> <img src="grid_map_core/doc/interpolationGaussWorld.gif" width="256" height="252">

The user can play with different worlds (surfaces) and different interpolation settings in the interpolation_demo.yaml file. The visualization displays the ground truth in green and yellow color. The interpolation result is shown in red and purple colors. Also, the demo computes maximal and average interpolation errors, as well as the average time required for a single interpolation query.

Grid map features four different interpolation methods (in order of increasing accuracy and increasing complexity):

For more details check the literature listed in CubicInterpolation.hpp file.

Conventions & Definitions

Grid map layers

Grid map conventions

Iterators

The grid map library contains various iterators for convenience.

Grid mapSubmapCircleLinePolygon
Grid map iteratorSubmap iteratorCircle iteratorLine iteratorPolygon iterator
EllipseSpiral
Ellipse iteratorSpiral iterator

Using the iterator in a for loop is common. For example, iterate over the entire grid map with the GridMapIterator with

for (grid_map::GridMapIterator iterator(map); !iterator.isPastEnd(); ++iterator) {
    cout << "The value at index " << (*iterator).transpose() << " is " << map.at("layer", *iterator) << endl;
}

The other grid map iterators follow the same form. You can find more examples on how to use the different iterators in the iterators_demo node.

Note: For maximum efficiency when using iterators, it is recommended to locally store direct access to the data layers of the grid map with grid_map::Matrix& data = map["layer"] outside the for loop:

grid_map::Matrix& data = map["layer"];
for (GridMapIterator iterator(map); !iterator.isPastEnd(); ++iterator) {
    const Index index(*iterator);
    cout << "The value at index " << index.transpose() << " is " << data(index(0), index(1)) << endl;
}

You can find a benchmarking of the performance of the iterators in the iterator_benchmark node of the grid_map_demos package which can be run with

rosrun grid_map_demos iterator_benchmark

Beware that while iterators are convenient, it is often the cleanest and most efficient to make use of the built-in Eigen methods. Here are some examples:

Changing the Position of the Map

There are two different methods to change the position of the map:

Packages

grid_map_rviz_plugin

This RViz plugin visualizes a grid map layer as 3d surface plot (height map). A separate layer can be chosen as layer for the color information.

Grid map visualization in RViz

grid_map_sdf

This package provides an efficient algorithm to convert an elevation map into a dense 3D signed distance field. Each point in the 3D grid contains the distance to the closest point in the map together with the gradient.

ANYmal SDF demo

grid_map_visualization

This node subscribes to a topic of type grid_map_msgs/GridMap and publishes messages that can be visualized in RViz. The published topics of the visualizer can be fully configure with a YAML parameter file. Any number of visualizations with different parameters can be added. An example is here for the configuration file of the tutorial_demo.

Point cloudVectorsOccupancy gridGrid cells
Point cloudVectorsOccupancy gridGrid cells

Parameters

Subscribed Topics

Published Topics

The published topics are configured with the YAML parameter file. Possible topics are:

Note: Color values are in RGB form as concatenated integers (for each channel value 0-255). The values can be generated like this as an example for the color green (red: 0, green: 255, blue: 0).

grid_map_filters

The grid_map_filters package containts several filters which can be applied a grid map to perform computations on the data in the layers. The grid map filters are based on ROS Filters, which means that a chain of filters can be configured as a YAML file. Furthermore, additional filters can be written and made available through the ROS plugin mechanism, such as the InpaintFilter from the grid_map_cv package.

Several basic filters are provided in the grid_map_filters package:

Additionally, the grid_map_cv package provides the following filters:

Build Status

Devel Job Status

KineticMelodicNoetic
grid_mapBuild StatusBuild StatusBuild Status
docBuild StatusBuild StatusBuild Status

Release Job Status

KineticMelodicNoetic
grid_mapBuild StatusBuild StatusBuild Status
grid_map_coreBuild StatusBuild StatusBuild Status
grid_map_costmap_2dBuild StatusBuild StatusBuild Status
grid_map_cvBuild StatusBuild StatusBuild Status
grid_map_demosBuild StatusBuild StatusBuild Status
grid_map_filtersBuild StatusBuild StatusBuild Status
grid_map_loaderBuild StatusBuild StatusBuild Status
grid_map_msgsBuild StatusBuild StatusBuild Status
grid_map_octomapBuild StatusBuild StatusBuild Status
grid_map_pclBuild StatusBuild StatusBuild Status
grid_map_rosBuild StatusBuild StatusBuild Status
grid_map_rviz_pluginBuild StatusBuild StatusBuild Status
grid_map_sdfBuild StatusBuild StatusBuild Status
grid_map_visualizationBuild StatusBuild StatusBuild Status

Bugs & Feature Requests

Please report bugs and request features using the Issue Tracker.