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:

• Multi-layered: Developed for universal 2.5-dimensional grid mapping with support for any number of layers.
• Efficient map re-positioning: Data storage is implemented as two-dimensional circular buffer. This allows for non-destructive shifting of the map's position (e.g. to follow the robot) without copying data in memory.
• Based on Eigen: Grid map data is stored as [Eigen] data types. Users can apply available Eigen algorithms directly to the map data for versatile and efficient data manipulation.
• Convenience functions: Several helper methods allow for convenient and memory safe cell data access. For example, iterator functions for rectangular, circular, polygonal regions and lines are implemented.
• ROS interface: Grid maps can be directly converted to and from ROS message types such as PointCloud2, OccupancyGrid, GridCells, and our custom GridMap message. Conversion packages provide compatibility with [costmap_2d], [PCL], and [OctoMap] data types.
• OpenCV interface: Grid maps can be seamlessly converted from and to [OpenCV] image types to make use of the tools provided by [OpenCV].
• Visualizations: The grid_map_rviz_plugin renders grid maps as 3d surface plots (height maps) in [RViz]. Additionally, the grid_map_visualization package helps to visualize grid maps as point clouds, occupancy grids, grid cells etc.
• Filters: The grid_map_filters provides are range of filters to process grid maps as a sequence of filters. Parsing of mathematical expressions allows to flexibly setup powerful computations such as thresholding, normal vectors, smoothening, variance, inpainting, and matrix kernel convolutions.

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

Affiliation: ANYbotics

Maintainer: Maximilian Wulf, mwulf@anybotics.com

** 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.

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: * grid_map_core * grid_map_ros * grid_map_costmap_2d * grid_map_cv * grid_map_filters * grid_map_octomap * grid_map_pcl

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:

• grid_map is the meta-package for the grid map library.
• grid_map_core implements the algorithms of the grid map library. It provides the GridMap class and several helper classes such as the iterators. This package is implemented without [ROS] dependencies.
• grid_map_ros is the main package for [ROS] dependent projects using the grid map library. It provides the interfaces to convert grid maps from and to several [ROS] message types.
• grid_map_demos contains several nodes for demonstration purposes.
• grid_map_filters builds on the [ROS Filters] package to process grid maps as a sequence of filters.
• grid_map_msgs holds the [ROS] message and service definitions around the [grid_map_msg/GridMap] message type.
• grid_map_rviz_plugin is an [RViz] plugin to visualize grid maps as 3d surface plots (height maps).
• grid_map_visualization contains a node written to convert GridMap messages to other [ROS] message types for example for visualization in [RViz].

Additional conversion packages:

• grid_map_costmap_2d provides conversions of grid maps from [costmap_2d] map types.
• grid_map_cv provides conversions of grid maps from and to [OpenCV] image types.
• grid_map_octomap provides conversions of grid maps from OctoMap ([OctoMap]) maps.
• grid_map_pcl provides conversions of grid maps from Point Cloud Library (PCL) polygon meshes and point clouds. For details, see the grid map pcl package README.

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.

• simple_demo demonstrates a simple example for using the grid map library. This ROS node creates a grid map, adds data to it, and publishes it. To see the result in RViz, execute the command

  roslaunch grid_map_demos simple_demo.launch
  

• tutorial_demo is an extended demonstration of the library's functionalities. Launch the tutorial_demo with

  roslaunch grid_map_demos tutorial_demo.launch
  

• iterators_demo showcases the usage of the grid map iterators. Launch it with

  roslaunch grid_map_demos iterators_demo.launch
  

• image_to_gridmap_demo demonstrates how to convert data from an image to a grid map. Start the demonstration with

  roslaunch grid_map_demos image_to_gridmap_demo.launch
  

  

• grid_map_to_image_demo demonstrates how to save a grid map layer to an image. Start the demonstration with

  rosrun grid_map_demos grid_map_to_image_demo _grid_map_topic:=/grid_map _file:=/home/$USER/Desktop/grid_map_image.png
  

• opencv_demo demonstrates map manipulations with help of [OpenCV] functions. Start the demonstration with

  roslaunch grid_map_demos opencv_demo.launch
  

  

• resolution_change_demo shows how the resolution of a grid map can be changed with help of the [OpenCV] image scaling methods. The see the results, use

  roslaunch grid_map_demos resolution_change_demo.launch
  

• filters_demo uses a chain of [ROS Filters] to process a grid map. Starting from the elevation of a terrain map, the demo uses several filters to show how to compute surface normals, use inpainting to fill holes, smoothen/blur the map, and use math expressions to detect edges, compute roughness and traversability. The filter chain setup is configured in the filters_demo_filter_chain.yaml file. Launch the demo with

  roslaunch grid_map_demos filters_demo.launch
  

  

For more information about grid map filters, see grid_map_filters.

• interpolation_demo shows the result of different interpolation methods on the resulting surface. The start the demo, use

  roslaunch grid_map_demos interpolation_demo.launch
  

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): * NN - Nearest Neighbour (fastest, but least accurate). * Linear - Linear interpolation. * Cubic convolution - Piecewise cubic interpolation. Implemented using the cubic convolution algorithm. * Cubic - Cubic interpolation (slowest, but most accurate).

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

Conventions & Definitions

Iterators

The grid map library contains various iterators for convenience.

Grid map	Submap	Circle	Line	Polygon
Ellipse	Spiral

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:

gri