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  deriva-
     tive  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  deriva-
          tive.

     -G   Name of the output grdfile for the directional  deriva-
          tive.



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 posi-
          tive clockwise from north  (the  +y  direction)  toward
          east  (the  +x  direction).  The negative of the direc-
          tional      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 illumina-
          tion of an image (see grdimage and grdview) by a  light
          source above the x,y plane shining from the azim direc-
          tion.  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  conven-
          tional  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 normal-
          izes 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  gra-
          dient 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  inten-
     sity  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(l),    gmtdefaults(l),    grdhisteq(l),     grdimage(l),
     grdview(l), grdvector(l)