grdgradient - Compute directional derivative or gradient from a
grid
grdgradient in_grdfile -Gout_grdfile [
-Aazim[/azim2] ] [
-D[a][c][o][n] ] [
-E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]
] [ -Lflag ] [
-N[e|t][amp][+ssigma][+ooffset]
] [ -Rregion ] [ -Sslopefile ] [
-V[level] ] [ -fg ] [ -nflags ]
Note: No space is allowed between the option flag and the
associated arguments.
grdgradient may be used to compute the directional
derivative in a given direction (-A), or to find the direction
(-S) [and the magnitude (-D)] of the vector gradient of the
data.
Estimated values in the first/last row/column of output depend on
boundary conditions (see -L).
- in_grdfile
- 2-D grid file from which to compute directional derivative. (See GRID FILE
FORMATS below).
- -Gout_grdfile
- Name of the output grid file for the directional derivative. (See GRID
FILE FORMATS below).
- -Aazim[/azim2]
- Azimuthal direction for a directional derivative; azim is the angle
in the x,y plane measured in degrees positive clockwise from north (the +y
direction) toward east (the +x direction). The negative of the directional
derivative, -[dz/dx*sin(azim) + dz/dy*cos(azim)], is found;
negation yields positive values when the slope of z(x,y) is downhill in
the azim direction, the correct sense for shading the illumination
of an image (see grdimage and grdview) by a light source above the x,y
plane shining from the azim direction. Optionally, supply two
azimuths, -Aazim/azim2, in which case the gradients
in each of these directions are calculated and the one larger in magnitude
is retained; this is useful for illuminating data with two directions of
lineated structures, e.g., -A0/270 illuminates from
the north (top) and west (left). Finally, if azim is a file it must
be a grid of the same domain, spacing and registration as
in_grdfile and we will update the azimuth at each output node when
computing the directional derivatives.
- -D[a][c][o][n]
- Find the direction of the positive (up-slope) gradient of the data. To
instead find the aspect (the down-slope direction), use -Da. By
default, directions are measured clockwise from north, as azim in
-A above. Append c to use conventional Cartesian angles
measured counterclockwise from the positive x (east) direction. Append
o to report orientations (0-180) rather than directions (0-360).
Append n to add 90 degrees to all angles (e.g., to give local
strikes of the surface ).
- -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]
- Compute Lambertian radiance appropriate to use with grdimage and grdview.
The Lambertian Reflection assumes an ideal surface that reflects all the
light that strikes it and the surface appears equally bright from all
viewing directions. Here, azim and elev are the azimuth and
elevation of the light vector. Optionally, supply ambient [0.55],
diffuse [0.6], specular [0.4], or shine [10], which
are parameters that control the reflectance properties of the surface.
Default values are given in the brackets. Use -Es for a simpler
Lambertian algorithm. Note that with this form you only have to provide
azimuth and elevation. Alternatively, use -Ep for the Peucker
piecewise linear approximation (simpler but faster algorithm; in this case
the azim and elev are hardwired to 315 and 45 degrees. This
means that even if you provide other values they will be ignored.)
- -Lflag
- Boundary condition flag may be x or y or xy
indicating data is periodic in range of x or y or both, or flag may
be g indicating geographical conditions (x and y are lon and lat).
[Default uses "natural" conditions (second partial derivative
normal to edge is zero).]
- -N[e|t][amp][+ssigma][+ooffset]
- Normalization. [Default is no normalization.] The actual gradients
g are offset and scaled to produce normalized gradients gn
with a maximum output magnitude of amp. If amp is not given,
default amp = 1. If offset is not given, it is set to the
average of g. -N yields gn = amp * (g -
offset)/max(abs(g - offset)). -Ne normalizes
using a cumulative Laplace distribution yielding gn = amp *
(1.0 - exp(sqrt(2) * (g - offset)/ sigma)), where
sigma is estimated using the L1 norm of (g - offset)
if it is not given. -Nt normalizes using a cumulative Cauchy
distribution yielding gn = (2 * amp / PI) * atan( (g
- offset)/ sigma) where sigma is estimated using the
L2 norm of (g - offset) if it is not given.
- -Rxmin/xmax/ymin/ymax[+r][+uunit]
(more ...)
- Specify the region of interest. Using the -R option will select a
subsection of in_grdfile grid. If this subsection exceeds the
boundaries of the grid, only the common region will be extracted.
- -Sslopefile
- Name of output grid file with scalar magnitudes of gradient vectors.
Requires -D but makes -G optional.
- -V[level] (more
...)
- Select verbosity level [c].
- -fg
- Geographic grids (dimensions of longitude, latitude) will be converted to
meters via a "Flat Earth" approximation using the current
ellipsoid parameters.
- -^ or just -
- Print a short message about the syntax of the command, then exits (NOTE:
on Windows just use -).
- -+ or just +
- Print an extensive usage (help) message, including the explanation of any
module-specific option (but not the GMT common options), then exits.
- -? or no arguments
- Print a complete usage (help) message, including the explanation of all
options, then exits.
If the grid does not have meter as the horizontal unit, append
+uunit to the input file name to convert from the specified
unit to meter. If your grid is geographic, convert distances to meters by
supplying -fg instead.
If you don't know what -N options to use to make an
intensity file for grdimage or grdview, a good first try is
-Ne0.6.
Usually 255 shades are more than enough for visualization
purposes. You can save 75% disk space by appending =nb/a to the output
filename out_grdfile.
If you want to make several illuminated maps of subregions of a
large data set, and you need the illumination effects to be consistent
across all the maps, use the -N option and supply the same value of
sigma and offset to grdgradient for each map. A good
guess is offset = 0 and sigma found by grdinfo -L2 or
-L1 applied to an unnormalized gradient grd.
If you simply need the x- or y-derivatives of the
grid, use grdmath.
By default GMT writes out grid as single precision floats in a
COARDS-complaint netCDF file format. However, GMT is able to produce grid
files in many other commonly used grid file formats and also facilitates so
called "packing" of grids, writing out floating point data as 1-
or 2-byte integers. (more ...)
To make a file for illuminating the data in geoid.nc using exp-
normalized gradients in the range [-0.6,0.6] imitating light sources in the
north and west directions:
gmt grdgradient geoid.nc -A0/270 -Ggradients.nc=nb/a -Ne0.6 -V
To find the azimuth orientations of seafloor fabric in the file
topo.nc:
gmt grdgradient topo.nc -Dno -Gazimuths.nc -V
Horn, B.K.P., Hill-Shading and the Reflectance Map, Proceedings of
the IEEE, Vol. 69, No. 1, January 1981, pp. 14-47.
(http://people.csail.mit.edu/bkph/papers/Hill-Shading.pdf)
gmt, gmt.conf grdhisteq, grdinfo, grdmath, grdimage, grdview,
grdvector
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F.
Wobbe