NAME
grdgradient - Compute directional derivative or gradient
from 2-D grd file representing z(x,y)
SYNOPSIS
grdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [
-D[c][o][n] ] [ -Lflag ] [ -M ] [
-N[e][t][amp][/sigma[/offset]] ] [ -Sslopefile ] [ -V ]
DESCRIPTION
grdgradient may be used to compute the directional deriva-
tive in a given direction (-A), or 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 grd file from which to compute directional deriva-
tive.
-G Name of the output grdfile for the directional deriva-
tive.
OPTIONS
No space between the option flag and the associated
arguments. Use upper case for the option flags and lower
case for modifiers.
-A Azimuthal direction for a directional derivative; azim
is the angle in the x,y plane measured in degrees posi-
tive clockwise from north (the +y direction) toward
east (the +x direction). The negative of the direc-
tional 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 illumina-
tion of an image (see grdimage and grdview) by a light
source above the x,y plane shining from the azim direc-
tion. 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).
-D Find the direction of the gradient of the data. By
default, the directions are measured clockwise from
north, as azim in -A above. Append c to use conven-
tional 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
orientation of lineated features).
-L 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).]
-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 Normalization. [Default: 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 normal-
izes 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.
-S Name of output grdfile with scalar magnitudes of gra-
dient vectors. Requires -D.
-V Selects verbose mode, which will send progress reports
to stderr [Default runs "silently"].
HINTS
If you don't know what -N options to use to make an inten-
sity file for grdimage or grdview, a good first try is
-Ne0.6.
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.
EXAMPLES
To make a file for illuminating the data in geoid.grd using
exp-normalized gradients imitating light sources in the
north and west directions, do
grdgradient geoid.grd -A0/270 -Ggradients.grd -Ne0.6 -V
To find the azimuth orientations of seafloor fabric in the
file topo.grd, try
grdgradient topo.grd -Snao -Gazimuths.grd -V
SEE ALSO
gmt(l), gmtdefaults(l), grdhisteq(l), grdimage(l),
grdview(l), grdvector(l)