# 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

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

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

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

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.

## Version History

Introduced in R2021a

expand all