1GRDGRADIENT(1) Generic Mapping Tools GRDGRADIENT(1)
2
6 grdgradient - Compute directional derivative or gradient from 2-D grid
7 file representing z(x,y)
8
10 grdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [ -D[c][o][n] ]
11 [ -E[s|p]azim/elev[/ambient/diffuse/specular/shine] ] [ -Lflag ] [ -M ]
12 [ -N[e][t][amp][/sigma[/offset]] ] [ -Sslopefile ] [ -V ]
13
15 grdgradient may be used to compute the directional derivative in a
16 given direction (-A), or the direction (-S) [and the magnitude (-D)] of
17 the vector gradient of the data.
18 Estimated values in the first/last row/column of output depend on
19 boundary conditions (see -L).
20 in_grdfile
22 2-D grid file from which to compute directional derivative.
23 (See GRID FILE FORMATS below).
24 -G Name of the output grid file for the directional derivative.
26 (See GRID FILE FORMATS below).
27
29 No space between the option flag and the associated arguments.
30 -A Azimuthal direction for a directional derivative; azim is the
32 angle in the x,y plane measured in degrees positive clockwise
33 from north (the +y direction) toward east (the +x direction).
34 The negative of the directional derivative, -[dz/dx*sin(azim) +
35 dz/dy*cos(azim)], is found; negation yields positive values when
36 the slope of z(x,y) is downhill in the azim direction, the cor‐
37 rect sense for shading the illumination of an image (see grdim‐
38 age and grdview) by a light source above the x,y plane shining
39 from the azim direction. Optionally, supply two azimuths,
40 -Aazim/azim2, in which case the gradients in each of these
41 directions are calculated and the one larger in magnitude is
42 retained; this is useful for illuminating data with two direc‐
43 tions of lineated structures, e.g. -A0/270 illuminates from the
44 north (top) and west (left).
45 -D Find the direction of the gradient of the data. By default, the
47 directions are measured clockwise from north, as azim in -A
48 above. Append c to use conventional Cartesian angles measured
49 counterclockwise from the positive x (east) direction. Append o
50 to report orientations (0-180) rather than directions (0-360).
51 Append n to add 90 degrees to all angles (e.g., to give orienta‐
52 tion of lineated features).
53 -E Compute Lambertian radiance appropriate to use with grdimage and
55 grdview. The Lambertian Reflection assumes an ideal surface
56 that reflects all the light that strikes it and the surface
57 appears equally bright from all viewing directions. azim and
58 elev are the azimuth and elevation of light vector. Optionally,
59 supply ambient diffuse specular shine which are parameters that
60 control the reflectance properties of the surface. Default val‐
61 ues are: 0.55/ 0.6/0.4/10 To leave some of the values untouched,
62 specify = as the new value. For example -E60/30/=/0.5 sets the
63 azim elev and diffuse to 60, 30 and 0.5 and leaves the other
64 reflectance parameters untouched. Append s to use a simpler
65 Lambertian algorithm. Note that with this form you only have to
66 provide the azimuth and elevation parameters. Append p to use
67 the Peucker piecewise linear approximation (simpler but faster
68 algorithm; in this case the azim and elev are hardwired to 315
69 and 45 degrees. This means that even if you provide other val‐
70 ues they will be ignored.)
71 -L Boundary condition flag may be x or y or xy indicating data is
73 periodic in range of x or y or both, or flag may be g indicating
74 geographical conditions (x and y are lon and lat). [Default
75 uses "natural" conditions (second partial derivative normal to
76 edge is zero).]
77 -M By default the units of grdgradient are in units_of_z/
79 units_of_dx_and_dy. However, the user may choose this option to
80 convert dx,dy in degrees of longitude,latitude into meters, so
81 that the units of grdgradient are in z_units/meter.
82 -N Normalization. [Default: no normalization.] The actual gradi‐
84 ents g are offset and scaled to produce normalized gradients gn
85 with a maximum output magnitude of amp. If amp is not given,
86 default amp = 1. If offset is not given, it is set to the aver‐
87 age of g. -N yields gn = amp * (g - offset)/max(abs(g
88 - offset)). -Ne normalizes using a cumulative Laplace distri‐
89 bution yielding gn = amp * (1.0 - exp(sqrt(2) * (g - offset)/
90 sigma)) where sigma is estimated using the L1 norm of (g - off‐
91 set) if it is not given. -Nt normalizes using a cumulative
92 Cauchy distribution yielding gn = (2 * amp / PI) * atan( (g -
93 offset)/ sigma) where sigma is estimated using the L2 norm of (g
94 - offset) if it is not given.
95 -S Name of output grid file with scalar magnitudes of gradient vec‐
97 tors. Requires -D but makes -G optional.
98 -V Selects verbose mode, which will send progress reports to stderr
100 [Default runs "silently"].
101
103 If you don't know what OPT(N) options to use to make an intensity file
104 for grdimage or grdview, a good first try is -Ne0.6.
105 If you want to make several illuminated maps of subregions of a large
107 data set, and you need the illumination effects to be consistent across
108 all the maps, use the -N option and supply the same value of sigma and
109 offset to grdgradient for each map. A good guess is offset = 0 and
110 sigma found by grdinfo -L2 or -L1 applied to an unnormalized gradient
111 grd.
112 If you simply need the x- or y-derivatives of the grid, use grdmath.
114
116 By default GMT writes out grid as single precision floats in a COARDS-
117 complaint netCDF file format. However, GMT is able to produce grid
118 files in many other commonly used grid file formats and also facili‐
119 tates so called "packing" of grids, writing out floating point data as
120 2- or 4-byte integers. To specify the precision, scale and offset, the
121 user should add the suffix =id[/scale/offset[/nan]], where id is a two-
122 letter identifier of the grid type and precision, and scale and offset
123 are optional scale factor and offset to be applied to all grid values,
124 and nan is the value used to indicate missing data. When reading
125 grids, the format is generally automatically recognized. If not, the
126 same suffix can be added to input grid file names. See grdreformat(1)
127 and Section 4.17 of the GMT Technical Reference and Cookbook for more
128 information.
129 When reading a netCDF file that contains multiple grids, GMT will read,
131 by default, the first 2-dimensional grid that can find in that file. To
132 coax GMT into reading another multi-dimensional variable in the grid
133 file, append ?varname to the file name, where varname is the name of
134 the variable. Note that you may need to escape the special meaning of ?
135 in your shell program by putting a backslash in front of it, or by
136 placing the filename and suffix between quotes or double quotes. The
137 ?varname suffix can also be used for output grids to specify a variable
138 name different from the default: "z". See grdreformat(1) and Section
139 4.18 of the GMT Technical Reference and Cookbook for more information,
140 particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
141
143 To make a file for illuminating the data in geoid.grd using exp- nor‐
144 malized gradients imitating light sources in the north and west direc‐
145 tions:
146 grdgradient geoid.grd -A0/270 -Ggradients.grd -Ne0.6 -V
148 To find the azimuth orientations of seafloor fabric in the file
150 topo.grd:
151 grdgradient topo.grd -Dno -Gazimuths.grd -V
153
156 Horn, B.K.P., Hill-Shading and the Reflectance Map, Proceedings of the
157 IEEE, Vol. 69, No. 1, January 1981, pp. 14-47. (http://peo‐
158 ple.csail.mit.edu/ bkph/papers/Hill-Shading.pdf)
159
161 GMT(1), gmtdefaults(1), grdhisteq(1), grdimage(1), grdview(1), grdvec‐
162 tor(1)
163GMT 4.5.6 10 Mar 2011 GRDGRADIENT(1)