Provided by: gmt-common_5.4.3+dfsg-1_all

**NAME**

grdgradient - Compute directional derivative or gradient from a grid

**SYNOPSIS**

grdgradientin_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**

grdgradientmay 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_grdfile2-D grid file from which to compute directional derivative. (See GRID FILE FORMATS below).-Gout_grdfileName of the output grid file for the directional derivative. (See GRID FILE FORMATS below).

**OPTIONAL** **ARGUMENTS**

-Aazim[/azim2] Azimuthal direction for a directional derivative;azimis 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 theazimdirection, 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 theazimdirection. 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/270illuminates from the north (top) and west (left). Finally, ifazimis a file it must be a grid of the same domain, spacing and registration asin_grdfileand 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, asazimin-Aabove. Appendcto use conventional Cartesian angles measured counterclockwise from the positive x (east) direction. Appendoto report orientations (0-180) rather than directions (0-360). Appendnto 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,azimandelevare the azimuth and elevation of the light vector. Optionally, supplyambient[0.55],diffuse[0.6],specular[0.4], orshine[10], which are parameters that control the reflectance properties of the surface. Default values are given in the brackets. Use-Esfor a simpler Lambertian algorithm. Note that with this form you only have to provide azimuth and elevation. Alternatively, use-Epfor the Peucker piecewise linear approximation (simpler but faster algorithm; in this case theazimandelevare hardwired to 315 and 45 degrees. This means that even if you provide other values they will be ignored.)-LflagBoundary conditionflagmay bexoryorxyindicating data is periodic in range of x or y or both, orflagmay begindicating 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 gradientsgare offset and scaled to produce normalized gradientsgnwith a maximum output magnitude ofamp. Ifampis not given, defaultamp= 1. Ifoffsetis not given, it is set to the average ofg.-Nyieldsgn=amp* (g-offset)/max(abs(g-offset)).-Nenormalizes using a cumulative Laplace distribution yieldinggn=amp* (1.0 - exp(sqrt(2) * (g-offset)/sigma)), wheresigmais estimated using the L1 norm of (g-offset) if it is not given.-Ntnormalizes using a cumulative Cauchy distribution yieldinggn= (2 *amp/ PI) * atan( (g-offset)/sigma) wheresigmais 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-Roption will select a subsection ofin_grdfilegrid. If this subsection exceeds the boundaries of the grid, only the common region will be extracted.-SslopefileName of output grid file with scalar magnitudes of gradient vectors. Requires-Dbut makes-Goptional.-V[level] (more …) Select verbosity level [c].-fgGeographic 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+uunitto the input file name to convert from the specified unit to meter. If your grid is geographic, convert distances to meters by supplying-fginstead.

**HINTS**

If you don’t know what-Noptions 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 filenameout_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-Noption and supply the same value ofsigmaandoffsettogrdgradientfor each map. A good guess isoffset= 0 andsigmafound by grdinfo-L2or-L1applied to an unnormalized gradient grd. If you simply need thex- ory-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**

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