NAME
grdgradient - Compute directional gradients from 2-D grd
files
SYNOPSIS
grdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [ -
Dslopefile ] [ -M ] [ -N[e][t][amp][/sigma] ] [ -S[a][o][n]
] [ -V ]
DESCRIPTION
grdgradient may be used to compute the directional deriva-
tive of a grdfile representing z(x,y). The program finds
-[dz/dx*sin(azim) + dz/dy* cos(azim)], where azim is an
angle (in degrees) in the x,y plane measured positive clock-
wise from north (the y axis) toward east (the x axis). The
derivative is negated so that grdgradient will give positive
values when the slope of z(x,y) is downhill in the azim
direction. The reason for this is that most applications
for grdgradient are in shading the illumination of an image
(see grdimage and grdview), and if we take the light source
to be above the x,y plane then slopes which are downhill
toward the light source are bright (positive) while slopes
which are uphill toward the light source are dark (nega-
tive).
grdgradient can also find the direction and magnitude of the
gradient of the data set and save directions or azimuths
(and optionally magnitudes).
No space between the option flag and the associated
arguments. Use upper case for the option flags and lower
case for modifiers.
in_grdfile
2-D grd file from which to compute directional deriva-
tive.
-G Name of the output grdfile with directional deriva-
tive.
OPTIONS
-A Azimuthal direction. azim is the angle (in degrees)
in the x,y plane measured positive clockwise from north
(the y axis) toward east (the x axis). There is an
option to supply two azimuths, -Aazim/azim2. In this
case, the gradients in each of these directions will be
calculated, and the one which is larger in magnitude
will be retained. This can be useful for illuminating
complex areas.
-D Name of output grdfile with gradient magnitudes.
Requires -S.
- M By default the units of grdgradient are in
units_of_z/units_of_dx_and_dy. However, the user may
choose this option to convert dx,dy in degrees of
longitude,latitude into meters, so that the units of
grdgradient are in z_units/meter.
-N This option will scale and offset all the actual gra-
dient values by a constant scale and offset so that the
maximum absolute value of the output is amp. By
default, no normalization is done. If -N or -Ne or -Nt
is chosen without setting the value of amp, then the
default amplitude is 1.0. If -Ne is chosen the gra-
dients will be transformed using a two-sided exponen-
tial (Laplace) distribution function as amp * (1.0 -
exp(sqrt(2) * (g - m)/sigma)), where g is the gradient
and m is the mean gradient. If sigma is not supplied
by the user, it will be estimated using the L1 norm
estimate of standard deviation. If -Nt is chosen, then
the gradients are adjusted to be (2 * amp / PI) * atan(
(g - m)/sigma), where g is the gradient and m is the
mean gradient. If sigma is not supplied by the user,
it will be estimated using the sample standard devia-
tion. Hints: When making several small maps from one
large data set, use the option to supply a user-defined
sigma so that the illumination effects are consistent
across all the maps. If you are trying to make an
intensity file for grdimage or grdview for the first
time and you don't know what to use, a good first start
is -Ne0.6.
-S Find the direction of the gradient of the data. By
default, the directions are measured counterclockwise
from the horizontal. Append a to use azimuths clock-
wise from north instead, append o to report orientation
(0-180) rather than direction (0-360) of gradient, and
append n to add 90 degrees to all angles (e.g., to give
orientation of lineated features).
-V Selects verbose mode, which will send progress reports
to stderr [Default runs "silently"].
EXAMPLES
To find the atan-normalized directional derivative of the
file geoid.grd in the north direction, do
grdgradient geoid.grd -A0 -Ggradients.grd -Nt -V
To find the azimuth orientations of seafloor fabric in the
file topo.grd, try
grdgradient topo.grd -Snao -Gazimuths.grd -V
To get the gradient of the scalar field z.grd we take the
gradient in the negative x- and y-directions (because of the
sign convention above) and obtain the two components of grad
(z) which can be plotted with grdvector:
grdgradient z.grd -A270 -Gdzdx.grd
grdgradient z.grd -A180 -Gdzdy.grd
SEE ALSO
gmt, gmtdefaults, grdhisteq, grdimage, grdview, grdvector
REFERENCES
Wessel, P., and W. H. F. Smith, 1995, The Generic Mapping
Tools (GMT) version 3.0 Technical Reference & Cookbook,
SOEST/NOAA.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released, EOS Trans. AGU, 76, p. 329.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released,
http://www.agu.org/eos_elec/95154e.html, Copyright 1995 by
the American Geophysical Union.
Wessel, P., and W. H. F. Smith, 1991, Free Software Helps
Map and Display Data, EOS Trans. AGU, 72, p. 441.