.TH GRDGRADIENT 1gmt "15 Jul 2011" "GMT 4.5.7" "Generic Mapping Tools" .SH NAME grdgradient \- Compute directional derivative or gradient from 2-D grid file representing z(x,y) .SH SYNOPSIS \fBgrdgradient\fP \fIin_grdfile\fP \fB\-G\fP\fIout_grdfile\fP [ \fB\-A\fP\fIazim\fP[/\fIazim2\fP] ] [ \fB\-D\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\-M\fP ] [ \fB\-N\fP[\fBe\fP][\fBt\fP][\fIamp\fP][/\fIsigma\fP[/\fIoffset\fP]] ] [ \fB\-S\fP\fIslopefile\fP ] [ \fB\-V\fP ] .SH DESCRIPTION \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. .br Estimated values in the first/last row/column of output depend on boundary conditions (see \fB\-L\fP). .br .TP \fIin_grdfile\fP 2-D grid file from which to compute directional derivative. (See GRID FILE FORMATS below). .TP \fB\-G\fP Name of the output grid file for the directional derivative. (See GRID FILE FORMATS below). .SH OPTIONS No space between the option flag and the associated arguments. .TP \fB\-A\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 \fBgrdimage\fP and \fBgrdview\fP) 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). .TP \fB\-D\fP Find the direction of the gradient of the data. By default, the 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 orientation of lineated features). .TP \fB\-E\fP Compute Lambertian radiance appropriate to use with \fBgrdimage\fP and \fBgrdview\fP. 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.) .TP \fB\-L\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).] .TP \fB\-M\fP By default the units of \fBgrdgradient\fP 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 \fBgrdgradient\fP are in z_units/meter. .TP \fB\-N\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. .TP \fB\-S\fP Name of output grid file with scalar magnitudes of gradient vectors. Requires \fB\-D\fP but makes \fB\-G\fP optional. .TP \fB\-V\fP Selects verbose mode, which will send progress reports to stderr [Default runs "silently"]. .SH HINTS If you don't know what OPT(N) options to use to make an intensity file for\"' \fBgrdimage\fP or \fBgrdview\fP, a good first try is \fB\-Ne\fP0.6. .br .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. .br .sp If you simply need the \fIx\fP- or \fIy\fP-derivatives of the grid, use \fBgrdmath\fP. .SH GRID FILE FORMATS By default \fBGMT\fP writes out grid as single precision floats in a COARDS-complaint netCDF file format. However, \fBGMT\fP 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 2- or 4-byte integers. To specify the precision, scale and offset, the user should add the suffix \fB=\fP\fIid\fP[\fB/\fP\fIscale\fP\fB/\fP\fIoffset\fP[\fB/\fP\fInan\fP]], where \fIid\fP is a two-letter identifier of the grid type and precision, and \fIscale\fP and \fIoffset\fP are optional scale factor and offset to be applied to all grid values, and \fInan\fP is the value used to indicate missing data. When reading grids, the format is generally automatically recognized. If not, the same suffix can be added to input grid file names. See \fBgrdreformat\fP(1) and Section 4.17 of the GMT Technical Reference and Cookbook for more information. .P When reading a netCDF file that contains multiple grids, \fBGMT\fP will read, by default, the first 2-dimensional grid that can find in that file. To coax \fBGMT\fP into reading another multi-dimensional variable in the grid file, append \fB?\fP\fIvarname\fP to the file name, where \fIvarname\fP is the name of the variable. Note that you may need to escape the special meaning of \fB?\fP in your shell program by putting a backslash in front of it, or by placing the filename and suffix between quotes or double quotes. The \fB?\fP\fIvarname\fP suffix can also be used for output grids to specify a variable name different from the default: "z". See \fBgrdreformat\fP(1) and Section 4.18 of the GMT Technical Reference and Cookbook for more information, particularly on how to read splices of 3-, 4-, or 5-dimensional grids. .SH 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: .br .sp \fBgrdgradient\fP geoid.grd \fB\-A\fP0/270 \fB\-G\fPgradients.grd \fB \-Ne\fP0.6 \fP\-V\fP .br .sp To find the azimuth orientations of seafloor fabric in the file topo.grd: .br .sp \fBgrdgradient\fP topo.grd \fB\-Dno\fP \fB\-G\fPazimuths.grd \fB\-V\fP .br .sp .SH 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) .SH "SEE ALSO" .IR GMT (1), .IR gmtdefaults (1), .IR grdhisteq (1), .IR grdimage (1), .IR grdview (1), .IR grdvector (1)