Main Content

gradientm

Gradient, slope, and aspect of data grid

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.

example

[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

collapse all

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)

Figure contains an axes object. The axes object with title Elevation Data contains an object of type surface.

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 contains an axes object. The axes object with title North Components of Gradient contains an object of type surface.

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

Figure contains an axes object. The axes object with title East Components of Gradient contains an object of type surface.

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

Figure contains an axes object. The axes object with title Slope Angles contains an object of type surface.

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

Figure contains an axes object. The axes object with title Aspect Angles contains an object of type surface.

Input Arguments

collapse all

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

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

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);

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

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

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

Output Arguments

collapse all

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

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

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

expand all