mapLayer

Create map layer for N-dimensional data

Since R2021a

Description

The mapLayer object creates an N-dimensional grid map, where the first two dimensions determine the footprint of the map, and all subsequent dimensions dictate the size and layout of the data stored in each cell. For storing scalar binary or probability values for a grid map, use the binaryOccupancyMap or occupancyMap objects instead.

A map layer stores data for grid cells that represent a discretized region of space. To query and update data using world, local, or grid coordinates, use the getMapData and setMapData object functions. Each grid cell in the map can store data of any size from a single a value to a multi-dimensional array. For more information, see the DataSize property.

Layer behavior can also be customized by providing function handles during creation using the GetTransformFcn and SetTransformFcn properties.

Creation

Syntax

map = mapLayer

map = mapLayer(mapData)

map = mapLayer(width,height)

map = mapLayer(rows,cols,'grid')

map = mapLayer(width,height,cellDims)

map = mapLayer(rows,cols,cellDims,'grid')

map = mapLayer(sourceMap)

map = mapLayer(___,Name=Value)

Description

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

map = mapLayer(mapData) creates a map from the values in the matrix or matrix array.

map = mapLayer(width,height) creates a map covering the specified width and height with a resolution of 1 cell per meter.

map = mapLayer(rows,cols,'grid') creates a map with a grid size of rows,cols with a resolution of 1 cell per meter.

map = mapLayer(width,height,cellDims) creates the map where the size of the data stored in each cell is defined by the array of integers cellDims.

map = mapLayer(rows,cols,cellDims,'grid') creates a map with a grid size of rowscols where the size of the data stored in each cell is defined by the array of integers cellDims.

map = mapLayer(sourceMap) creates a new object using the layers copied from another mapLayer object.

map = mapLayer(___,Name=Value) specifies property values using name-value arguments.

For example, mapLayer(__,'LocalOriginInWorld',[15 20]) sets the local origin to a specific world location.

Input Arguments

mapData — Map values

matrix | multidimensional array

Map values, specified as a matrix or multidimensional array.

Map Values	Contents of Map Cells
2-D matrix	Scalar For example, in this 2-D matrix each element in the 2-by-2 map stores one scalar. p = [1 2; 3 4]; map = mapLayer(p);
3-D array	Vector For example, in this 3-D array each element in the 2-by-2 map stores a three-element vector. p = []; p(:,:,1) = ones(2,2); p(:,:,2) = ones(2,2); p(:,:,3) = ones(2,2); map = mapLayer(p);
N-D array	2-D matrix, 3-D array, etc For example, in this 4-D array each element in the 2-by-2 map stores a 2-by-2 matrix. p = []; p(1,1,:,:) = ones(2,2); p(1,2,:,:) = ones(2,2); p(2,1,:,:) = ones(2,2); p(2,2,:,:) = ones(2,2); map = mapLayer(p);

For more information about multidimensional arrays, see Multidimensional Arrays.

width — Map width

positive numeric scalar

Map width, specified as a positive numeric scalar. Units are in cells per meter.

height — Map height

positive numeric scalar

Map height, specified as a positive numeric scalar. Units are in cells per meter.

rows — Number of grid rows

positive numeric integer

Number of grid rows, specified as a positive numeric integer.

cols — Number of grid columns

positive numeric integer

Number of grid columns, specified as a positive numeric integer.

cellDims — Dimensions of cell data

1 (default) | positive numeric integer | N-element vector of positive integers | M-by-N matrix of positive integers

Dimensions of cell data, specified as a positive numeric integer, an N-element vector of positive integers, or an M-by-N matrix of positive integers.

If cellDims is a positive numeric integer greater than 1, then each map cell contains a vector of numeric scalars with cellDims number of elements. By default, the cellDims value of 1 means that each element in the map layer stores a numeric scalar

If cellDims is an N-element vector of positive integers, then each map cell contains a vector of size N containing numeric scalars.

If cellDims is an M-by-N matrix of positive integers, then each map cell contains a matrix of size M-by-N of numeric scalars.

Example: mapLayer(width,height,3) creates a 3-D map layer.

sourceMap — Source map layer

mapLayer object

Source map layer, specified as a mapLayer object.

Properties

DataSize — Size of the N-dimensional data matrix

[10 10] (default) | vector of integers

Size of the N-dimensional data matrix, specified as vector of integers. The first two dimensions define the footprint of the map, and all subsequent dimensions dictate the size and layout of the data stored in each cell. The default value assumes a single value is stored for each cell in a 10-by-10 grid.

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

This property is set when you create the object based on the dimensions of the input matrix p or the inputs width, height, and cellDims.

After you create the object, this property is read-only.

Data Types: double

DataType — Data type of the values stored

'double' (default) | character vector

Data type of the values stored in the map, specified as a character vector.

This property is set based on the data type of the input p or the data type of DefaultValue. After you create the object, this property is read-only.

Data Types: char

DefaultValue — Default value for unspecified map locations

0 (default) | numeric scalar

Default value for unspecified map locations including areas outside the map, specified as a numeric scalar.

If you specify the GetTransformFcn or SetTransformFcn property when creating the object, the default value is updated based on that transformation function. If you create the map with a matrix of values p, the transform function modifies the values before storing.

Data Types: double

GetTransformFcn — Applies transformations to retrieved values

function handle

Applies transformations to values retrieved by the getMapData function, specified as a function handle.

This function handle is called inside the getMapData object function. It can be used to apply a transformation to values retrieved from the map layer. The function definition must have the following format:

modifiedValues = getTransformFcnHandle(map,values,varargin)

The size of the output modifiedValues must match the size of the input values. The function provides all map data accessed from the getMapData object function to this transform function through the varargin inputs.

You can set this property when you create the object. After you create the object, this property is read-only.

Data Types: function_handle

GridLocationInWorld — Location of the grid in local coordinates

[0 0] (default) | two-element vector | [xWorld yWorld]

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

GridOriginInLocal — Location of the grid in local coordinates

[0 0] (default) | two-element vector | [xLocal yLocal]

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

GridSize — Number of rows and columns in grid

two-element integer-valued vector

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.

This property is set when you create the object based on the first two dimensions of the input matrix p, the inputs width and height, or the inputs row and col.

Data Types: double

LayerName — Name of layer

'mapLayer' (default) | character vector | string scalar

Name of map layer, specified as a character vector or string scalar.

You can set this property when you create the object. After you create the object, this property is read-only.

Data Types: double

LocalOriginInWorld — Location of the local frame in world coordinates

[0 0] (default) | two-element vector | [xWorld yWorld]

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

Resolution — Grid resolution

1 (default) | scalar

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

SetTransformFcn — Applies transformations to set values

function handle

Applies transformations to values set by the setMapData function, specified as a function handle.

This function handle is called inside the setMapData object function. It can be used to apply a transformation to values set in the map layer. The function must have the following syntax:

modifiedValues = setTransformFcnHandle(map,values,varargin)        
        if numel(varargin) == 0
            return; %
        else
          % Custom Code
        end
end

The size of the output, modifiedValues, must match the size of the input, values. The function provides all map data specified in the setMapData object function to this transform function. When creating this object without starting values, the function is called without additional input arguments, so specify an if-statement to return when the number of elements in varagin is zero.

You can set this property when you create the object. After you create the object, this property is read-only.

Data Types: function_handle

XLocalLimits — Minimum and maximum values of x-coordinates in local frame

two-element vector

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

YLocalLimits — Minimum and maximum values of y-coordinates in local frame

two-element vector

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

XWorldLimits — Minimum and maximum world range values of x-coordinates

two-element vector

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

YWorldLimits — Minimum and maximum world range values of y-coordinates

two-element vector

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

getMapData	Retrieve data from map layer
grid2local	Convert grid indices to local coordinates
grid2world	Convert grid indices to world coordinates
local2grid	Convert local coordinates to grid indices
local2world	Convert local coordinates to world coordinates
move	Move map in world frame
setMapData	Assign data to map layer
syncWith	Sync map with overlapping map
world2grid	Convert world coordinates to grid indices
world2local	Convert world coordinates to local coordinates

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.

Limitations

• mapLayer objects can only belong to one multiLayerMap object at a time.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

• The LayerName property must be fixed at compile-time

• The DataType property must be known at compile-time.

As of MATLAB^® R2022a, default map behavior during code generation has changed, which may result in backwards compatibility issues. Maps such as mapLayer now support fixed-size code generation (DynamicMemoryAllocation="off").

1. Maps that are either default-constructed or constructed with compile-time constant size information (or matrices that are of compile-time constant size) produce fixed-size maps.

2. To restore the previous behavior, use the coder.ignoreConst (MATLAB Coder) function when specifying size inputs, or coder.varsize (MATLAB Coder) matrix variable name specified as a string scalar or character vector, prior to constructing the map.

Version History

Introduced in R2021a