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)