grdgradient(1) GMT grdgradient(1)
NAME
grdgradient - Compute directional derivative or gradient from a grid
SYNOPSIS
grdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [
-D[a][c][o][n] ] [ -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecu-
lar][+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.
DESCRIPTION
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).
REQUIRED ARGUMENTS
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).
OPTIONAL ARGUMENTS
-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 cor-
rect sense for shading the illumination of an image (see grdim-
age 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 direc-
tions 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 Carte-
sian 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 lin-
ear 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 anaturala conditions (second partial derivative normal to
edge is zero).]
-N[e|t][amp][+ssigma][+ooffset]
Normalization. [Default is no normalization.] The actual gradi-
ents 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 aver-
age of g. -N yields gn = amp * (g - offset)/max(abs(g - off-
set)). -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 distribu-
tion 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 a|)
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 vec-
tors. Requires -D but makes -G optional.
-V[level] (more a|)
Select verbosity level [c].
-fg Geographic grids (dimensions of longitude, latitude) will be
converted to meters via a aFlat Eartha approximation using the
current ellipsoid parameters.
-n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more a|)
Select interpolation mode for grids.
-^ 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 explana-
tion 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.
GRID DISTANCE UNITS
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.
HINTS
If you donat 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.
GRID FILE FORMATS
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 apackinga of grids, writing out floating point
data as 1- or 2-byte integers. (more a|)
EXAMPLES
To make a file for illuminating the data in geoid.nc using exp- normal-
ized 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
REFERENCES
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)
SEE ALSO
gmt(1), gmt.conf(5), grdhisteq(1), grdinfo(1), grdmath(1), grdimage(1),
grdview(1), grdvector(1)
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 grdgradient(1)
gmt5 5.4.2 - Generated Wed Jun 28 18:28:29 CDT 2017