## 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 cor-
                  rect sense for shading the illumination of an image (see  grdim-
                  age  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 direc-
                  tions 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 orienta-
                  tion 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  vec-
                  tors. 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-normal-
           ized  gradients  imitating  light  sources in the north and west direc-
           tions:

           grdgradient geoid.grd -A0/270 -Ggradients.grd -Ne0.6 -V

           To find the  azimuth  orientations  of  seafloor  fabric  in  the  file
           topo.grd:

           grdgradient topo.grd -Snao -Gazimuths.grd -V

## SEE ALSO

           gmt(l),  gmtdefaults(l), grdhisteq(l), grdimage(l), grdview(l), grdvec-
           tor(l)

    GMT4.0                            1 Oct 2004                    GRDGRADIENT(l)