Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       grdgradient - Compute directional derivative or gradient from a grid

SYNOPSIS

       grdgradient   in_grdfile    -Gout_grdfile  [   -Aazim[/azim2]  ]  [   -D[a][c][o][n]  ]  [
       -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]   ]   [     -Lflag    ]    [
       -N[e|t][amp][+ssigma][+ooffset]  ] [  -Rregion ] [  -Sslopefile ] [  -V[level] ] [ -fg ] [
       -nflags ]

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       grdgradient may be used to compute the directional derivative in a given  direction  (-A),
       or to find 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).

REQUIRED ARGUMENTS

       in_grdfile
              2-D grid file from which to compute directional derivative. (See GRID FILE  FORMATS
              below).

       -Gout_grdfile
              Name of the output grid file for the directional derivative. (See GRID FILE FORMATS
              below).

OPTIONAL ARGUMENTS

       -Aazim[/azim2]
              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).  Finally, if azim is  a  file  it
              must  be  a  grid of the same domain, spacing and registration as in_grdfile and we
              will update the  azimuth  at  each  output  node  when  computing  the  directional
              derivatives.

       -D[a][c][o][n]
              Find  the  direction  of  the positive (up-slope) gradient of the data.  To instead
              find the aspect (the down-slope direction), use -Da.  By  default,  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 local strikes of the surface ).

       -E[m|s|p]azim/elev[+aambient][+ddiffuse][+pspecular][+sshine]
              Compute Lambertian radiance appropriate to use  with  grdimage  and  grdview.   The
              Lambertian  Reflection  assumes  an  ideal surface that reflects all the light that
              strikes it and the surface appears equally  bright  from  all  viewing  directions.
              Here,  azim and elev are the azimuth and elevation of the light vector. Optionally,
              supply ambient [0.55], diffuse [0.6], specular [0.4],  or  shine  [10],  which  are
              parameters  that  control the reflectance properties of the surface. Default values
              are given in the brackets. Use -Es for a simpler Lambertian  algorithm.  Note  that
              with  this  form you only have to provide azimuth and elevation. Alternatively, use
              -Ep for the Peucker piecewise linear approximation (simpler but  faster  algorithm;
              in this case the azim and elev are hardwired to 315 and 45 degrees. This means that
              even if you provide other values they will be ignored.)

       -Lflag 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).]

       -N[e|t][amp][+ssigma][+ooffset]
              Normalization. [Default is 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.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify  the  region  of  interest. Using the -R option will select a subsection of
              in_grdfile grid. If this subsection exceeds the boundaries of the  grid,  only  the
              common region will be extracted.

       -Sslopefile
              Name  of  output grid file with scalar magnitudes of gradient vectors.  Requires -D
              but makes -G optional.

       -V[level] (more ...)
              Select verbosity level [c].

       -fg    Geographic grids (dimensions of longitude, latitude) will be  converted  to  meters
              via a "Flat Earth" approximation using the current ellipsoid parameters.

       -n[b|c|l|n][+a][+bBC][+c][+tthreshold] (more ...)
              Select interpolation mode for grids.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              just use -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print  a  complete  usage (help) message, including the explanation of all options,
              then exits.

GRID DISTANCE UNITS

       If the grid does not have meter as the horizontal unit, append +uunit to  the  input  file
       name  to  convert  from  the specified unit to meter.  If your grid is geographic, convert
       distances to meters by supplying -fg instead.

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.

       Usually  255 shades are more than enough for visualization purposes. You can save 75% disk
       space by appending =nb/a to the output filename out_grdfile.

       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.

GRID FILE FORMATS

       By  default  GMT  writes  out grid as single precision floats in a COARDS-complaint netCDF
       file format. However, GMT is able to produce grid files in many other commonly  used  grid
       file formats and also facilitates so called "packing" of grids, writing out floating point
       data as 1- or 2-byte integers. (more ...)

EXAMPLES

       To make a file for illuminating the data in geoid.nc using exp-  normalized  gradients  in
       the range [-0.6,0.6] imitating light sources in the north and west directions:

              gmt grdgradient geoid.nc -A0/270 -Ggradients.nc=nb/a -Ne0.6 -V

       To find the azimuth orientations of seafloor fabric in the file topo.nc:

              gmt grdgradient topo.nc -Dno -Gazimuths.nc -V

REFERENCES

       Horn,  B.K.P., Hill-Shading and the Reflectance Map, Proceedings of the IEEE, Vol. 69, No.
       1, January 1981, pp. 14-47.  (http://people.csail.mit.edu/bkph/papers/Hill-Shading.pdf)

SEE ALSO

       gmt, gmt.conf grdhisteq, grdinfo, grdmath, grdimage, grdview, grdvector

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe