gradient

Get gradient at locations

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.

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.

Note

When the cornerLoc and mapSize are specified, gradient computes gradients at cell centers within the rectangular query region.

Examples

Calculate Gradients using Signed Distance Map

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

Calculate gradient for cells in top-left quadrant.

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

map — Signed distance map

signedDistanceMap object

Signed distance map, specified as a signedDistanceMap object.

location — World or local coordinates, or grid locations

N-by-2 matrix

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

cornerLocation — Location of output matrix

two-element vector

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

mapSize — Subregion map size

two-element vector | [x y]

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

frame — Coordinate frame

"world" (default) | "local" | "grid"

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

grad — xy-gradients

L-by-1-by-2 array | M-by-N-by-2 array

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.

The x-gradients and y-gradients are the first and second page, respectively.

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.

isValid — Points in boundary

L-element vector

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.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2023a