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)