getMapData

Retrieve data from map layer

Since R2021a

Syntax

mapData = getMapData(map)

mapData = getMapData(map,xy)

mapData = getMapData(map,xy,"local")

mapData = getMapData(map,ij,"grid")

[mapData,inBounds] = getMapData(___)

mapData = getMapData(map,bottomLeft,mapSize)

mapData = getMapData(map,bottomLeft,mapSize,"local")

mapData = getMapData(map,topLeft,gridSize,"grid")

Description

mapData = getMapData(map) returns a matrix of values that contains all the data for the given map layer map.

mapData = getMapData(map,xy) returns an array of values for the given xy-locations in world coordinates.

mapData = getMapData(map,xy,"local") returns an array of values for the given xy-locations in local coordinates.

mapData = getMapData(map,ij,"grid") returns an array of values for the given ij-locations in grid coordinates. Each row of ij refers to a grid cell index [i j]

[mapData,inBounds] = getMapData(___) also returns a vector of logical values indicating whether the corresponding input location xy or ij is valid using the previous syntaxes.

mapData = getMapData(map,bottomLeft,mapSize) returns a matrix of values in a subregion of the map layer, map. The subregion starts in the bottom-left xy-position bottomLeft in world coordinates with a given map size mapSize specified as [width height] in meters.

mapData = getMapData(map,bottomLeft,mapSize,"local") specifies the bottom-left corner of the subregion in local coordinates.

mapData = getMapData(map,topLeft,gridSize,"grid") specifies the top-left corner of the sub region in grid coordinates. The subregion size, gridSize is also given in grid coordinates as [rows cols].

Examples

Store and Modify XY Velocities Using A Single Map Layer

Create a map layer that stores two values per grid location as xy-velocities.

Create an m-by-n-by-2 matrix of values. The first element in the third dimension is dx and the second is dy as velocities.

dXY = reshape(1:200,10,20);
dXY(:,:,2) = dXY;

Create a map layer from the matrix. Specify the resolution and layer name.

vLayer = mapLayer(dXY,'Resolution',1,'LayerName','dXY');

Get all the map data out as a matrix. Get the xy-locations of the velocity values by creating arrays that cover the minimum and maximum xy-world limits and is shifted to the grid-center locations. The y-locations are flipped when converting between matrix to world coordinates. Visualize the velocities corresponding to those grid-center locations using the quiver function.

v = getMapData(vLayer);

R = 1/(2*vLayer.Resolution);
xLim = vLayer.XWorldLimits;
yLim = vLayer.YWorldLimits;
xLoc = (xLim(1)+R):R*2:(xLim(2)-R);
yLoc = (yLim(2)-R):-R*2:(yLim(1)+R);

quiver(xLoc,yLoc,v(:,:,1),v(:,:,2))

Set the bottom-left quadrant to new updated values. Create the values as a matrix and specify the bottom-left corner (0,0) in map coordinates to the setData function.

updateValues = repmat(reshape([-50,100],[1 1 2]),5,10);

setMapData(vLayer,[0 0],updateValues)
v = getMapData(vLayer);
quiver(xLoc,yLoc,v(:,:,1),v(:,:,2))

Set new values for the top-left quadrant using grid coordinates. For maps, the top-left grid location is (1,1).

setMapData(vLayer,[1 1],updateValues,'grid')
v = getMapData(vLayer);
quiver(xLoc,yLoc,v(:,:,1),v(:,:,2))

Write Custom Transform Functions for Map Layers

The mapLayer object enables you to apply custom element-wise transformations when setting and getting data in the map. To transform data you set or get from the map, specify function handles for the GetTransfomFcn and SetTransformFcn properties. This example shows how to implement a log-odds probabilistic map layer by creating a lookup table for probability and log-odds values. The transform functions use these lookup tables to convert between these values when setting or getting data.

Create Lookup Tables

Generate a full lookup table of values that map the probability values to the minimum and maximum limits of int16 values.

Create an array of int16 values from intmin to intmax. Define the probability limits.

intType = 'int16';
intLinSpace = intmin(intType):intmax(intType);
numOfPoints = length(intLinSpace);
probLimits = [0.001 0.999];

The exampleHelperProbToLogodds and examplerHelperLogoddsToProb functions convert between the log-odds and probability values. Use the helper functions to get the log-odds limits and generate the array for looking up log-odds values. Create an interpolated grid for the entire lookup table.

logOddsLimits = exampleHelperProbToLogodds([0.001 0.999]);
logOddsLookup = single(exampleHelperLogoddsToProb(linspace(logOddsLimits(1),logOddsLimits(2),numOfPoints)));
interpTable = griddedInterpolant(logOddsLookup,single(intLinSpace),'nearest');

Specify Transform Function Handles

The transform function handles utilize example helpers that define how to convert between log-odds integer values and the probability values with an applied saturation limit. The probability saturation limits are [0.001 .999] as previously specified. This behavior is similar to the occupancyMap object.

getXformFcn = @(obj,logodds,varargin)...
    exampleHelperIntLogoddsToProb(logodds,logOddsLookup(:),intLinSpace);

setXformFcn = @(obj,prob,varargin)...
    exampleHelperProbToIntLogodds(prob,interpTable,logOddsLookup(:),intLinSpace,probLimits);

Create Map Layer

Generate an occupancy map layer object from a matrix of probability values. Specify the get and set transform functions.

occupancyLayer = mapLayer(repmat(0.5,10,10),...
                           'LayerName','Occupancy',...
                           'GetTransformFcn',getXformFcn,...
                           'SetTransformFcn',setXformFcn);

Notice that when you create the map, the default value is 0.001 instead of 0. This difference is because the SetTransformFcn function has been applied to the default value of 0 when you create the object, which saturates the value to 0.001.

disp(occupancyLayer.DefaultValue)

    0.0010

Get and Set Map Data

The map data matches the matrix you set on creation.

extData = getMapData(occupancyLayer) 

extData = 10×10

    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000
    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000    0.5000

Set specific map locations to values that are:

• Outside of the probability saturation limits.

• Higher precision than the resolution of the lookup tables.

setMapData(occupancyLayer,[0 0],0.00001)
setMapData(occupancyLayer,[5 5],0.25999)

For the first location, the probability is bound to the saturation limits.

extData = getMapData(occupancyLayer,[0 0])

extData = 
0.0010

The second location returns the value closest to the probability value in the lookup table.

extData2 = getMapData(occupancyLayer,[5 5])

extData2 = 
0.2600

The generated map layer can now be used for updating a probability occupancy map that are stored as int16 values. To combine this map with other layers or map types, see the multiLayerMap object.

Input Arguments

map — Map layer

mapLayer object

Map layer, specified as a mapLayer object.

xy — World or local coordinates

n-by-2 matrix

World or local coordinates, specified as an n-by-2 matrix of [x y] pairs, where n is the number of coordinates.

Data Types: double

ij — Grid positions

n-by-2 matrix

Grid positions, specified as an n-by-2 matrix of [i j] pairs in [rows cols] format, where n is the number of grid positions.

Data Types: double

bottomLeft — Location of output matrix in world or local coordinates

two-element vector | [xCoord yCoord]

Location of bottom left corner of output matrix in world or local coordinates, specified as a two-element vector, [xCoord yCoord]. Location is in world or local coordinates based on syntax.

Data Types: double

mapSize — Subregion map size

two-element vector | [x y]

Subregion map size, specified as a two-element vector [x y] in world or local coordinates.

Data Types: double

gridSize — Output grid size

two-element vector | [row col]

Output grid size, specified as a two-element vector [row col].

Data Types: double

topLeft — Location of grid

two-element vector | [iCoord jCoord]

Location of top left corner of grid, specified as a two-element vector, [iCoord jCoord].

Data Types: double

Output Arguments

mapData — Data values from map layer

matrix

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 rows and columns respectively. DataDims are the dimensions of the map data, map.DataSize(3:end).

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

inBounds — Valid map locations

n-by-1 column vector

Valid map locations, returned as an n-by-1 column vector equal in length to xy or ij. Locations inside the map limits return a value of 1. Locations outside the map limits return a value of 0.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2021a

R2023a: Signed Distance Map Support

The getMapData function now supports the signedDistanceMap object as a new map representation for the map argument.