1GRDGRADIENT(1)               Generic Mapping Tools              GRDGRADIENT(1)
2
3
4

NAME

6       grdgradient  - Compute directional derivative or gradient from 2-D grid
7       file representing z(x,y)
8

SYNOPSIS

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

DESCRIPTION

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
21       in_grdfile
22              2-D  grid  file  from  which  to compute directional derivative.
23              (See GRID FILE FORMATS below).
24
25       -G     Name of the output grid file  for  the  directional  derivative.
26              (See GRID FILE FORMATS below).
27

OPTIONS

29       No space between the option flag and the associated arguments.
30
31       -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
46       -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
54       -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
72       -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
78       -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
83       -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
96       -S     Name of output grid file with scalar magnitudes of gradient vec‐
97              tors.  Requires -D but makes -G optional.
98
99       -V     Selects verbose mode, which will send progress reports to stderr
100              [Default runs "silently"].
101

HINTS

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
106       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
113       If you simply need the x- or y-derivatives of the grid, use grdmath.
114

GRID FILE FORMATS

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
130       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

EXAMPLES

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
147       grdgradient geoid.grd -A0/270 -Ggradients.grd -Ne0.6 -V
148
149       To  find  the  azimuth  orientations  of  seafloor  fabric  in the file
150       topo.grd:
151
152       grdgradient topo.grd -Dno -Gazimuths.grd -V
153
154

REFERENCES

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

SEE ALSO

161       GMT(1), gmtdefaults(1), grdhisteq(1), grdimage(1), grdview(1),  grdvec‐
162       tor(1)
163
164
165
166GMT 4.5.6                         10 Mar 2011                   GRDGRADIENT(1)
Impressum