---
name: "grdgradient"
section: "1"
platform: "linux"
package: "gmt-manpages"
version: "3.4-1"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/grdgradient"
---

# grdgradient(1)

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

## SEE ALSO

*gmt*(l), *gmtdefaults*(l), *grdhisteq*(l), *grdimage*(l), *grdview*(l), *grdvector*(l)