Plugins

You can add your own plugin to process the elevation map and publish an additional layer in the outgoing grid_map_msgs/msg/GridMap message.

This page is structured in two parts:

Create a plugin
Existing plugins

Create a plugin

You can create your own plugin to process the elevation map and publish a new derived layer.

Let’s look at the example.

First, create your plugin file in elevation_mapping_cupy/elevation_mapping_cupy/plugins/ and save it as example.py.

import cupy as cp
from typing import List
from .plugin_manager import PluginBase


class NameOfYourPlugin(PluginBase):
    def __init__(self, add_value:float=1.0, **kwargs):
        super().__init__()
        self.add_value = float(add_value)

    def __call__(self,
        elevation_map: cp.ndarray,
        layer_names: List[str],
        plugin_layers: cp.ndarray,
        plugin_layer_names: List[str],
        semantic_layers: cp.ndarray,
        semantic_layer_names: List[str],
        *args
    )->cp.ndarray:
        # Process maps here
        # You can also use the other plugin's data through plugin_layers.
        new_elevation = elevation_map[0] + self.add_value
        return new_elevation

Then, add your plugin setting to elevation_mapping_cupy/config/core/plugin_config.yaml.

example:                                      # Name of your filter
  type: "example"                             # Module name under plugins/.
  enable: True                                # Whether to load this plugin.
  fill_nan: True                              # Fill NaNs in invalid cells before publishing.
  is_height_layer: True                       # True for geometric layers, false for semantic scores.
  layer_name: "example_layer"                 # Output layer name.
  extra_params:                               # Passed to the plugin constructor.
    add_value: 2.0

example_large:                                # You can apply same filter with different name.
  type: "example"
  enable: True
  fill_nan: True
  is_height_layer: True
  layer_name: "example_layer_large"
  extra_params:
    add_value: 100.0

Finally, add your layer name to publishers in your config. You can create a new topic or add to existing topics.

plugin_example: # Topic name
  layers: [ 'elevation', 'example_layer', 'example_layer_large' ]
  basic_layers: [ 'example_layer' ]
  fps: 1.0        # The plugin is updated at this rate.

At runtime, the plugin manager imports the module from elevation_mapping_cupy.plugins and instantiates the first class that inherits from PluginBase. Keep the module name and the type field aligned.

Existing plugins

This section lists the plugins that are already installed and available for use.

1. Min filter

class elevation_mapping_cupy.plugins.min_filter.MinFilter(cell_n: int = 100, dilation_size: int = 5, iteration_n: int = 5, **kwargs)

This is a filter to fill in invalid cells with minimum values around.

Parameters:

cell_n (int) – width of the elevation map.
dilation_size (int) – The size of the patch to search for minimum value for each iteration.
iteration_n (int) – The number of iteration to repeat the same filter.
() (**kwargs)

__init__(cell_n: int = 100, dilation_size: int = 5, iteration_n: int = 5, **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

2. Inpainting

The default inpainting plugin only fills bounded interior holes; large or border-connected invalid regions stay unknown in the published layer.

class elevation_mapping_cupy.plugins.inpainting.Inpainting(cell_n: int = 100, method: str = 'telea', input_layer_name: str = 'elevation', max_hole_area: int = 64, fill_border_holes: bool = False, inpaint_radius: float = 1.0, **kwargs)

This class is used for inpainting, a process of reconstructing lost or deteriorated parts of images and videos.

Parameters:

cell_n (int) – The number of cells. Default is 100.
method (str) – The inpainting method. Options are ‘telea’ or ‘ns’ (Navier-Stokes). Default is ‘telea’.
() (**kwargs) – Additional keyword arguments.

__init__(cell_n: int = 100, method: str = 'telea', input_layer_name: str = 'elevation', max_hole_area: int = 64, fill_border_holes: bool = False, inpaint_radius: float = 1.0, **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

3. Smooth Filter

class elevation_mapping_cupy.plugins.smooth_filter.SmoothFilter(cell_n: int = 100, input_layer_name: str = 'elevation', **kwargs)

SmoothFilter is a class that applies a smoothing filter to the elevation map. The filter is applied to the layer specified by the input_layer_name parameter. If the specified layer is not found, the filter is applied to the elevation layer.

Parameters:

cell_n (int) – The width and height of the elevation map. Default is 100.
input_layer_name (str) – The name of the layer to which the filter should be applied. Default is “elevation”.
**kwargs – Additional keyword arguments.

__init__(cell_n: int = 100, input_layer_name: str = 'elevation', **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

4. Robot centric elevation

class elevation_mapping_cupy.plugins.robot_centric_elevation.RobotCentricElevation(cell_n: int = 100, resolution: float = 0.05, threshold: float = 0.4, use_threshold: bool = 0, **kwargs)

Generates an elevation map with respect to the robot frame.

Parameters:

cell_n (int)
resolution (ruamel.yaml.scalarfloat.ScalarFloat)
threshold (ruamel.yaml.scalarfloat.ScalarFloat)
use_threshold (bool)
() (**kwargs)

__init__(cell_n: int = 100, resolution: float = 0.05, threshold: float = 0.4, use_threshold: bool = 0, **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

5. Erosion

class elevation_mapping_cupy.plugins.erosion.Erosion(input_layer_name='traversability', kernel_size: int = 3, iterations: int = 1, reverse: bool = False, default_layer_name: str = 'traversability', **kwargs)

This class is used for applying erosion to an elevation map or specific layers within it. Erosion is a morphological operation that is used to remove small-scale details from a binary image.

Parameters:

kernel_size (int) – Size of the erosion kernel. Default is 3, which means a 3x3 square kernel.
iterations (int) – Number of times erosion is applied. Default is 1.
() (**kwargs) – Additional keyword arguments.

__init__(input_layer_name='traversability', kernel_size: int = 3, iterations: int = 1, reverse: bool = False, default_layer_name: str = 'traversability', **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

6. Max Filter

class elevation_mapping_cupy.plugins.max_filter.MaxFilter(cell_n: int = 100, dilation_size: int = 5, iteration_n: int = 5, **kwargs)

This is a filter to fill in invalid cells with maximum values around.

…

width

width of the elevation map.

Type:: int

height

height of the elevation map.

Type:: int

dilation_size

The size of the patch to search for maximum value for each iteration.

Type:: int

iteration_n

The number of iteration to repeat the same filter.

Type:: int

__init__(cell_n: int = 100, dilation_size: int = 5, iteration_n: int = 5, **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)

7. Max Layer Filter

class elevation_mapping_cupy.plugins.max_layer_filter.MaxLayerFilter(cell_n: int = 100, layers: list = ['traversability'], reverse: list = [True], min_or_max: str = 'max', thresholds: list = [False], scales: list = [1.0], default_value: float = 0.0, **kwargs)

Applies a maximum filter to the input layers and updates the traversability map. This can be used to enhance navigation by identifying traversable areas.

Parameters:

cell_n (int) – The width and height of the elevation map.
reverse (list) – A list of boolean values indicating whether to reverse the filter operation for each layer. Default is [True].
min_or_max (str) – A string indicating whether to apply a minimum or maximum filter. Accepts “min” or “max”. Default is “max”.
layers (list) – List of layers for semantic traversability. Default is [“traversability”].
thresholds (list) – List of thresholds for each layer. If the value is bigger than a threshold, assign 1.0 otherwise 0.0. If it is False, it does not apply. Default is [False].
**kwargs – Additional keyword arguments.

__init__(cell_n: int = 100, layers: list = ['traversability'], reverse: list = [True], min_or_max: str = 'max', thresholds: list = [False], scales: list = [1.0], default_value: float = 0.0, **kwargs)

Parameters:

plugin_params – PluginParams
callback (The parameter of)