1GRDGRADIENT(1) GMT GRDGRADIENT(1)
2
6 grdgradient - Compute directional derivative or gradient from a grid
7
9 grdgradient in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [
10 -D[a][c][o][n] ] [ -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecu‐
11 lar][+sshine] ] [ -Lflag ] [ -N[e|t][amp][+ssigma][+ooffset] ] [
12 -Rregion ] [ -Sslopefile ] [ -V[level] ] [ -fg ] [ -nflags ]
13 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 grdgradient may be used to compute the directional derivative in a
19 given direction (-A), or to find the direction (-S) [and the magnitude
20 (-D)] of the vector gradient of the data.
21 Estimated values in the first/last row/column of output depend on
23 boundary conditions (see -L).
24
26 in_grdfile
27 2-D grid file from which to compute directional derivative. (See
28 GRID FILE FORMATS below).
29 -Gout_grdfile
31 Name of the output grid file for the directional derivative.
32 (See GRID FILE FORMATS below).
33
35 -Aazim[/azim2]
36 Azimuthal direction for a directional derivative; azim is the
37 angle in the x,y plane measured in degrees positive clockwise
38 from north (the +y direction) toward east (the +x direction).
39 The negative of the directional derivative, -[dz/dx*sin(azim) +
40 dz/dy*cos(azim)], is found; negation yields positive values when
41 the slope of z(x,y) is downhill in the azim direction, the cor‐
42 rect sense for shading the illumination of an image (see grdim‐
43 age and grdview) by a light source above the x,y plane shining
44 from the azim direction. Optionally, supply two azimuths,
45 -Aazim/azim2, in which case the gradients in each of these
46 directions are calculated and the one larger in magnitude is
47 retained; this is useful for illuminating data with two direc‐
48 tions of lineated structures, e.g., -A0/270 illuminates from the
49 north (top) and west (left). Finally, if azim is a file it must
50 be a grid of the same domain, spacing and registration as
51 in_grdfile and we will update the azimuth at each output node
52 when computing the directional derivatives.
53 -D[a][c][o][n]
55 Find the direction of the positive (up-slope) gradient of the
56 data. To instead find the aspect (the down-slope direction),
57 use -Da. By default, directions are measured clockwise from
58 north, as azim in -A above. Append c to use conventional Carte‐
59 sian angles measured counterclockwise from the positive x (east)
60 direction. Append o to report orientations (0-180) rather than
61 directions (0-360). Append n to add 90 degrees to all angles
62 (e.g., to give local strikes of the surface ).
63 -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]
65 Compute Lambertian radiance appropriate to use with grdimage and
66 grdview. The Lambertian Reflection assumes an ideal surface
67 that reflects all the light that strikes it and the surface
68 appears equally bright from all viewing directions. Here, azim
69 and elev are the azimuth and elevation of the light vector.
70 Optionally, supply ambient [0.55], diffuse [0.6], specular
71 [0.4], or shine [10], which are parameters that control the
72 reflectance properties of the surface. Default values are given
73 in the brackets. Use -Es for a simpler Lambertian algorithm.
74 Note that with this form you only have to provide azimuth and
75 elevation. Alternatively, use -Ep for the Peucker piecewise lin‐
76 ear approximation (simpler but faster algorithm; in this case
77 the azim and elev are hardwired to 315 and 45 degrees. This
78 means that even if you provide other values they will be
79 ignored.)
80 -Lflag Boundary condition flag may be x or y or xy indicating data is
82 periodic in range of x or y or both, or flag may be g indicating
83 geographical conditions (x and y are lon and lat). [Default
84 uses "natural" conditions (second partial derivative normal to
85 edge is zero).]
86 -N[e|t][amp][+ssigma][+ooffset]
88 Normalization. [Default is no normalization.] The actual gradi‐
89 ents g are offset and scaled to produce normalized gradients gn
90 with a maximum output magnitude of amp. If amp is not given,
91 default amp = 1. If offset is not given, it is set to the aver‐
92 age of g. -N yields gn = amp * (g - offset)/max(abs(g - off‐
93 set)). -Ne normalizes using a cumulative Laplace distribution
94 yielding gn = amp * (1.0 - exp(sqrt(2) * (g - offset)/ sigma)),
95 where sigma is estimated using the L1 norm of (g - offset) if it
96 is not given. -Nt normalizes using a cumulative Cauchy distribu‐
97 tion yielding gn = (2 * amp / PI) * atan( (g - offset)/ sigma)
98 where sigma is estimated using the L2 norm of (g - offset) if it
99 is not given.
100 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
102 Specify the region of interest. Using the -R option will select
103 a subsection of in_grdfile grid. If this subsection exceeds the
104 boundaries of the grid, only the common region will be
105 extracted.
106 -Sslopefile
108 Name of output grid file with scalar magnitudes of gradient vec‐
109 tors. Requires -D but makes -G optional.
110 -V[level] (more ...)
112 Select verbosity level [c].
113 -fg Geographic grids (dimensions of longitude, latitude) will be
115 converted to meters via a "Flat Earth" approximation using the
116 current ellipsoid parameters.
117 -n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
119 Select interpolation mode for grids.
120 -^ or just -
122 Print a short message about the syntax of the command, then
123 exits (NOTE: on Windows just use -).
124 -+ or just +
126 Print an extensive usage (help) message, including the explana‐
127 tion of any module-specific option (but not the GMT common
128 options), then exits.
129 -? or no arguments
131 Print a complete usage (help) message, including the explanation
132 of all options, then exits.
133
135 If the grid does not have meter as the horizontal unit, append +uunit
136 to the input file name to convert from the specified unit to meter. If
137 your grid is geographic, convert distances to meters by supplying -fg
138 instead.
139
141 If you don't know what -N options to use to make an intensity file for
142 grdimage or grdview, a good first try is -Ne0.6.
143 Usually 255 shades are more than enough for visualization purposes. You
145 can save 75% disk space by appending =nb/a to the output filename
146 out_grdfile.
147 If you want to make several illuminated maps of subregions of a large
149 data set, and you need the illumination effects to be consistent across
150 all the maps, use the -N option and supply the same value of sigma and
151 offset to grdgradient for each map. A good guess is offset = 0 and
152 sigma found by grdinfo -L2 or -L1 applied to an unnormalized gradient
153 grd.
154 If you simply need the x- or y-derivatives of the grid, use grdmath.
156
158 By default GMT writes out grid as single precision floats in a
159 COARDS-complaint netCDF file format. However, GMT is able to produce
160 grid files in many other commonly used grid file formats and also
161 facilitates so called "packing" of grids, writing out floating point
162 data as 1- or 2-byte integers. (more ...)
163
165 To make a file for illuminating the data in geoid.nc using exp- normal‐
166 ized gradients in the range [-0.6,0.6] imitating light sources in the
167 north and west directions:
168 gmt grdgradient geoid.nc -A0/270 -Ggradients.nc=nb/a -Ne0.6 -V
170 To find the azimuth orientations of seafloor fabric in the file
172 topo.nc:
173 gmt grdgradient topo.nc -Dno -Gazimuths.nc -V
175
177 Horn, B.K.P., Hill-Shading and the Reflectance Map, Proceedings of the
178 IEEE, Vol. 69, No. 1, January 1981, pp. 14-47. (‐
179 http://people.csail.mit.edu/bkph/papers/Hill-Shading.pdf)
180
182 gmt, gmt.conf grdhisteq, grdinfo, grdmath, grdimage, grdview, grdvector
183
185 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
1865.4.5 Feb 24, 2019 GRDGRADIENT(1)