Main Content

getMapData

Retrieve data from map layers

Since R2021a

collapse all in page

Syntax

mapData = getMapData(map)
mapData = getMapData(map,layername)
mapData = getMapData(map,layername,layerinputs)

Description

mapData = getMapData(map) returns a cell array of matrices for the data in each layer of the specified multiLayerMap object. For binary or occupancy map layers, the values of this function are passed to the getOccupancy function. mapData is returned as an cell-array of matrices for each layer.

example

mapData = getMapData(map,layername) returns all the map data for the specified layer name. mapData is returned as a matrix equal to the DataSize of the specified layer.

mapData = getMapData(map,layername,layerinputs) takes the layerinputs arguments and passes them to the getMapData object function for the specified map layer name. To access individual cells or blocks of data in the world, local, or grid coordinates, see the syntaxes of getMapData.

Examples

collapse all

Open Live Script

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

Input Arguments

collapse all

Multilayer map, specified as a multiLayerMap object.

Map layer name, specified as a string scalar or character array. Map layers have their name specified when creating the multiLayerMap object.

Variable-length inputs to getMapData function of map layer, specified as varargin. To specify individual cells or blocks of data in the world, local, or grid coordinates, see the syntaxes of getMapData.

Output Arguments

collapse all

Data values from map layer, returned as a matrix. By default, the function returns all data on the layer as an M-by-N-by-DataDims matrix. M and N are the grid height and width respectively. DataDims are the dimensions of the map data, map.DataSize(3,:).

For other syntaxes, the map data may be given as an array of values with size N-by-DataDims or as a subregion of the full matrix.

Version History

Introduced in R2021a

See Also

Objects

Functions