Since R2023a

## Syntax

``grad = gradient(map)``
``grad = gradient(map,location)``
``grad = gradient(map,location,frame)``
``[grad,isValid] = gradient(map,location,___)``
``grad = gradient(map,cornerLocation,mapSize)``
``grad = gradient(map,cornerLocation,mapSize,frame)``

## Description

````grad = gradient(map)` returns the xy-gradients `grad` for the specified signed distance map `map`.```
````grad = gradient(map,location)` returns an array of gradients for the specified xy-locations `location` in world coordinates.```

example

````grad = gradient(map,location,frame)` returns an array of gradient values for the specified locations `location`, in the coordinate frame `frame`.```
````[grad,isValid] = gradient(map,location,___)` returns `isValid`, indicating which of the specified locations `location` are within the map bounds `isValid`.```
````grad = gradient(map,cornerLocation,mapSize)` returns a matrix of values in a subregion of the map layer, `map`. The subregion starts in the corner location `cornerLocation` in the world coordinate frame with a given map size `mapSize`.```
````grad = gradient(map,cornerLocation,mapSize,frame)` returns a matrix of distances in a subregion of the map layer, `map`. The subregion starts in the corner location `cornerLocation` in the coordinate frame `frame` with a given map size `mapSize`. NoteWhen the `cornerLoc` and `mapSize` are specified, `gradient` computes gradients at cell centers within the rectangular query region. ```

## Examples

collapse all

Create a linearly interpolated map.

`map = signedDistanceMap(InterpolationMethod="linear");`

Set the map data to an identity matrix to set the main diagonal of the map to occupied.

`setMapData(map,eye(10));`

Set top left quadrant as occupied.

`setMapData(map,[0 5],true(5));`

Calculate gradient in each corner cell of map.

```queryIJ = [1 1; 1 10; 10 1; 10 10]; gradientAtCornerCell = gradient(map,queryIJ,"grid")```
```gradientAtCornerCell = gradientAtCornerCell(:,:,1) = 1 0 1 -1 gradientAtCornerCell(:,:,2) = 1 1 0 -1 ```

`gradientInQuadrant = gradient(map,[0 5],[5 5])`
```gradientInQuadrant = gradientInQuadrant(:,:,1) = 1.0000 1.0000 1.0000 1.0000 1.0000 0 0.5000 1.0000 1.0000 1.0000 0 0 0.5000 1.0000 1.0000 0 0 0 0.5000 1.0000 0 0 0 0 0.5000 gradientInQuadrant(:,:,2) = -1.0000 0 0 0 0 -1.0000 -0.5000 0 0 0 -1.0000 -1.0000 -0.5000 0 0 -1.0000 -1.0000 -1.0000 -0.5000 0 -1.0000 -1.0000 -1.0000 -1.0000 -0.5000 ```

Display gradient vectors over the map.

`show(map,BoundaryColor=[0 0 0],VectorField="Gradient");` ## Input Arguments

collapse all

Signed distance map, specified as a `signedDistanceMap` object.

World or local coordinates, or grid locations, specified as an N-by-2 matrix. N is the number of locations. The format of the rows depends on the value of the `frame` argument:

• `"world"` — [x y] coordinates in the world frame.

• `"local"` — [x y] coordinates in the local frame.

• `"grid"` — [row column] location in the grid frame.

Data Types: `double`

Location of output matrix, specified as a two-element vector of coordinates in the form, [x y]. The location is in world or local coordinates if the `frame` argument is set to `"world"` and `"local"`, respectively. When `frame` is `"grid"`, `cornerLocation` is the top-left corner of the world frame.

Data Types: `double`

Subregion map size, specified as a two-element vector [x y] in world or local coordinates. Location is in world or local coordinates if the `frame` argument is set to `"world"` and `"local"`, respectively. When `frame` is `"grid"`, `cornerLocation` is the top-left corner of the world frame.

Data Types: `double`

Coordinate frame, specified as one of these options:

• `"world"` — Specify coordinates in the world frame.

• `"local"` — Specify coordinates in the local frame.

• `"grid"` — Specify grid locations in the grid frame.

Data Types: `char` | `string`

## Output Arguments

collapse all

xy-gradients, returned as an L-by-1-by-2 array for location queries and an M-by-N-by-2 array for subregion queries. L is the number of locations queried. M and N are the dimensions of the map or specified map subregion.

If `frame` is either `"world"` or `"local"`, then `gradient` returns gradients in Cartesian space.

If `frame` is `"grid"`, then `gradient` returns gradients in grid space.

Points in boundary, returned as an L-element vector, where L is the total number of queried locations. Each element is a `1` (`true`) if the point is within the boundaries, and `0` (`false`) if the point is outside boundaries.

This output is only returned for point queries.

## Version History

Introduced in R2023a