.. index:: ! grdgradient
***********
grdgradient
***********
.. only:: not man
grdgradient - Compute directional derivative or gradient from a grid
Synopsis
--------
.. include:: common_SYN_OPTs.rst_
**grdgradient** *in_grdfile* |-G|\ *out_grdfile*
[ |-A|\ *azim*\ [/*azim2*] ] [ |-D|\ [**a**][**c**][**o**][**n**] ]
[ |-E|\ [**m**\ \|\ **s**\ \|\ **p**\ ]\ *azim/elev*\ [**+a**\ *ambient*\ ][**+d**\ *diffuse*\ ][**+p**\ *specular*\ ][**+s**\ *shine*\ ] ]
[ |-L|\ *flag* ]
[ |-N|\ [**e**\ \|\ **t**][*amp*][**+s**\ *sigma*\ ][**+o**\ *offset*\ ] ]
[ |SYN_OPT-R| ] [ |-S|\ *slopefile* ]
[ |SYN_OPT-V| ] [ **-fg** ]
[ |SYN_OPT-n| ]
|No-spaces|
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).
.. _-G:
**-G**\ *out_grdfile*
Name of the output grid file for the directional derivative. (See
GRID FILE FORMATS below).
Optional Arguments
------------------
.. _-A:
**-A**\ *azim*\ [/*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
:doc:`grdimage` and :doc:`grdview`) by a light source above the x,y plane
shining from the *azim* direction. Optionally, supply two azimuths,
**-A**\ *azim*/*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., **-A**\ *0*/*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:
**-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:
**-E**\ [**m**\ \|\ **s**\ \|\ **p**\ ]\ *azim/elev*\ [**+a**\ *ambient*\ ][**+d**\ *diffuse*\ ][**+p**\ *specular*\ ][**+s**\ *shine*\ ]
Compute Lambertian radiance appropriate to use with :doc:`grdimage` and :doc:`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.)
.. _-L:
**-L**\ *flag*
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:
**-N**\ [**e**\ \|\ **t**][*amp*][**+s**\ *sigma*\ ][**+o**\ *offset*\ ]
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.
.. _-R:
.. |Add_-R| replace:: 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.
.. include:: explain_-R.rst_
.. _-S:
**-S**\ *slopefile*
Name of output grid file with scalar magnitudes of gradient vectors.
Requires **-D** but makes **-G** optional.
.. _-V:
.. |Add_-V| unicode:: 0x20 .. just an invisible code
.. include:: explain_-V.rst_
**-fg**
Geographic grids (dimensions of longitude, latitude) will be converted to
meters via a "Flat Earth" approximation using the current ellipsoid parameters.
.. include:: explain_-n.rst_
.. include:: explain_help.rst_
Grid Distance Units
-------------------
If the grid does not have meter as the horizontal unit, append **+u**\ *unit* 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 :doc:`grdimage` or :doc:`grdview`, a good first try is **-Ne**\ 0.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 :doc:`grdinfo` **-L2** or **-L1** applied to an
unnormalized gradient grd.
If you simply need the *x*- or *y*-derivatives of the grid, use :doc:`grdmath`.
.. include:: explain_grd_inout_short.rst_
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
--------
:doc:`gmt`, :doc:`gmt.conf`
:doc:`grdhisteq`,
:doc:`grdinfo`,
:doc:`grdmath`,
:doc:`grdimage`, :doc:`grdview`,
:doc:`grdvector`