grdhisteq

       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  equal­
       ization  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 grdim­
       age/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. Alter­
       natively, 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 out­
       put of grdgradient.  For shading purposes  it  is  desired
       that  the data have a smooth distribution, such as a gaus­
       sian. 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 loca­
       tions  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 associ­
       ated arguments. Use upper case for the  option  flags  and
       lower case for modifiers.

       in_grdfile
              2-D binary grd file to be equalized.


       -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 grd­
              file  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 lin­
              ear].

       -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  gradi­
       ent 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 grd­
       file (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 gra­
       dients  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 mul­
       tiplying 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 normaliza­
       tion factor with -N.

       gmtdefaults(l), gmt(l), grd2cpt(l), grdgradient(l), grdim­
       age(l), grdmath(l), grdview(l), makecpt(l)