Class GridMap

Class Documentation

class GridMap

Grid map managing multiple overlaying maps holding float values. Data structure implemented as two-dimensional circular buffer so map can be moved efficiently.

Data is defined with string keys. Examples are:

  • ”elevation”

  • ”variance”

  • ”color”

  • ”quality”

  • ”surface_normal_x”, “surface_normal_y”, “surface_normal_z” etc.

Public Types

typedef grid_map::DataType DataType
typedef grid_map::Matrix Matrix

Public Functions

explicit GridMap(const std::vector<std::string> &layers)

Constructor.

Parameters:

layers – a vector of strings containing the definition/description of the data layer.

GridMap()

Emtpy constructor.

GridMap(const GridMap&) = default

Default copy assign and copy constructors.

GridMap &operator=(const GridMap&) = default
GridMap(GridMap&&) = default
GridMap &operator=(GridMap&&) = default
virtual ~GridMap() = default

Destructor.

void setGeometry(const Length &length, const double resolution, const Position &position = Position::Zero())

Set the geometry of the grid map. Clears all the data.

Parameters:

  • length – the side lengths in x, and y-direction of the grid map [m].

  • resolution – the cell size in [m/cell].

  • position – the 2d position of the grid map in the grid map frame [m].

void setGeometry(const SubmapGeometry &geometry)

Set the geometry of the grid map from submap geometry information.

Parameters:

geometry – the submap geometry information.

void add(const std::string &layer, const double value = NAN)

Add a new empty data layer.

Parameters:

layer – the name of the layer. @value value the value to initialize the cells with.

void add(const std::string &layer, const Matrix &data)

Add a new data layer (if the layer already exists, overwrite its data, otherwise add layer and data).

Parameters:

  • layer – the name of the layer.

  • data – the data to be added.

bool exists(const std::string &layer) const

Checks if data layer exists.

Parameters:

layer – the name of the layer.

Returns:

true if layer exists, false otherwise.

const Matrix &get(const std::string &layer) const

Returns the grid map data for a layer as matrix.

Parameters:

layer – the name of the layer to be returned.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

grid map data as matrix.

Matrix &get(const std::string &layer)

Returns the grid map data for a layer as non-const. Use this method with care!

Parameters:

layer – the name of the layer to be returned.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

grid map data.

const Matrix &operator[](const std::string &layer) const

Returns the grid map data for a layer as matrix.

Parameters:

layer – the name of the layer to be returned.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

grid map data as matrix.

Matrix &operator[](const std::string &layer)

Returns the grid map data for a layer as non-const. Use this method with care!

Parameters:

layer – the name of the layer to be returned.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

grid map data.

bool erase(const std::string &layer)

Removes a layer from the grid map.

Parameters:

layer – the name of the layer to be removed.

Returns:

true if successful.

const std::vector<std::string> &getLayers() const

Gets the names of the layers.

Returns:

the names of the layers.

void setBasicLayers(const std::vector<std::string> &basicLayers)

Set the basic layers that need to be valid for a cell to be considered as valid. Also, the basic layers are set to NAN when clearing the cells with clearBasic(). By default the list of basic layers is empty.

Parameters:

basicLayers – the list of layers that are the basic layers of the map.

const std::vector<std::string> &getBasicLayers() const

Gets the names of the basic layers.

Returns:

the names of the basic layers.

bool hasBasicLayers() const

True if basic layers are defined.

Returns:

true if basic layers are defined, false otherwise.

bool hasSameLayers(const grid_map::GridMap &other) const

Checks if another grid map contains the same layers as this grid map. The other grid map could contain more layers than the checked ones. Does not check the selection of basic layers.

Parameters:

other – the other grid map.

Returns:

true if the other grid map has the same layers, false otherwise.

float &atPosition(const std::string &layer, const Position &position)

Get cell data at requested position.

Parameters:

  • layer – the name of the layer to be accessed.

  • position – the requested position.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

the data of the cell.

float atPosition(const std::string &layer, const Position &position, InterpolationMethods interpolationMethod = InterpolationMethods::INTER_NEAREST) const

Get cell data at requested position. Const version form above.

Parameters:

  • layer – the name of the layer to be accessed.

  • position – the requested position.

Throws:

  • std::out_of_range – if no map layer with name layer is present.

  • std::runtime_error – if the specified interpolation method is not implemented.

Returns:

the data of the cell.

float &at(const std::string &layer, const Index &index)

Get cell data for requested index.

Parameters:

  • layer – the name of the layer to be accessed.

  • index – the requested index.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

the data of the cell.

float at(const std::string &layer, const Index &index) const

Get cell data for requested index. Const version form above.

Parameters:

  • layer – the name of the layer to be accessed.

  • index – the requested index.

Throws:

std::out_of_range – if no map layer with name layer is present.

Returns:

the data of the cell.

bool getIndex(const Position &position, Index &index) const

Gets the corresponding cell index for a position.

Parameters:

  • position – [in] the requested position.

  • index – [out] the corresponding index.

Returns:

true if successful, false if position outside of map.

bool getPosition(const Index &index, Position &position) const

Gets the 2d position of cell specified by the index (x, y of cell position) in the grid map frame.

Parameters:

  • index – [in] the index of the requested cell.

  • position – [out] the position of the data point in the parent frame.

Returns:

true if successful, false if index not within range of buffer.

bool isInside(const Position &position) const

Check if position is within the map boundaries.

Parameters:

position – the position to be checked.

Returns:

true if position is within map, false otherwise.

bool isValid(const Index &index) const

Checks if the index of all layers defined as basic types are valid, i.e. if all basic types are finite. Returns false if no basic types are defined.

Parameters:

index – the index to check.

Returns:

true if cell is valid, false otherwise.

bool isValid(const Index &index, const std::string &layer) const

Checks if cell at index is a valid (finite) for a certain layer.

Parameters:

  • index – the index to check.

  • layer – the name of the layer to be checked for validity.

Returns:

true if cell is valid, false otherwise.

bool isValid(const Index &index, const std::vector<std::string> &layers) const

Checks if cell at index is a valid (finite) for certain layers.

Parameters:

  • index – the index to check.

  • layers – the layers to be checked for validity.

Returns:

true if cell is valid, false otherwise.

bool getPosition3(const std::string &layer, const Index &index, Position3 &position) const

Gets the 3d position of a data point (x, y of cell position & cell value as z) in the grid map frame. This is useful for data layers such as elevation.

Parameters:

  • layer – the name of the layer to be accessed.

  • index – the index of the requested cell.

  • position – the position of the data point in the parent frame.

Returns:

true if successful, false if no valid data available.

bool getVector(const std::string &layerPrefix, const Index &index, Eigen::Vector3d &vector) const

Gets the 3d vector of three layers with suffixes ‘x’, ‘y’, and ‘z’.

Parameters:

  • layerPrefix – the prefix for the layer to bet get as vector.

  • index – the index of the requested cell.

  • vector – the vector with the values of the data type.

Returns:

true if successful, false if no valid data available.

GridMap getSubmap(const Position &position, const Length &length, bool &isSuccess) const

Gets a submap from the map. The requested submap is specified with the requested location and length. Note: The returned submap may not have the requested length due to the borders of the map and discretization.

Parameters:

  • position – [in] the requested position of the submap (usually the center).

  • length – [in] the requested length of the submap.

  • isSuccess – [out] true if successful, false otherwise.

Returns:

submap (is empty if success is false).

GridMap getTransformedMap(const Eigen::Isometry3d &transform, const std::string &heightLayerName, const std::string &newFrameId, const double sampleRatio = 0.0) const

Apply isometric transformation (rotation + offset) to grid map and returns the transformed map. Note: The returned map may not have the same length since it’s geometric description contains the original map.

Parameters:

  • transform – [in] the requested transformation to apply.

  • heightLayerName – [in] the height layer of the map.

  • newFrameId – [in] frame index of the new map.

  • sampleRatio – [in] if zero or negative, no in-painting is used to fill missing points due to sparsity of the map. Otherwise, four points are sampled around each grid cell to make sure that at least one of those points map to a new grid cell. A sampleRatio of 1 corresponds to the the resolution of the grid map.

Throws:

std::out_of_range – if no map layer with name heightLayerName is present.

Returns:

transformed map.

void setPosition(const Position &position)

Set the position of the grid map. Note: This method does not change the data stored in the grid map and is complementary to the move(...) method. For a comparison between the setPosition and the move method, see the move_demo_node.cpp file of the grid_map_demos package.

Parameters:

position – the 2d position of the grid map in the grid map frame [m].

bool move(const Position &position, std::vector<BufferRegion> &newRegions)

Move the grid map w.r.t. to the grid map frame. Use this to move the grid map boundaries without moving the grid map data. Takes care of all the data handling, such that the grid map data is stationary in the grid map frame. Note: For a comparison between the setPosition and the move method, see the move_demo_node.cpp file of the grid_map_demos package.

Parameters:

  • position – the new location of the grid map in the map frame.

  • newRegions – the regions of the newly covered / previously uncovered regions of the buffer.

Returns:

true if map has been moved, false otherwise.

bool move(const Position &position)

Move the grid map w.r.t. to the grid map frame. Use this to move the grid map boundaries without moving the grid map data. Takes care of all the data handling, such that the grid map data is stationary in the grid map frame.

Parameters:

position – the new location of the grid map in the map frame.

Returns:

true if map has been moved, false otherwise.

bool addDataFrom(const GridMap &other, bool extendMap, bool overwriteData, bool copyAllLayers, std::vector<std::string> layers = std::vector<std::string>())

Adds data from an other grid map to this grid map

Parameters:

  • other – the grid map to take data from.

  • extendMap – if true the grid map is resized that the other map fits within.

  • overwriteData – if true the new data replaces the old values, else only invalid cells are updated.

  • copyAllLayer – if true all layers are used to add data.

  • layers – the layers that are copied if not all layers are used.

Returns:

true if successful.

bool extendToInclude(const GridMap &other)

Extends the size of the grip map such that the other grid map fits within.

Parameters:

other – the grid map to extend the size to.

Returns:

true if successful.

void clear(const std::string &layer)

Clears all cells (set to NAN) for a layer.

Parameters:

layer – the layer to be cleared.

void clearBasic()

Clears all cells (set to NAN) for all basic layers. Header information (geometry etc.) remains valid.

void clearAll()

Clears all cells of all layers. If basic layers are used, clearBasic() is preferred as it is more efficient. Header information (geometry etc.) remains valid.

void setTimestamp(const Time timestamp)

Set the timestamp of the grid map.

Parameters:

timestamp – the timestamp to set (in nanoseconds).

Time getTimestamp() const

Get the timestamp of the grid map.

Returns:

timestamp in nanoseconds.

void resetTimestamp()

Resets the timestamp of the grid map (to zero).

void setFrameId(const std::string &frameId)

Set the frame id of the grid map.

Parameters:

frameId – the frame id to set.

const std::string &getFrameId() const

Get the frameId of the grid map.

Returns:

frameId.

const Length &getLength() const

Get the side length of the grid map.

Returns:

side length of the grid map.

const Position &getPosition() const

Get the 2d position of the grid map in the grid map frame.

Returns:

position of the grid map in the grid map frame.

double getResolution() const

Get the resolution of the grid map.

Returns:

resolution of the grid map in the xy plane [m/cell].

const Size &getSize() const

Get the grid map size (rows and cols of the data structure).

Returns:

grid map size.

void setStartIndex(const Index &startIndex)

Set the start index of the circular buffer. Use this method with caution!

Returns:

buffer start index.

const Index &getStartIndex() const

Get the start index of the circular buffer.

Returns:

buffer start index.

bool isDefaultStartIndex() const

Checks if the buffer is at start index (0,0).

Returns:

true if buffer is at default start index.

void convertToDefaultStartIndex()

Rearranges data such that the buffer start index is at (0,0).

Position getClosestPositionInMap(const Position &position) const

Calculates the closest point to positionOutMap that is in the grid map. If positionOutMap is already in the grid map, that position is returned.

Parameters:

position – [in] position that should be approached as close as possible.

Returns:

position in map.