Main Content

getMapData

Retrieve data from map layer

Description

example

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

collapse all

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

Figure contains an axes object. The axes object contains an object of type quiver.

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

Figure contains an axes object. The axes object contains an object of type quiver.

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

Figure contains an axes object. The axes object contains an object of type quiver.

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 probabilitistic 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 probablilty limits.

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

The exampleHelperProbToLogodds and examplerHelperLogoddsToProb functions covert 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 .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 occupany map that are stored as int16 values. To combine this map with other layers or map types, see the multiLayerMap object.

Input Arguments

collapse all

Map layer, specified as a mapLayer object.

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

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

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

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

Data Types: double

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

Data Types: double

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

Data Types: double

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

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

Introduced in R2021a