## NAME

          grdhisteq - Histogram equalization for grd files

## SYNOPSIS

          grdhisteq in_grdfile [ -Gout_grdfile ] [ -Cn_cells ] [ -D ] [ -N[norm]
          ] [ -Q ] [ -V ]

## DESCRIPTION

          grdhisteq allows the user to find the data values which divide a given
          grdfile into patches of equal area.  One common use of grdhisteq is in
          a kind of histogram equalization of an image.  In this application,
          the user might have a grdfile 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 grdhisteq to write to
          stdout an ASCII list of those data values which divide the range of
          the data into n_cells segments, each of which has an equal area in the
          image.  Using awk or makecpt 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 grd2cpt.
               The second common use of grdhisteq is in writing a grdfile 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 grdfile, run
          grdhisteq and make a grdfile using n_cells = 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 grdgradient.  For shading purposes it is
          desired that the data have a smooth distribution, such as a gaussian.
          If you run grdhisteq on output from grdgradient and make a grdfile
          output with the Gaussian option, you will have a grdfile 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.
               No space between the option flag and the associated arguments.
          Use upper case for the option flags and lower case for modifiers.

          in_grdfile
               2-D binary grd file to be equalized.

## OPTIONS

          -C   Sets how many cells (or divisions) of data range to make.

          -D   Dump level information to standard output.

          -G   Name of output 2-D grd file.  Used with -N only.

          -N   Gaussian output.  Use with -G to make an output grdfile with
               standard normal scores.  Append norm to force the scores to fall
               in the <-1,+1> range [Default is standard normal scores].

          -Q   Use quadratic intensity scaling.  [Default is linear].

          -V   Selects verbose mode, which will send progress reports to stderr
               [Default runs "silently"].

## EXAMPLES

          To find the height intervals that devide the file heights.grd into 16
          divisions of equal area, try

          grdhisteq heights.grd -C16 -D > levels.d

          To make the poorly distributed intensities in the file raw_intens.grd
          suitable for use with grdimage or grdview, try

          grdhisteq raw_intens.grd -Gsmooth_intens.grd -N -V

## RESTRICTIONS

          If you use grdhisteq to make a gaussian output for gradient shading in
          grdimage or grdview, 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 grdfile (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 grdfile.  But if N is very large, it is
          possible for x to be greater than 4.  Therefore, with the grdimage
          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 grdhisteq and
          rescale it using grdmath 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 -N.

## SEE ALSO

          gmtdefaults, gmt, grd2cpt, grdgradient, grdimage, grdmath, grdview,
          makecpt