Discrete signed distance map of 2-D region
Since R2023a
expand all in page
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
map = signedDistanceMap(width,height)width, and height height with a resolution of 1 cell per meter.
map = signedDistanceMap(width,height,resolution)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")width-by-height in world coordinates. The Resolution property is set to resolution.
map = signedDistanceMap(rows,cols,resolution,"grid")rows-by-cols in grid coordinates. The Resolution property is set to resolution.
Other Maps
example
map = signedDistanceMap(mapmatrix)mapmatrix.
map = signedDistanceMap(mapmatrix,resolution)mapmatrix with a resolution resolution. The Resolution property is set to resolution.
map = signedDistanceMap(sourcemap)signedDistanceMap object.
map = signedDistanceMap(sourcemap,resolution)signedDistanceMap object but resamples the matrix to have the specified resolution resolution. The Resolution property is set to resolution.
Additional Options
map = signedDistanceMap(___,Name=Value)
For example, signedDistanceMap(__,LocalOriginInWorld=[15 20]) sets the local origin to a specific world location.
Input Arguments
expand all
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 — Signed distance map to copy values from
signedDistanceMap object
Signed distance map to copy values from, specified as a signedDistanceMap object.
Properties
expand all
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 isNaN."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
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
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
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
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
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
collapse all
Get Distance to Nearest Obstacles in Signed Distance Map
Open Live Script
Load the exampleMaps MAT file.
load exampleMaps.matCreate 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 0show(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.5000boundary(:,:,2) = 6.5000
dist = distance(sdm,coord)
dist = 4
Plot the line between the queried point and the closest obstacle cell center
hold onplot([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
See Also
Objects
- multiLayerMap | occupancyMap3D | occupancyMap | binaryOccupancyMap
Functions
- distance | getMapData | setMapData | move | syncWith
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Contact your local office
