## 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