## 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  seg-
           ments,  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  cpt-
           file  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 grdhis-
           teq on output from grdgradient and make a grdfile output with the Gaus-
           sian 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 divide 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 stan-
           dard 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 multiply-
           ing 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].  Alterna-
           tively, supply a normalization factor with -N.

## SEE ALSO

           gmtdefaults(l),  gmt(l),  grd2cpt(l), grdgradient(l), grdimage(l), grd-
           math(l), grdview(l), makecpt(l)

    GMT3.4.6                          1 Jan 2005                      GRDHISTEQ(l)