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)