# man grdgradient () - Compute directional derivative or gradient from 2-D grd file representing z(x,y)

## NAME

grdgradient - Compute directional derivative or gradient from 2-D grd file representing z(x,y)

## SYNOPSIS

**grdgradient** *in_grdfile* **-G***out_grdfile* [ **-A***azim*[/*azim2*] ]
[ **-D**[**c**][**o**][**n**] ] [ **-L***flag* ] [ **-M** ] [ **-N**[**e**][**t**][*amp*][/*sigma*[/*offset*]] ] [ **-S***slopefile* ]
[ **-V** ]

## DESCRIPTION

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

*in_grdfile*- 2-D grd file from which to compute directional derivative.
**-G**- Name of the output grdfile for the directional derivative.

## OPTIONS

No space between the option flag and the associated arguments. Use upper case for the option flags and lower case for modifiers.

**-A**- 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,**-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). **-D**- Find the direction of the gradient of the data. By default, the 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 orientation of lineated features). **-L**- 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).] **-M**- By default the units of
**grdgradient**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**grdgradient**are in z_units/meter. **-N**- Normalization. [Default: 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. **-S**- Name of output grdfile with scalar magnitudes of gradient vectors. Requires
**-D**. **-V**- Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].

## 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 **-Ne**0.6.

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

## 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, do

grdgradient geoid.grd **-A**0/270 **-G**gradients.grd **-Ne**0.6 -V

To find the azimuth orientations of seafloor fabric in the file topo.grd, try

grdgradient topo.grd **-Snao -G**azimuths.grd **-V**