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 gradi-
              ents 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 aver-
              age  of  g.   -N yields gn = amp * (g - offset)/max(abs(g - off-
              set)).  -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 distri-
              bution 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, 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), grdvec-
       tor(l)



VERSION                              DATE                       GRDGRADIENT(l)

Man(1) output converted with man2html