gradientm

Gradient, slope, and aspect of data grid

Syntax

[aspect,slope,gradN,gradE] = gradientm(F,R)

[aspect,slope,gradN,gradE] = gradientm(F,R,spheroid)

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F)

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F,spheroid)

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F,spheroid,angleUnit)

Description

Regular Data Grids

[aspect,slope,gradN,gradE] = gradientm(F,R) returns the aspect angle, slope angle, and north and east components of the gradient for a regular data grid F with respect to a geographic reference R. By default, gradientm locates the latitude and longitude coordinates referenced by R using the spheroid contained in the Spheroid property of the geocrs object in the GeographicCRS property of R. If the GeographicCRS property of R is empty, then geopeaks uses GRS80.

[aspect,slope,gradN,gradE] = gradientm(F,R,spheroid) uses the specified reference spheroid instead of the spheroid contained in the Spheroid property of the geocrs object in the GeographicCRS property of R or the spheroid GRS80.

Geolocated Data Grids

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F) returns the same values for a geolocated data grid F with respect to the latitude-longitude mesh defined by lat and lon. By default, latitude and longitude are in degrees. The default reference spheroid is GRS80.

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F,spheroid) uses the specified reference spheroid instead of GRS80.

[aspect,slope,gradN,gradE] = gradientm(lat,lon,F,spheroid,angleUnit) specifies the units for latitude and longitude as 'degrees' (the default) or 'radians'.

Examples

Calculate and Display Gradient, Slope, and Aspect of Elevation Data

Generate sample elevation data for the region around a mountain summit using a geographic postings reference object and the geopeaks function. To do this, first create a reference object for the region by specifying the latitude and longitude limits and the size of the elevation data grid. Next, generate elevation data for the region using geopeaks.

latlim = [10 45];
lonlim = [60 100];
size = [100 100];
R = georefpostings(latlim,lonlim,size);
F = geopeaks(R);

Compute the aspect angles, slope angles, and gradient components of the data.

[aspect,slope,gradN,gradE] = gradientm(F,R);

Visualize the results by plotting the data. Create a map using an equidistant cylindrical projection and plot the data as a surface. Adjust the aspect ratio of the map by using the daspect function. View the map in 3-D by using the view function.

figure
axesm('eqdcylin');
geoshow(F,R,'DisplayType','surface')
daspect([1 1 5])
title('Elevation Data')
colorbar
view(3)

Then, plot the gradient components using the same projection. Note that both the north and east component values are zero at the summit.

figure
axesm('eqdcylin')
geoshow(gradN,R,'DisplayType','surface')
title('North Components of Gradient')
colorbar

figure
axesm('eqdcylin')
geoshow(gradE,R,'DisplayType','surface')
title('East Components of Gradient')
colorbar

Plot the slope angles. Note that the value of the slope angle is zero at the summit.

figure
axesm('eqdcylin')
geoshow(slope,R,'DisplayType','surface')
title('Slope Angles')
colorbar

Plot the aspect angles. An aspect angle describes the direction the mountain slope faces as an azimuth measured clockwise from north.

figure
axesm('eqdcylin')
geoshow(aspect,R,'DisplayType','surface')
title('Aspect Angles')
colorbar

Input Arguments

F — Data grid

numeric matrix

Data grid, specified as a numeric matrix with at least two rows and two columns. The data grid may contain NaN values. F is either a regular data grid associated with a geographic raster reference object, or a georeferenced data grid with respect to a latitude-longitude mesh.

If F is a regular data grid and R is a reference object, then size(F) must be the same as R.RasterSize. If F is a geolocated data grid, then size(F) must be the same as size(lat) and size(lon).

Data Types: single | double

R — Geographic reference

GeographicCellsReference object | GeographicPostingsReference object

Geographic reference that contains geospatial referencing information for F, specified as a GeographicCellsReference or GeographicPostingsReference object. The RasterSize property of R must be the same as size(F).

spheroid — Reference spheroid

'GRS80' (default) | referenceEllipsoid object | oblateSpheroid object | referenceSphere object | vector

Reference spheroid, specified as a referenceEllipsoid object, oblateSpheroid object, referenceSphere object, or vector of the form [semimajorAxis eccentricity].

For more information about reference spheroids, see Comparison of Reference Spheroids.

Example: spheroid = referenceEllipsoid(wgs84Ellipsoid);

lat — Latitudes

numeric matrix

Latitudes, specified as a numeric matrix with at least two rows and two columns. By default, specify latitudes in degrees. To use values in radians, specify the angleUnit argument as 'radians'.

lat must be the same size as lon and F.

Data Types: single | double

lon — Longitudes

numeric matrix

Longitudes, specified as a numeric matrix with at least two rows and two columns. By default, specify longitudes in degrees. To use values in radians, specify the angleUnit argument as 'radians'.

lon must be the same size as lat and F.

Data Types: single | double

angleUnit — Angle units

'degrees' (default) | 'radians'

Angle units, specified as 'degrees' (the default) or 'radians'.

Output Arguments

aspect — Aspect angles

matrix

Aspect angles, returned as a matrix of the same size as F. An aspect angle is the direction in which F decreases most rapidly, expressed as an azimuth measured clockwise from north.

By default, aspect angles are in degrees. To return values in radians, specify lat and lon in radians and angleUnit as 'radians'.

If both components of the gradient are zero, then the aspect angle is returned as NaN.

Data Types: double

slope — Slope angles

matrix

Slope angles, returned as a matrix of the same size as F. For the slope angles to have physical meaning, the data grid must specify elevation, and its distance unit must match the length unit of the reference spheroid. Otherwise, a slope angle is the arctangent of the magnitude of the gradient.

By default, slope angles are in degrees. To return values in radians, specify lat and lon in radians and angleUnit as 'radians'.

Data Types: double

gradN — North components of gradient

matrix

North components of the gradient, returned as a matrix of the same size as F. The north component of a gradient is the change in R per unit of distance in the north direction, where the distance unit matches the length unit of the reference spheroid.

Data Types: double

gradE — East components of gradient

matrix

East components of the gradient, returned as a matrix of the same size as F. The east component of a gradient is the change in R per unit of distance in the east direction, where the distance unit matches the length unit of the reference spheroid.

Data Types: double

Version History

Introduced before R2006a

R2024b: gradientm does not accept referencing vectors or referencing matrices as input

The gradientm function does not accept referencing vectors or referencing matrices as input. Use a geographic raster reference object, specified as a GeographicCellsReference or GeographicPostingsReference object, as input instead. Reference objects have several advantages over referencing vectors and referencing matrices.

• Unlike referencing vectors and referencing matrices, reference objects have properties that document the size of the associated raster, its geographic limits, and the direction of its rows and columns.

• You can manipulate the limits of geographic rasters associated with reference objects using the geocrop function.

• You can manipulate the size and resolution of geographic rasters associated with reference objects using the georesize function.

To update your code, create a geographic reference object.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing vector to a geographic reference object by using the refvecToGeoRasterReference function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the referencing vector or referencing matrix in your code with the reference object.

R2023b: gradientm will not accept referencing vectors or referencing matrices as input

When you specify a referencing vector or referencing matrix as input, the gradientm function issues a warning that it will not accept referencing vectors or referencing matrices as input in a future release.

R2020b: gradientm uses reference ellipsoid information in raster reference objects

When you specify R as a geographic raster reference object, the gradientm function uses the reference ellipsoid within the object. To find the reference ellipsoid for a geographic raster reference object, R, first get its geographic coordinate reference system as a geocrs object. Then, query the Spheroid property of the geocrs object.

g = R.GeographicCRS;
g.Spheroid

To use gradientm with a different spheroid, specify the spheroid argument.