.TH GRDHISTEQ 1 "Feb 27 2014" "GMT 4.5.13 (SVN)" "Generic Mapping Tools"
.SH NAME
grdhisteq \- Histogram equalization for grid files 
.SH SYNOPSIS
\fBgrdhisteq\fP \fIin_grdfile\fP [ \fB\-G\fP\fIout_grdfile\fP ] 
[ \fB\-C\fP\fIn_cells\fP ] [ \fB\-D\fP ] [ \fB\-N\fP[\fInorm\fP] ] [ \fB\-Q\fP ] [ \fB\-V\fP ]
.SH DESCRIPTION
\fBgrdhisteq\fP allows the user to find the data values which divide a given
grid file into patches of equal area.  One common use of \fBgrdhisteq\fP is in
a kind of histogram equalization of an image.  In this application, the
user might have a grid of flat topography with a mountain in the middle.
Ordinary gray shading of this file (using grdimage/grdview) with a linear mapping
from topography to graytone will result in most of the image being very
dark gray, with the mountain being almost white.  One could use \fBgrdhisteq\fP
to write to stdout an ASCII list of those data values which divide the
range of the data into \fIn_cells\fP segments, each of which has an equal
area in the image.  Using \fBawk\fP or \fBmakecpt\fP one can take this output and build a cpt
file; using the cptfile with grdimage will result in an image with all
levels of gray occurring equally.  Alternatively, see \fBgrd2cpt\fP.
.P
The second common use of \fBgrdhisteq\fP is in writing a grid with statistics
based on some kind of cumulative distribution function.  In this application,
the output has relative highs and lows in the same (x,y) locations as the
input file, but the values are changed to reflect their place in some
cumulative distribution.  One example would be to find the lowest 10%
of the data:  Take a grid, run \fBgrdhisteq\fP and make a grid using
\fIn_cells\fP = 10, and then contour the result to trace the 1 contour.
This will enclose the lowest 10% of the data, regardless of their original
values.  Another example is in equalizing the output of \fBgrdgradient\fP.
For shading purposes it is desired that the data have a smooth distribution,
such as a gaussian.  If you run \fBgrdhisteq\fP on output from \fBgrdgradient\fP
and make a grid file output with the Gaussian option, you will have a
grid whose values are distributed according to a gaussian distribution
with zero mean and unit variance.  The locations of these values will
correspond to the locations of the input; that is, the most negative
output value will be in the (x,y) location of the most negative input
value, and so on.
.TP
\fIin_grdfile\fP
2-D binary grid file to be equalized.
(See GRID FILE FORMATS below).
.SH OPTIONS
No space between the option flag and the associated arguments.
.TP
\fB\-C\fP
Sets how many cells (or divisions) of data range to make.
.TP
\fB\-D\fP
Dump level information to standard output.
.TP
\fB\-G\fP
Name of output 2-D grid file.  Used with \fB\-N\fP only.
(See GRID FILE FORMATS below).
.TP
\fB\-N\fP
Gaussian output.  Use with \fB\-G\fP to make an output grid with standard normal scores.
Append \fInorm\fP to force the scores to fall in the <-1,+1> range [Default is standard normal scores].
.TP
\fB\-Q\fP
Use quadratic intensity scaling.  [Default is linear].
.TP
\fB\-V\fP
Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].
.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 find the height intervals that divide the file heights.grd into 16 divisions of
equal area:
.br
.sp
\fBgrdhisteq\fP heights.grd \fB\-C\fP 16 \fB\-D\fP > levels.d
.br
.sp
To make the poorly distributed intensities in the file raw_intens.grd suitable for use
with \fBgrdimage\fP or \fBgrdview\fP, run
.br
.sp
\fBgrdhisteq\fP raw_intens.grd \fB\-G\fP smooth_intens.grd \fB\-N\fP \fB\-V\fP
.SH RESTRICTIONS
If you use \fBgrdhisteq\fP to make a gaussian output for gradient shading
in \fBgrdimage\fP or \fBgrdview\fP, you should be aware of the following:  the output will be
in the range [-x, x], where x is based on the number of data in the input
grid (nx * ny) and the cumulative gaussian distribution function F(x).
That is, let N = nx * ny.  Then x will be adjusted so that 
F(x) = (N - 1 + 0.5)/N.  Since about 68% of the values from a standard normal
distribution fall within +/- 1, this will be true of the output grid.
But if N is very large, it is possible for x to be greater than 4.  Therefore,
with the \fBgrdimage\fP program clipping gradients to the range [-1, 1], you will
get correct shading of 68% of your data, while 16% of them will be clipped
to -1 and 16% of them clipped to +1.  If this makes too much of the image
too light or too dark, you should take the output of \fBgrdhisteq\fP and rescale
it using \fBgrdmath\fP and multiplying by something less than 1.0, to shrink
the range of the values, thus bringing more than 68% of the image into the
range [-1, 1].  Alternatively, supply a normalization factor with \fB\-N\fP.
.SH "SEE ALSO"
.IR gmtdefaults (1),
.IR GMT (1),
.IR grd2cpt (1),
.IR grdgradient (1),
.IR grdimage (1),
.IR grdmath (1),
.IR grdview (1),
.IR makecpt (1)