signedDistanceMap

Discrete signed distance map of 2-D region

Since R2023a

Description

Use the signedDistanceMap object to represent distances to surfaces or contours in space using signed distance functions. Query points return positive values if they lie outside an occupied region of space and negative if they lie inside a space. This map object also provides gradient information and the location to nearest occupied cell in the scene.

Creation

Syntax

map = signedDistanceMap

map = signedDistanceMap(width,height)

map = signedDistanceMap(width,height,resolution)

map = signedDistanceMap(width,height,resolution,"world")

map = signedDistanceMap(rows,cols,resolution,"grid")

map = signedDistanceMap(mapmatrix)

map = signedDistanceMap(mapmatrix,resolution)

map = signedDistanceMap(sourcemap)

map = signedDistanceMap(sourcemap,resolution)

map = signedDistanceMap(___,Name=Value)

Description

Dimensions

map = signedDistanceMap creates an empty 2-D signed distance map object occupying 10-by-10 meters of space with a resolution of 1 cell per meter.

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

map = signedDistanceMap(width,height,resolution) creates a map with the specified width width, and height height with a resolution of resolution cell per meter. The Resolution property is set to resolution.

map = signedDistanceMap(width,height,resolution,"world") creates a map with a grid size of width-by-height in world coordinates. The Resolution property is set to resolution.

map = signedDistanceMap(rows,cols,resolution,"grid") creates a map with a grid size of rows-by-cols in grid coordinates. The Resolution property is set to resolution.

Other Maps

map = signedDistanceMap(mapmatrix) creates a map of the same size and value as the matrix mapmatrix.

map = signedDistanceMap(mapmatrix,resolution) creates a map from the values in the matrix or matrix array mapmatrix with a resolution resolution. The Resolution property is set to resolution.

map = signedDistanceMap(sourcemap) creates an object using values from another map object. Note that converting from a probabilistic map representation such as an occupancy map to a binary map representation such as a signed distance map may cause some loss of information due to differences in how occupancy values are encoded.

map = signedDistanceMap(sourcemap,resolution) creates a new object using the occupancy data copied from another map object but resamples the matrix to have the specified resolution resolution. The Resolution property is set to resolution.

Additional Options

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

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

Input Arguments

width — Width of map

10 (default) | nonnegative numeric scalar

Width of map, specified as nonnegative numeric scalar, in meters.

height — Height of map

nonnegative numeric scalar

Height of map, specified as nonnegative numeric scalar, in meters.

rows — Number of rows in map

nonnegative numeric scalar

Number of rows in map, specified as nonnegative numeric scalar.

cols — Number of columns in map

10 (default) | nonnegative numeric scalar

Number of columns in map, specified as nonnegative numeric scalar.

mapmatrix — Occupancy map matrix

M-by-N binary-valued matrix

Occupancy map matrix, specified as a M-by-N binary-valued matrix, where each cell contains 1 for occupied and 0 for unoccupied.

sourcemap — Map to convert from

signedDistanceMap object | occupancyMap object | binaryOccupancyMap object

Map to convert from, specified as a signedDistanceMap, occupancyMap, or binaryOccupancyMap object.

Properties

DataType — Data type of the values stored

'logical' (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.

InterpolationMethod — Interpolation method for distance matrix

"linear" (default) | "none"

Interpolation method for distance matrix, specified as a string scalar:

• "none" — Distance is constant within cells. The gradient is NaN.

• "linear" — Bilinearly interpolate distance. The gradient is piecewise continuous between cell-centers.

Data Types: char | string

GridLocationInWorld — Location of bottom-left corner of grid in world 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.

GridOriginInLocal — Location of bottom-left corner of 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.

GridSize — Number of rows and columns in grid

two-element integer-valued vector

Number of rows and columns in grid, stored as a two-element integer-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 mapmatrix, the inputs width and height, or the inputs row and col.

LayerName — Name of map layer

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

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

You can set this property as a name-value argument when you create the object. After you create the object, this property is read-only.

Data Types: char | string

LocalOriginInWorld — Location of local frame origin in world coordinates

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

Location of the local frame origin 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 as a name-value argument when you create the object.

Resolution — Grid resolution

Read-only: 1 (default) | positive numeric scalar

This property is read-only.

Grid resolution, specified as a positive numeric scalar in cells per meter representing the number and size of grid locations.

You can set this property as a name-value argument when you create the object. After you create the object, this property is read-only.

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

Read-only: two-element row vector

This property is read-only.

Minimum and maximum values of x-coordinates in the local frame, stored as a two-element row vector of the form [min max]. Local frame is defined by the LocalOriginInWorld property.

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

Read-only: two-element row vector

This property is read-only.

Minimum and maximum values of y-coordinates in the local frame, stored as a two-element row vector of the form [min max]. Local frame is defined by the LocalOriginInWorld property.

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

Read-only: two-element row vector

This property is read-only.

Minimum and maximum values of x-coordinates of the world frame, stored as a two-element row vector representing the minimum and maximum values, in that order.

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

Read-only: two-element row vector

This property is read-only.

Minimum and maximum values of y-coordinates of the world frame, stored as a two-element row vector representing the minimum and maximum values, in that order.

Object Functions

copy	Create copy of 2-D signed distance map
closestBoundary	Get nearest boundary to location
distance	Get distance at locations
getMapData	Retrieve data from map layer
gradient	Get gradient at locations
grid2world	Convert grid indices to world coordinates
grid2local	Convert grid indices to local 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
show	Display signed distance map
syncWith	Sync map with overlapping map
world2grid	Convert world coordinates to grid indices
world2local	Convert world coordinates to local coordinates

Examples

Get Distance to Nearest Obstacles in Signed Distance Map

Load the exampleMaps MAT file.

load exampleMaps.mat

Create a signed distance map using the simpleMap data.

sdm = signedDistanceMap(simpleMap,InterpolationMethod="none");
show(sdm,BoundaryColor=[0 0 0],Colorbar="on");

setMapData(sdm,[7 1],zeros(5,5))
getMapData(sdm,[9 2])

ans = logical
   0

show(sdm,BoundaryColor=[0 0 0],Colorbar="on");

Find the closest boundary to the coordinate, [16.25 6.25] and calculate the distance to the nearest boundary.

coord = [16.25 6.25];
boundary = closestBoundary(sdm,coord,"world")

boundary = 
boundary(:,:,1) =

   20.5000


boundary(:,:,2) =

    6.5000

dist = distance(sdm,coord)

dist = 
4

Plot the line between the queried point and the closest obstacle cell center.

hold on
plot([coord(1) boundary(:,:,1)],[coord(2) boundary(:,:,2)],"-r",Marker=".",MarkerSize=10)

Note that even though distance from the queried point appears greater than 4 when plotted, the distance function calculates the distance from the nearest cell center of the queried point.

Version History

Introduced in R2023a

R2026a: Map conversion support

You can now convert between occupancyMap, binaryOccupancyMap, and signedDistanceMap objects,

For example, this code shows the creation of an binaryOccupancyMap object and the conversion to occupancyMap and signedDistanceMap objects.

binOccMap = binaryOccupancyMap(10,10);
occMap = occupancyMap(binOccMap);
sdMap = signedDistanceMap(binOccMap);

Note that converting from a probabilistic map representation such as an occupancyMap to a binary map representation such as a binaryOccupancyMap or a signedDistanceMap may cause some loss of information, since continuous probabilistic values in the range [0, 1] are reduced to logical values of only 0 or 1.

R2026a: Move and sync between different map representations

You can now move and sync between the occupancyMap, binaryOccupancyMap, and signedDistanceMap objects using the move and syncWith object functions.

For example, this code shows how to move and sync with different map representations.

% Create map respresentations
worldOccMap = occupancyMap(100,100);
localBinOccMap = binaryOccupancyMap(10,20,Resolution=2);
localSDMap = signedDistanceMap(10,20,Resolution=2.5);

% Sync the local binary occupancy map to the world occupancy map
syncWith(localBinOccMap,worldOccMap)

% Move and sync the local signed distance map to the world occupancy map at
% desired location
gridLoc = [15 30];
move(localSDMap,gridLoc,SyncWith=worldOccMap);