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 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 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(1gmt),    gmt(1gmt),    grd2cpt(1gmt),    grdgradient(1gmt),   grdimage(1gmt),
       grdmath(1gmt), grdview(1gmt), makecpt(1gmt)

                                            1 Jan 2004                               GRDHISTEQ(l)