multiLayerMap

Manage multiple map layers

Since R2021a

Description

The multiLayerMap object groups and stores multiple map layers as mapLayer, occupancyMap, or binaryOccupancyMap objects.

Once added to this object, map layers can be modified by either using the multiLayerMap object functions or by performing actions on individual map layers using their object functions or the layer name as input. Any modification to common properties on the multiLayerMap object are reflected across all associated layers.

Creation

Syntax

map = multiLayerMap

map = multiLayerMap(maps)

map = multiLayerMap(names,mapData)

map = multiLayerMap(names,width,height)

map = multiLayerMap(names,width,height,cellDims)

map = multiLayerMap(names,rows,cols,'grid')

map = multiLayerMap(names,rows,cols,cellDims,'grid')

map = multiLayerMap(sourceMap)

map = multiLayerMap(___,Name,Value)

Description

map = multiLayerMap creates an empty map object occupying 10-by-10 meters of space with a resolution of 1 cell per meter.

map = multiLayerMap(maps) creates a multilayer map from a cell array of mapLayer, occupancyMap, or binaryOccupancyMap objects. Objects combined into a multilayer map must be defined with the same resolution and cover the same region in space, but can represent different categories of information over the shared region.

map = multiLayerMap(names,mapData) creates a multilayer map from the cell array of layer names and associated cell array of map matrices. Matrices must have the same first two dimensions to cover the same shared region. Default resolution is 1 cell per meter.

map = multiLayerMap(names,width,height) creates a multilayer map with the cell array of layer names covering the specified width and height as scalars in meters.

map = multiLayerMap(names,width,height,cellDims) creates a multilayer map where the size of the data stored in each cell of the map is defined by the array of integers, cellDims. For multiple layers, cellDims is a cell array of integer arrays.

map = multiLayerMap(names,rows,cols,'grid') specifies the map width and height as a grid size specified in the rows and cols inputs.

map = multiLayerMap(names,rows,cols,cellDims,'grid') creates a map with a specified grid size and the size of the data stored in each cell is defined by the array of integers or cell array of integer arrays cellDims.

map = multiLayerMap(sourceMap) creates a new object using the layers copied from another multiLayerMap object.

map = multiLayerMap(___,Name,Value) specifies property values using name-value pairs.

For example, multiLayerMap(__,'LocalOriginInWorld',[15 20]) sets the local origin to a specific world location.

Input Arguments

maps — Map layers

N-element cell array of mapLayer objects

Map layers, specified as an N-element cell array of mapLayer objects.

names — Name of each layer

cell array of string scalars

Name of each layer, specified as a cell array of string scalars. The order of these names are associated with the order of other arguments that are cell arrays.

Data Types: cell | string

mapData — Map data of map layers

cell array of matrices

Map data of map layers, specified as a cell array of matrices. Each matrix must have the same dimensions.

width — Map width

positive numeric scalar

Map width, specified as a positive numeric scalar. Units are in cells per meter.

height — Map height

positive numeric scalar

Map height, specified as a positive numeric scalar. Units are in cells per meter.

rows — Number of grid rows

positive numeric integer

Number of grid rows, specified as a positive numeric integer.

cols — Number of grid columns

positive numeric integer

Number of grid columns, specified as a positive numeric integer.

cellDims — Dimensions of cell data in map layers

1 (default) | positive numeric integer | N-element vector of positive integers | M-by-N matrix of positive integers

Dimensions of cell data in map layers, specified as a positive numeric integer, an N-element vector of positive integers, or an M-by-N matrix of positive integers.

If cellDims is a positive numeric integer greater than 1, then each map cell contains a vector of numeric scalars with cellDims number of elements. By default, the cellDims value of 1 means that each element in the map layer stores a numeric scalar

If cellDims is an N-element vector of positive integers, then each map cell contains a vector of size N containing numeric scalars.

If cellDims is an M-by-N matrix of positive integers, then each map cell contains a matrix of size M-by-N of numeric scalars.

Example: mapLayer(width,height,3) creates a 3-D map layer.

sourceMap — Source map layer

multiLayerMap object

Source map layers, specified as a multiLayerMap object.

Properties

DataSize — Size of the data in each map layer data array

cell array of integer vectors

Size of the data in each map layer data array, specified as a cell array of integer vectors. In each vector, the first two dimensions define the footprint of the map layer, and all subsequent dimensions dictate the size and layout of the data stored in each cell.

If the map stores an n-element vector of values in each cell, this property would be [width height n].

If the map stores a 10-by-10 grid with each cell containing a 3-by-3-by-3 matrix array, the data size would be [10 10 3 3 3].

After you create the object, this property is read-only.

Data Types: cell | double

DataType — Data type of the values stored

cell array of string scalars

Data type of the values stored in each layer, specified as a cell array of character vectors.

When you create this object, the specified map layers determine each data type. After you create the object, this property is read-only.

Data Types: cell | char

DefaultValue — Default value for unspecified map locations

{0} (default) | cell array of numeric scalars

Default value for unspecified map locations for each layer, specified as a cell array of numeric scalars. This default value is returned for areas outside the map as well.

Data Types: cell | double

GridLocationInWorld — Location of the grid in local coordinates

[0 0] (default) | two-element vector | [xWorld yWorld]

Location of the bottom-left corner of the grid in world coordinates, specified as a two-element vector, [xWorld yWorld].

You can set this property when you create the object.

Data Types: double

GridOriginInLocal — Location of the grid in local coordinates

[0 0] (default) | two-element vector | [xLocal yLocal]

Location of the bottom-left corner of the grid in local coordinates, specified as a two-element vector, [xLocal yLocal].

You can set this property when you create the object.

Data Types: double

GridSize — Number of rows and columns in grid

Read-only: two-element integer-valued vector

This property is read-only.

Number of rows and columns in grid, stored as a 1-by-2 real-valued vector representing the number of rows and columns, in that order.

Data Types: double

LayerNames — Name of each layer

cell array of string scalars

Name of each layer, specified as a cell array of string scalars. The order of these names are associated with the order of other properties that are cell arrays.

You can set this property when you create the object. After you create the object, this property is read-only.

Data Types: cell | string

LocalOriginInWorld — Location of the local frame in world coordinates

[0 0] (default) | two-element vector | [xWorld yWorld]

Location of the origin of the local frame in world coordinates, specified as a two-element vector, [xLocal yLocal]. Use the move function to shift the local frame as your vehicle moves.

You can set this property when you create the object.

Data Types: double

NumLayers — Number of map layers

Read-only: 1 (default) | positive integer

This property is read-only.

Number of map layers, stored as a positive integer.

Data Types: double

Resolution — Grid resolution

Read-only: 1 (default) | scalar

This property is read-only.

Grid resolution, stored as a scalar in cells per meter representing the number and size of grid locations.

You can set this property when you create the object. After you create the object, this property is read-only.

Data Types: double

XLocalLimits — Minimum and maximum values of x-coordinates in local frame

Read-only: two-element vector

This property is read-only.

Minimum and maximum values of x-coordinates in local frame, stored as a two-element horizontal vector of the form [min max]. Local frame is defined by LocalOriginInWorld property.

Data Types: double

YLocalLimits — Minimum and maximum values of y-coordinates in local frame

Read-only: two-element vector

This property is read-only.

Minimum and maximum values of y-coordinates in local frame, stored as a two-element horizontal vector of the form [min max]. Local frame is defined by LocalOriginInWorld property.

Data Types: double

XWorldLimits — Minimum and maximum world range values of x-coordinates

Read-only: two-element vector

This property is read-only.

Minimum and maximum world range values of x-coordinates, stored as a 1-by-2 vector representing the minimum and maximum values, in that order.

Data Types: double

YWorldLimits — Minimum and maximum world range values of y-coordinates

Read-only: two-element vector

This property is read-only.

Minimum and maximum world range values of y-coordinates, stored as a 1-by-2 vector representing the minimum and maximum values, in that order.

Data Types: double

Object Functions

getLayer	Return individual layers from multilayer map
getMapData	Retrieve data from map layers
grid2local	Convert grid indices to local coordinates
grid2world	Convert grid indices to world coordinates
local2grid	Convert local coordinates to grid indices
local2world	Convert local coordinates to world coordinates
move	Move map in world frame
setMapData	Assign data to map layers
syncWith	Sync map with overlapping map
world2grid	Convert world coordinates to grid indices
world2local	Convert world coordinates to local coordinates

Examples

Create Listeners Using Dependent Map Layers

The multiLayerMap object enables you to group multiple map layers and define behavior for those layers when setting and getting data. Using separate map layers, you can store various map data and specify different behaviors for each. You can also define the SetTransformFcn and GetTransformFcn function handles for a map layer so that dependencies are created between layers. This example shows how to store data in a map layer and implement event listeners which update other maps. These maps store how many times the data is updated or accessed.

Dependent Layers

Create two independent map layers.

mapAccessed = mapLayer(zeros(10,10),"LayerName","GetListener");
mapModified = mapLayer(zeros(10,10),"LayerName","SetListener");

Specify function handles for the get and set transform functions used in the main map layer. These functions increment the value of a grid location when you get or set map data in the input map mainMap. See Listener Function Handles for the function implementation.

getHookFcn = @(mainMap,values,varargin)exampleHelperGetHookFcn(mapAccessed,mainMap,values,varargin{:});
setHookFcn = @(mainMap,values,varargin)exampleHelperSetHookFcn(mapModified,mainMap,values,varargin{:});

Create the main map layer with default values of 0.5. Specify the function handles to create the layer dependencies.

map = mapLayer(repmat(0.5,10,10), ...
                'GetTransformFcn',getHookFcn, ...
                'SetTransformFcn',setHookFcn);

Add all maps to the same multiLayerMap object.

multiMapLayers = multiLayerMap({map,mapAccessed,mapModified})

multiMapLayers = 
  multiLayerMap with properties:

   Map Properties
              NumLayers: 3
               GridSize: [10 10]
             Resolution: 1
    GridLocationInWorld: [0 0]
      GridOriginInLocal: [0 0]
     LocalOriginInWorld: [0 0]
           XLocalLimits: [0 10]
           YLocalLimits: [0 10]
           XWorldLimits: [0 10]
           YWorldLimits: [0 10]

   Layer Properties
             LayerNames: {'mapLayer'  'GetListener'  'SetListener'}
               DataSize: {[10 10]  [10 10]  [10 10]}
               DataType: ["double"    "double"    "double"]
           DefaultValue: {[0]  [0]  [0]}

Set the (0,0) map location with a value of zero using the setMapData object function of multiLayerMap object.

setMapData(multiMapLayers,"mapLayer",[0 0],0)

Check that SetListener map layer incremented their value.

getMapData(multiMapLayers,"SetListener",[0 0])

ans = 
1

Get the data you just set to the main map layer. The expected value of zero is returned.

getMapData(multiMapLayers,"mapLayer",[0 0])

ans = 
0

Check that GetListener map layer incremented their value.

getMapData(multiMapLayers,"GetListener",[0 0])

ans = 
1

Update the entire map with a matrix of values. Access the data as well.

setMapData(multiMapLayers,"mapLayer",rand(10,10))
getMapData(multiMapLayers,"mapLayer")

ans = 10×10

    0.8147    0.1576    0.6557    0.7060    0.4387    0.2760    0.7513    0.8407    0.3517    0.0759
    0.9058    0.9706    0.0357    0.0318    0.3816    0.6797    0.2551    0.2543    0.8308    0.0540
    0.1270    0.9572    0.8491    0.2769    0.7655    0.6551    0.5060    0.8143    0.5853    0.5308
    0.9134    0.4854    0.9340    0.0462    0.7952    0.1626    0.6991    0.2435    0.5497    0.7792
    0.6324    0.8003    0.6787    0.0971    0.1869    0.1190    0.8909    0.9293    0.9172    0.9340
    0.0975    0.1419    0.7577    0.8235    0.4898    0.4984    0.9593    0.3500    0.2858    0.1299
    0.2785    0.4218    0.7431    0.6948    0.4456    0.9597    0.5472    0.1966    0.7572    0.5688
    0.5469    0.9157    0.3922    0.3171    0.6463    0.3404    0.1386    0.2511    0.7537    0.4694
    0.9575    0.7922    0.6555    0.9502    0.7094    0.5853    0.1493    0.6160    0.3804    0.0119
    0.9649    0.9595    0.1712    0.0344    0.7547    0.2238    0.2575    0.4733    0.5678    0.3371

Check that GetListener and SetListener map layers incremented their values.

getMapData(multiMapLayers,"SetListener")

ans = 10×10

     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     2     1     1     1     1     1     1     1     1     1

getMapData(multiMapLayers,"GetListener")

ans = 10×10

     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     1     1     1     1     1     1     1     1     1     1
     2     1     1     1     1     1     1     1     1     1

The bottom-left location returns two and all other values are one. This confirms the listener functions are working as intended.

Listener Function Handles

These functions implement the get and set example helper functions that update the other map layers.

function valuesOut = exampleHelperSetHookFcn(modifiedMap,sourceLayer,valueIn,varargin)
    % Pass output through
    valuesOut = valueIn;
    
    % If no additional inputs are passed, return immediately.
    if numel(varargin) == 0
        return;
    else
        % Otherwise, increment the value in the modifiedMap.
        if numel(varargin) == 1
            currentValue = getMapData(modifiedMap);
            setMapData(modifiedMap,currentValue+1);
        else        
            currentValue = getMapData(modifiedMap,varargin{1},varargin{3:end});
            % setMapData syntax <<<<>>>>
            setMapData(modifiedMap,varargin{1},currentValue+1,varargin{3:end});
        end
    end
end

function data = exampleHelperGetHookFcn(accessedMap,sourceLayer,valuesIn,varargin)
    
    data = valuesIn;

    % If no additional inputs are passed, check if the values in
    if numel(varargin) == 0
        if isequal(size(valuesIn),sourceLayer.DataSize)
            % Increment the dependent map.
            currentValue = getMapData(accessedMap);
            setMapData(accessedMap,currentValue+1);
        end
    else
        currentValue = getMapData(accessedMap,varargin{:});
        setMapData(accessedMap,varargin{1},currentValue+1,varargin{3:end});
    end
end

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

As of MATLAB^® R2022a, default map behavior during code generation has changed, which may result in backward compatibility issues. Maps such as multiLayerMap now support fixed-size code generation (DynamicMemoryAllocation="off").

1. Maps that are either default-constructed or constructed with compile-time constant size information (or matrices that are of compile-time constant size) produce fixed-size maps.

2. To restore the previous behavior, use the coder.ignoreConst (MATLAB Coder) function when specifying size inputs, or coder.varsize (MATLAB Coder) matrix variable name specified as a string scalar or character vector, prior to constructing the map.

Version History

Introduced in R2021a