GRDGRADIENT(1) Generic Mapping Tools GRDGRADIENT(1)NAMEgrdgradient - Compute directional derivative or gradient from 2-D grid
file representing z(x,y)
SYNOPSISgrdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [ -D[c][o][n] ]
[ -E[s|p]azim/elev[/ambient/diffuse/specular/shine] ] [ -Lflag ] [ -M ]
[ -N[e][t][amp][/sigma[/offset]] ] [ -Sslopefile ] [ -V ]
DESCRIPTIONgrdgradient may be used to compute the directional derivative 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 grid file from which to compute directional derivative.
(See GRID FILE FORMATS below).
-G Name of the output grid file for the directional derivative.
(See GRID FILE FORMATS below).
OPTIONS
No space between the option flag and the associated arguments.
-A 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).
-D Find the up-slope 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 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 orientation of lineated features).
-E 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. azim and
elev are the azimuth and elevation of light vector. Optionally,
supply ambient diffuse specular shine which are parameters that
control the reflectance properties of the surface. Default val‐
ues are: 0.55/ 0.6/0.4/10 To leave some of the values untouched,
specify = as the new value. For example -E60/30/=/0.5 sets the
azim elev and diffuse to 60, 30 and 0.5 and leaves the other
reflectance parameters untouched. Append s to use a simpler
Lambertian algorithm. Note that with this form you only have to
provide the azimuth and elevation parameters. Append p to use
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 val‐
ues they will be ignored.)
-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 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
- offset)). -Ne normalizes using a cumulative Laplace distri‐
bution yielding gn = amp * (1.0 - exp(sqrt(2) * (g - offset)/
sigma)) where sigma is estimated using the L1 norm of (g - off‐
set) 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.
-S Name of output grid file with scalar magnitudes of gradient vec‐
tors. Requires -D but makes -G optional.
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
HINTS
If you don't know what OPT(N) options to use to make an intensity file
for grdimage or grdview, a good first try is -Ne 0.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.
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 facili‐
tates so called "packing" of grids, writing out floating point data as
2- or 4-byte integers. To specify the precision, scale and offset, the
user should add the suffix =id[/scale/offset[/nan]], where id is a two-
letter identifier of the grid type and precision, and scale and offset
are optional scale factor and offset to be applied to all grid values,
and nan is the value used to indicate missing data. When reading
grids, the format is generally automatically recognized. If not, the
same suffix can be added to input grid file names. See grdreformat(1)
and Section 4.17 of the GMT Technical Reference and Cookbook for more
information.
When reading a netCDF file that contains multiple grids, GMT will read,
by default, the first 2-dimensional grid that can find in that file. To
coax GMT into reading another multi-dimensional variable in the grid
file, append ?varname to the file name, where varname is the name of
the variable. Note that you may need to escape the special meaning of ?
in your shell program by putting a backslash in front of it, or by
placing the filename and suffix between quotes or double quotes. The
?varname suffix can also be used for output grids to specify a variable
name different from the default: "z". See grdreformat(1) and Section
4.18 of the GMT Technical Reference and Cookbook for more information,
particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
EXAMPLES
To make a file for illuminating the data in geoid.grd using exp- nor‐
malized gradients imitating light sources in the north and west direc‐
tions:
grdgradient geoid.grd -A 0/270 -G gradients.grd -Ne0.6 -V
To find the azimuth orientations of seafloor fabric in the file
topo.grd:
grdgradient topo.grd -Dno -G azimuths.grd -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://peo‐
ple.csail.mit.edu/ bkph/papers/Hill-Shading.pdf)
SEE ALSOGMT(1), gmtdefaults(1), grdhisteq(1), grdimage(1), grdview(1), grdvec‐
tor(1)GMT 4.5.14 1 Nov 2015 GRDGRADIENT(1)
