Need help with grid_map?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

1.2K Stars 505 Forks BSD 3-Clause "New" or "Revised" License 743 Commits 75 Opened issues


Universal grid map library for mobile robotic mapping

Services available


Need anything else?

Contributors list

Grid Map


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.


  • 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 gridmaprviz_plugin renders grid maps as 3d surface plots (height maps) in RViz. Additionally, the gridmapvisualization package helps to visualize grid maps as point clouds, occupancy grids, grid cells etc.
  • Filters: The gridmapfilters 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, [email protected]
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


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)

  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 = {}


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

The C++ API is documented here: * gridmapcore * gridmapros * gridmapcostmap_2d * gridmapcv * gridmapfilters * gridmapoctomap * gridmappcl


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


The gridmapcore 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. gridmapcv, gridmappcl etc.) depend on packages described below in Packages Overview.


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
cd ../

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.
  • gridmapcore implements the algorithms of the grid map library. It provides the
    class and several helper classes such as the iterators. This package is implemented without ROS dependencies.
  • gridmapros 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.
  • gridmapdemos contains several nodes for demonstration purposes.
  • gridmapfilters builds on the ROS Filters package to process grid maps as a sequence of filters.
  • gridmapmsgs holds the ROS message and service definitions around the [gridmapmsg/GridMap] message type.
  • gridmaprviz_plugin is an RViz plugin to visualize grid maps as 3d surface plots (height maps).
  • gridmapvisualization contains a node written to convert GridMap messages to other ROS message types for example for visualization in RViz.

Additional conversion packages:

  • gridmapcostmap_2d provides conversions of grid maps from costmap_2d map types.
  • gridmapcv provides conversions of grid maps from and to OpenCV image types.
  • gridmapoctomap provides conversions of grid maps from OctoMap (OctoMap) maps.
  • gridmappcl 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


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

if you are using catkin tools.



The gridmapdemos 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
  • imagetogridmap_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

    Image to grid map demo result

  • gridmaptoimagedemo 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

    OpenCV demo result

  • resolutionchangedemo 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

    file. Launch the demo with

    roslaunch grid_map_demos filters_demo.launch

    Filters demo results

For more information about grid map filters, see gridmapfilters.

  • 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

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


Conventions & Definitions

Grid map layers

Grid map conventions


The grid map library contains various iterators for convenience.

Grid map

Submap Circle Line Polygon
Grid map iterator Submap iterator Circle iterator Line iterator Polygon iterator
Ellipse Spiral
Ellipse iterator Spiral iterator

Using the iterator in a

loop is common. For example, iterate over the entire grid map with the
for (grid_map::GridMapIterator iterator(map); !iterator.isPastEnd(); ++iterator) {
    cout << "The value at index " << (*iterator).transpose() << " is " <<"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
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

node of the
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:

  • Setting a constant value to all cells of a layer:

  • Adding two layers:

    map["sum"] = map["layer_1"] + map["layer_2"];
  • Scaling a layer:

    map["layer"] = 2.0 * map["layer"];
  • Max. values between two layers:

    map["max"] = map["layer_1"].cwiseMax(map["layer_2"]);
  • Compute the root mean squared error:

    map.add("error", (map.get("layer_1") - map.get("layer_2")).cwiseAbs());
    unsigned int nCells = map.getSize().prod();
    double rootMeanSquaredError = sqrt((map["error"].array().pow(2).sum()) / nCells);

Changing the Position of the Map

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

: Changes the position of the map without changing data stored in the map. This changes the corresponce between the data and the map frame. *
: Relocates the grid map such that the corresponce between data and the map frame does not change. Data in the overlapping region before and after the position change remains stored. Data that falls outside of the map at its new position is discarded. Cells that cover previously unknown regions are emptied (set to nan). The data storage is implemented as two-dimensional circular buffer to minimize computational effort.

Grid map iterator Submap iterator



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


This node subscribes to a topic of type gridmapmsgs/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 cloud

Vectors Occupancy grid Grid cells
Point cloud Vectors Occupancy grid Grid cells


  • grid_map_topic
    (string, default: "/grid_map")

    The name of the grid map topic to be visualized. See below for the description of the visualizers.

Subscribed Topics

Published Topics

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

  • point_cloud

    Shows the grid map as a point cloud. Select which layer to transform as points with the

    name: elevation
    type: point_cloud
     layer: elevation
     flat: false # optional
  • flat_point_cloud

    Shows the grid map as a "flat" point cloud, i.e. with all points at the same height z. This is convenient to visualize 2d maps or images (or even video streams) in RViz with help of its

    Color Transformer
    . The parameter
    determines the desired z-position of the flat point cloud.
    name: flat_grid
    type: flat_point_cloud
     height: 0.0

    Note: In order to omit points in the flat point cloud from empty/invalid cells, specify the layers which should be checked for validity with

  • vectors

    Visualizes vector data of the grid map as visual markers. Specify the layers which hold the x-, y-, and z-components of the vectors with the

    parameter. The parameter
    defines the layer to be used as start point of the vectors.
    name: surface_normals
    type: vectors
     layer_prefix: normal_
     position_layer: elevation
     scale: 0.06
     line_width: 0.005
     color: 15600153 # red
  • occupancy_grid

    Visualizes a layer of the grid map as occupancy grid. Specify the layer to be visualized with the

    parameter, and the upper and lower bound with
    name: traversability_grid
    type: occupancy_grid
     layer: traversability
     data_min: -0.15
     data_max: 0.15
  • grid_cells

    Visualizes a layer of the grid map as grid cells. Specify the layer to be visualized with the

    parameter, and the upper and lower bounds with
    name: elevation_cells
    type: grid_cells
     layer: elevation
     lower_threshold: -0.08 # optional, default: -inf
     upper_threshold: 0.08 # optional, default: inf
  • region

    Shows the boundary of the grid map.

    name: map_region
    type: map_region
     color: 3289650
     line_width: 0.003

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


The gridmapfilters 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

from the


Several basic filters are provided in the gridmapfilters package:

  • gridMapFilters/ThresholdFilter

    Set values in the output layer to a specified value if the condition_layer is exceeding either the upper or lower threshold (only one threshold at a time).

    name: lower_threshold
    type: gridMapFilters/ThresholdFilter
      condition_layer: layer_name
      output_layer: layer_name
      lower_threshold: 0.0 # alternative: upper_threshold
      set_to: 0.0 # # Other uses: .nan, .inf
  • gridMapFilters/MeanInRadiusFilter

    Compute for each cell of a layer the mean value inside a radius.

    name: mean_in_radius
    type: gridMapFilters/MeanInRadiusFilter
      input_layer: input
      output_layer: output
      radius: 0.06 # in m.
  • gridMapFilters/MedianFillFilter

    Compute for each NaN cell of a layer the median (of finites) inside a patch with radius. Optionally, apply median calculations for values that are already finite, the patch radius for these points is given by existingvalueradius. Note that the fill computation is only performed if the fill_mask is valid for that point.

    name: median
    type: gridMapFilters/MedianFillFilter
      input_layer: input
      output_layer: output
      fill_hole_radius: 0.11 # in m. 
      filter_existing_values: false # Default is false. If enabled it also does a median computation for existing values. 
      existing_value_radius: 0.2 # in m. Note that this option only has an effect if filter_existing_values is set true. 
      fill_mask_layer: fill_mask # A layer that is used to compute which areas to fill. If not present in the input it is automatically computed. 
      debug: false # If enabled, the additional debug_infill_mask_layer is published. 
      debug_infill_mask_layer: infill_mask # Layer used to visualize the intermediate, sparse-outlier removed fill mask. Only published if debug is enabled.
  • gridMapFilters/NormalVectorsFilter

    Compute the normal vectors of a layer in a map.

    name: surface_normals
    type: gridMapFilters/NormalVectorsFilter
      input_layer: input
      output_layers_prefix: normal_vectors_
      radius: 0.05
      normal_vector_positive_axis: z
  • gridMapFilters/NormalColorMapFilter

    Compute a new color layer based on normal vectors layers.

    name: surface_normals
    type: gridMapFilters/NormalColorMapFilter
      input_layers_prefix: normal_vectors_
      output_layer: normal_color
  • gridMapFilters/MathExpressionFilter

    Parse and evaluate a mathematical matrix expression with layers of a grid map. See EigenLab for the documentation of the expressions.

    name: math_expression
    type: gridMapFilters/MathExpressionFilter
      output_layer: output
      expression: acos(normal_vectors_z) # Slope.
      # expression: abs(elevation - elevation_smooth) # Surface roughness.
      # expression: 0.5 * (1.0 - (slope / 0.6)) + 0.5 * (1.0 - (roughness / 0.1)) # Weighted and normalized sum.
  • gridMapFilters/SlidingWindowMathExpressionFilter

    Parse and evaluate a mathematical matrix expression within a sliding window on a layer of a grid map. See EigenLab for the documentation of the expressions.

    name: math_expression
    type: gridMapFilters/SlidingWindowMathExpressionFilter
      input_layer: input
      output_layer: output
      expression: meanOfFinites(input) # Box blur
      # expression: sqrt(sumOfFinites(square(input - meanOfFinites(input))) ./ numberOfFinites(input)) # Standard deviation
      # expression: 'sumOfFinites([0,-1,0;-1,5,-1;0,-1,0].*elevation_inpainted)' # Sharpen with kernel matrix
      compute_empty_cells: true
      edge_handling: crop # options: inside, crop, empty, mean
      window_size: 5 # in number of cells (optional, default: 3), make sure to make this compatible with the kernel matrix
      # window_length: 0.05 # instead of window_size, in m
  • gridMapFilters/DuplicationFilter

    Duplicate a layer of a grid map.

    name: duplicate
    type: gridMapFilters/DuplicationFilter
      input_layer: input
      output_layer: output
  • gridMapFilters/DeletionFilter

    Delete layers from a grid map.

    name: delete
    type: gridMapFilters/DeletionFilter
      layers: [color, score] # List of layers.

Additionally, the gridmapcv package provides the following filters:

  • gridMapCv/InpaintFilter

    Use OpenCV to inpaint/fill holes in a layer.

    name: inpaint
    type: gridMapCv/InpaintFilter
      input_layer: input
      output_layer: output
      radius: 0.05 # in m

Build Status

Devel Job Status

| | Kinetic | Melodic | Noetic | | --- | --- | --- | --- | | gridmap | [Build Status]( | [Build Status]( | [Build Status]( | | doc | Build Status | Build Status | Build Status |

Release Job Status

| | Kinetic | Melodic | Noetic | | --- | --- | --- | --- | | gridmap | [Build Status]( | [Build Status]( | [Build Status]( | | gridmapcore | Build Status | Build Status | Build Status | | gridmapcostmap2d | [Build Status]( | [Build Status]( | [Build Status]( | | gridmapcv | Build Status | Build Status | Build Status | | gridmapdemos | Build Status | Build Status | Build Status | | gridmapfilters | Build Status | Build Status | Build Status | | gridmaploader | Build Status | Build Status | Build Status | | gridmapmsgs | Build Status | Build Status | Build Status | | gridmapoctomap | Build Status | Build Status | Build Status | | gridmappcl | Build Status | Build Status | Build Status | | gridmapros | Build Status | Build Status | Build Status | | gridmaprvizplugin | [Build Status]( | [Build Status]( | [Build Status]( | | gridmapsdf | Build Status | Build Status | Build Status | | gridmapvisualization | Build Status | Build Status | Build Status |

Bugs & Feature Requests

Please report bugs and request features using the Issue Tracker.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.