GRDGRADIENT(l)															    GRDGRADIENT(l)

NAME

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

SYNOPSIS

       grdgradient  in_grdfile -Gout_grdfile [ -Aazim[/azim2] ] [ -D[c][o][n] ] [ -Lflag ] [ -M ] [ -N[e][t][amp][/sigma[/offset]] ] [ -Sslopefile
       ] [ -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, -Aazim/azim2, in which case the gradients in each of these directions are calcu-
	      lated and the one larger in magnitude is retained; this is useful for illuminating data with two directions of lineated  structures,
	      e.g. -A0/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 geo-
	      graphical  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 normal-
	      izes  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 -Ne0.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  direc-
       tions, do

       grdgradient geoid.grd -A0/270 -Ggradients.grd -Ne0.6 -V

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

       grdgradient topo.grd -Snao -Gazimuths.grd -V

SEE ALSO

       gmt(1gmt), gmtdefaults(1gmt), grdhisteq(1gmt), grdimage(1gmt), grdview(1gmt), grdvector(1gmt)

								    1 Jan 2004							    GRDGRADIENT(l)