Plugins

You can add your own plugin to process the elevation map and publish as a layer in GridMap message.

This page is structured in two parts:

Create a plugin

You can create your own plugin to process the elevation map and publish as a layer in GridMap message.

Let’s look at the example.

First, create your plugin file in elevation_mapping_cupy/script/plugins/ and save 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 config/plugin_config.yaml

example:                                      # Name of your filter
  type: "example"                             # Specify the name of your plugin (the name of your file name).
  enable: True                                # weather to load this plugin
  fill_nan: True                              # Fill nans to invalid cells of elevation layer.
  is_height_layer: True                       # If this is a height layer (such as elevation) or not (such as traversability)
  layer_name: "example_layer"                 # The layer name.
  extra_params:                               # This params are passed to the plugin class on initialization.
    add_value: 2.0                            # Example param

example_large:                                # You can apply same filter with different name.
  type: "example"                             # Specify the name of your plugin (the name of your file name).
  enable: True                                # weather to load this plugin
  fill_nan: True                              # Fill nans to invalid cells of elevation layer.
  is_height_layer: True                       # If this is a height layer (such as elevation) or not (such as traversability)
  layer_name: "example_layer_large"           # The layer name.
  extra_params:                               # This params are passed to the plugin class on initialization.
    add_value: 100.0                          # Example param with larger value.

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 called with this fps.

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

class elevation_mapping_cupy.plugins.inpainting.Inpainting(cell_n: int = 100, method: str = 'telea', **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', **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. Semantic Filter

class elevation_mapping_cupy.plugins.semantic_filter.SemanticFilter(cell_n: int = 100, classes: list = ['person', 'grass'], **kwargs)

This is a filter to create a one hot encoded map of the class probabilities.

Parameters:

  • cell_n (int) – width and height of the elevation map.

  • classes (list) – List of classes for semantic filtering. Default is [“person”, “grass”].

  • **kwargs – Additional keyword arguments.

__init__(cell_n: int = 100, classes: list = ['person', 'grass'], **kwargs)
Parameters:

  • plugin_params – PluginParams

  • callback (The parameter of)

color_map(N: int = 256, normalized: bool = False)

Creates a color map with N different colors.

Parameters:

  • N (int, optional) – The number of colors in the map. Defaults to 256.

  • normalized (bool, optional) – If True, the colors are normalized to the range [0,1]. Defaults to False.

Returns:

The color map.

Return type:

np.ndarray

transform_color()

Transforms the color map into a format that can be used for semantic filtering.

Returns:

The transformed color map.

Return type:

cp.ndarray

get_layer_indices(layer_names: List[str]) → List[int]

Get the indices of the layers that are to be processed using regular expressions. :param layer_names: List of layer names. :type layer_names: List[str]

Returns:

List of layer indices.

Return type:

List[int]

6. Semantic traversability

class elevation_mapping_cupy.plugins.semantic_traversability.SemanticTraversability(cell_n: int = 100, layers: list = ['traversability'], thresholds: list = [0.5], type: list = ['traversability'], **kwargs)

Extracts traversability and elevations from layers and generates an updated traversability that can be used by checker.

Parameters:

  • cell_n (int) – The width and height of the elevation map.

  • layers (list) – List of layers for semantic traversability. Default is [“traversability”].

  • thresholds (list) – List of thresholds for each layer. Default is [0.5].

  • type (list) – List of types for each layer. Default is [“traversability”].

  • **kwargs – Additional keyword arguments.

__init__(cell_n: int = 100, layers: list = ['traversability'], thresholds: list = [0.5], type: list = ['traversability'], **kwargs)
Parameters:

  • plugin_params – PluginParams

  • callback (The parameter of)

7. Features PCA

class elevation_mapping_cupy.plugins.features_pca.FeaturesPca(cell_n: int = 100, process_layer_names: List[str] = [], **kwargs)

This is a filter to create a pca layer of the semantic features in the map.

Parameters:

  • cell_n (int) – width and height of the elevation map.

  • classes (ruamel.yaml.comments.CommentedSeq)

  • () (**kwargs)

__init__(cell_n: int = 100, process_layer_names: List[str] = [], **kwargs)
Parameters:

  • plugin_params – PluginParams

  • callback (The parameter of)

get_layer_indices(layer_names: List[str]) → List[int]

Get the indices of the layers that are to be processed using regular expressions. :param layer_names: List of layer names. :type layer_names: List[str]

Returns:

List of layer indices.

Return type:

List[int]