Main Content

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

Description

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

example

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.

Properties

expand all

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

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

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

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

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

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

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

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

This property is read-only.

Number of map layers, stored as a positive integer.

Data Types: double

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

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

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

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

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

getLayerReturn individual layers from multilayer map
getMapDataRetrieve data from map layers
grid2localConvert grid indices to local coordinates
grid2worldConvert grid indices to world coordinates
local2gridConvert local coordinates to grid indices
local2worldConvert local coordinates to world coordinates
moveMove map in world frame
setMapDataAssign data to map layers
syncWithSync map with overlapping map
world2gridConvert world coordinates to grid indices
world2localConvert world coordinates to local coordinates

Examples

collapse all

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

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 depedent 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

Version History

Introduced in R2021a