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, gmtdefaults, grdhisteq, grdimage, grdview, grdvector