autoware.universe

# 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](https://github.com/anybotics/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](LICENSE). **Author: Péter Fankhauser<br /> Affiliation: [ANYbotics](https://www.anybotics.com/)<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.](https://www.anymal-research.org/)  ## 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](http://www.researchgate.net/publication/284415855)) @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](http://www.researchgate.net/publication/284415855). The C++ API is documented here: * [grid_map_core](http://docs.ros.org/kinetic/api/grid_map_core/html/index.html) * [grid_map_ros](http://docs.ros.org/kinetic/api/grid_map_ros/html/index.html) * [grid_map_costmap_2d](http://docs.ros.org/kinetic/api/grid_map_costmap_2d/html/index.html) * [grid_map_cv](http://docs.ros.org/kinetic/api/grid_map_cv/html/index.html) * [grid_map_filters](http://docs.ros.org/kinetic/api/grid_map_filters/html/index.html) * [grid_map_octomap](http://docs.ros.org/kinetic/api/grid_map_octomap/html/index.html) * [grid_map_pcl](http://docs.ros.org/kinetic/api/grid_map_pcl/html/index.html) ## 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_sdf*** provides an algorithm to convert an elevation map into a 3D signed distance field. * ***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](http://pointclouds.org/)) polygon meshes and point clouds. For details, see the grid map pcl package [README](grid_map_pcl/README.md). ### 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](http://catkin-tools.readthedocs.org/). ## Usage ### Demonstrations The *grid_map_demos* package contains several demonstration nodes. Use this code to verify your installation of the grid map packages a