grdgradient

       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
              derivative.

       -G     Name of the  output  grdfile  for  the  directional
              derivative.

OPTIONS

               No  space  between the option flag and the associ­
       ated 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 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 direc­
              tions are calculated and the one larger  in  magni­
              tude  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
              (e.g., to give orientation of lineated features).

       -L     Boundary  condition  flag may be x or y or xy indi­
              cating 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  mag­
              nitude  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  -  off­
              set)/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 - off­
              set) 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 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 grdgradi­
       ent 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.
       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),  grd­
       view(l), grdvector(l)