.\" Man page generated from reStructuredText.
.
.TH "GRDGRADIENT" "1gmt" "Nov 05, 2016" "5.3.1" "GMT"
.SH NAME
grdgradient \- Compute directional derivative or gradient from a grid
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBgrdgradient\fP \fIin_grdfile\fP  \fB\-G\fP\fIout_grdfile\fP
[  \fB\-A\fP\fIazim\fP[/\fIazim2\fP] ] [  \fB\-D\fP[\fBa\fP][\fBc\fP][\fBo\fP][\fBn\fP] ]
[  \fB\-E\fP[\fBs|p\fP]\fIazim/elev\fP[/\fIambient\fP/\fIdiffuse\fP/\fIspecular\fP/\fIshine\fP] ]
[  \fB\-L\fP\fIflag\fP ]
[  \fB\-N\fP[\fBe\fP][\fBt\fP][\fIamp\fP][/\fIsigma\fP[/\fIoffset\fP]] ]
[  \fB\-R\fP\fIregion\fP ] [  \fB\-S\fP\fIslopefile\fP ]
[  \fB\-V\fP[\fIlevel\fP] ] [ \fB\-fg\fP ]
[ \fB\-n\fPflags ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBgrdgradient\fP may be used to compute the directional derivative in a
given direction (\fB\-A\fP), or the direction (\fB\-S\fP) [and the magnitude
(\fB\-D\fP)] of the vector gradient of the data.
.sp
Estimated values in the first/last row/column of output depend on
boundary conditions (see \fB\-L\fP).
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
.B \fIin_grdfile\fP
2\-D grid file from which to compute directional derivative. (See GRID FILE FORMATS below).
.UNINDENT
.INDENT 0.0
.TP
\fB\-G\fP\fIout_grdfile\fP
Name of the output grid file for the directional derivative. (See
GRID FILE FORMATS below).
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-A\fP\fIazim\fP[/\fIazim2\fP]
Azimuthal direction for a directional derivative; \fIazim\fP 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(\fIazim\fP) +
dz/dy*cos(\fIazim\fP)], is found; negation yields positive values
when the slope of z(x,y) is downhill in the \fIazim\fP 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 \fIazim\fP direction. Optionally, supply two azimuths,
\fB\-A\fP\fIazim\fP/\fIazim2\fP, 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., \fB\-A\fP\fI0\fP/\fI270\fP illuminates from the
north (top) and west (left).
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP[\fBa\fP][\fBc\fP][\fBo\fP][\fBn\fP]
Find the direction of the positive (up\-slope) gradient of the data.
To instead find the aspect (the down\-slope direction), use \fB\-Da\fP\&.
By default, directions are measured clockwise from north, as \fIazim\fP in \fB\-A\fP
above. Append \fBc\fP to use conventional Cartesian angles measured
counterclockwise from the positive x (east) direction. Append \fBo\fP
to report orientations (0\-180) rather than directions (0\-360).
Append \fBn\fP to add 90 degrees to all angles (e.g., to give
local strikes of the surface ).
.UNINDENT
.INDENT 0.0
.TP
\fB\-E\fP[\fBs|p\fP]\fIazim/elev\fP[/\fIambient\fP/\fIdiffuse\fP/\fIspecular\fP/\fIshine\fP]
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. \fIazim\fP and \fIelev\fP are
the azimuth and elevation of light vector. Optionally, supply
\fIambient\fP \fIdiffuse\fP \fIspecular\fP \fIshine\fP which are parameters that
control the reflectance properties of the surface. Default values
are: \fI0.55\fP/\fI0.6\fP/\fI0.4\fP/\fI10\fP To leave some of the values untouched,
specify = as the new value. For example \fB\-E\fP\fI60\fP/\fI30\fP/\fI=\fP/\fI0.5\fP
sets the \fIazim\fP \fIelev\fP and \fIdiffuse\fP to 60, 30 and 0.5 and leaves
the other reflectance parameters untouched. Append \fBs\fP to use a
simpler Lambertian algorithm. Note that with this form you only have
to provide the azimuth and elevation parameters. Append \fBp\fP to use
the Peucker piecewise linear approximation (simpler but faster
algorithm; in this case the \fIazim\fP and \fIelev\fP are hardwired to 315
and 45 degrees. This means that even if you provide other values
they will be ignored.)
.UNINDENT
.INDENT 0.0
.TP
\fB\-L\fP\fIflag\fP
Boundary condition \fIflag\fP may be \fIx\fP or \fIy\fP or \fIxy\fP indicating data
is periodic in range of x or y or both, or \fIflag\fP may be \fIg\fP
indicating geographical conditions (x and y are lon and lat).
[Default uses "natural" conditions (second partial derivative normal
to edge is zero).]
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP[\fBe\fP][\fBt\fP][\fIamp\fP][/\fIsigma\fP[/\fIoffset\fP]]
Normalization. [Default: no normalization.] The actual gradients \fIg\fP
are offset and scaled to produce normalized gradients \fIgn\fP with a
maximum output magnitude of \fIamp\fP\&. If \fIamp\fP is not given, default
\fIamp\fP = 1. If \fIoffset\fP is not given, it is set to the average of
\fIg\fP\&. \fB\-N\fP yields \fIgn\fP = \fIamp\fP * (\fIg\fP \- \fIoffset\fP)/max(abs(\fIg\fP \-
\fIoffset\fP)). \fB\-Ne\fP normalizes using a cumulative Laplace
distribution yielding \fIgn\fP = \fIamp\fP * (1.0 \-
exp(sqrt(2) * (\fIg\fP \- \fIoffset\fP)/ \fIsigma\fP)) where
\fIsigma\fP is estimated using the L1 norm of (\fIg\fP \- \fIoffset\fP) if it is
not given. \fB\-Nt\fP normalizes using a cumulative Cauchy distribution
yielding \fIgn\fP = (2 * \fIamp\fP / PI) * atan( (\fIg\fP \- \fIoffset\fP)/
\fIsigma\fP) where \fIsigma\fP is estimated using the L2 norm of (\fIg\fP \-
\fIoffset\fP) if it is not given.
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP[\fIunit\fP]\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fBr\fP] (more ...)
Specify the region of interest. Using the \fB\-R\fP option
will select a subsection of \fIin_grdfile\fP grid. If this subsection
exceeds the boundaries of the grid, only the common region will be extracted.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP\fIslopefile\fP
Name of output grid file with scalar magnitudes of gradient vectors.
Requires \fB\-D\fP but makes \fB\-G\fP optional.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.TP
\fB\-fg\fP
Geographic grids (dimensions of longitude, latitude) will be converted to
meters via a "Flat Earth" approximation using the current ellipsoid parameters.
.UNINDENT
.INDENT 0.0
.TP
\fB\-n\fP[\fBb\fP|\fBc\fP|\fBl\fP|\fBn\fP][\fB+a\fP][\fB+b\fP\fIBC\fP][\fB+c\fP][\fB+t\fP\fIthreshold\fP] (more ...)
Select interpolation mode for grids.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows use just \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of options, then exits.
.UNINDENT
.SH GRID DISTANCE UNITS
.sp
If the grid does not have meter as the horizontal unit, append \fB+u\fP\fIunit\fP to the input file name to convert from the
specified unit to meter.  If your grid is geographic, convert distances to meters by supplying \fB\-fg\fP instead.
.SH HINTS
.sp
If you don\(aqt know what \fB\-N\fP options to use to make an intensity file
for grdimage or grdview, a good first try is \fB\-Ne\fP0.6.
.sp
Usually 255 shades are more than enough for visualization purposes. You
can save 75% disk space by appending =nb/a to the output filename
\fIout_grdfile\fP\&.
.sp
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 \fB\-N\fP option and supply the same value of \fIsigma\fP
and \fIoffset\fP to \fBgrdgradient\fP for each map. A good guess is \fIoffset\fP =
0 and \fIsigma\fP found by \fBgrdinfo\fP \fB\-L2\fP or \fB\-L1\fP applied to an
unnormalized gradient grd.
.sp
If you simply need the \fIx\fP\- or \fIy\fP\-derivatives of the grid, use grdmath\&.
.SH GRID FILE FORMATS
.sp
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 ...)
.SH EXAMPLES
.sp
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:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdgradient geoid.nc \-A0/270 \-Ggradients.nc=nb/a \-Ne0.6 \-V
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
To find the azimuth orientations of seafloor fabric in the file topo.nc:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt grdgradient topo.nc \-Dno \-Gazimuths.nc \-V
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH REFERENCES
.sp
Horn, B.K.P., Hill\-Shading and the Reflectance Map, Proceedings of the
IEEE, Vol. 69, No. 1, January 1981, pp. 14\-47.
(\fI\%http://people.csail.mit.edu/bkph/papers/Hill\-Shading.pdf\fP)
.SH SEE ALSO
.sp
gmt, gmt.conf
grdhisteq,
grdmath,
grdimage, grdview,
grdvector
.SH COPYRIGHT
2016, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.