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

example

````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 a new object using the occupancy data copied from another `signedDistanceMap` object.```
````map = signedDistanceMap(sourcemap,resolution)` creates a new object using the occupancy data copied from another `signedDistanceMap` object but resamples the matrix to have the specified resolution `resolution`. The `Resolution` property is set to `resolution`.```

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

expand all

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

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

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

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

Map matrix, specified as a M-by-N matrix, where each cell contains `1` for occupied and `0` for unoccupied.

Signed distance map to copy values from, specified as a `signedDistanceMap` object.

Properties

expand all

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`

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

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`

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.

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.

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

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 `

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.

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.

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.

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.

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.

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

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