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 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 grd file from which to compute directional derivative.

       -G     Name of the output grdfile for the directional derivative.

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 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  correct
              sense  for shading the illumination of an image (see grdimage 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  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  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).

       -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 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 grdfile with scalar magnitudes of gradient 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 intensity 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(1gmt), gmtdefaults(1gmt), grdhisteq(1gmt), grdimage(1gmt), grdview(1gmt), grdvector(1gmt)

                                                   1 Jan 2004                                     GRDGRADIENT(l)