NAME

       grdhisteq - Perform histogram equalization for a grid

SYNOPSIS

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

       Note: No space is allowed between the option flag and the associated arguments.

DESCRIPTION

       grdhisteq  allows  the  user  to  find the data values which divide a given grid file 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 grid of flat topography with a
       mountain in the middle. Ordinary gray shading of this file  (using  grdimage  or  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  or file 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; using the CPT 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 grid 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 grid, run grdhisteq and make a grid 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  grid  file
       output  with  the  Gaussian  option,  you  will  have  a grid 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.

REQUIRED ARGUMENTS

       in_grdfile
              2-D grid file to be equalized. (See GRID FILE FORMATS below).

OPTIONAL ARGUMENTS

       -Cn_cells
              Sets how many cells (or divisions) of data range to make [16].

       -D     Dump level information to file, or standard output if no file is provided.

       -Gout_grdfile
              Name of output 2-D grid file. Used with -N only. (See GRID FILE FORMATS below).

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

       -Q     Quadratic output. Selects quadratic histogram equalization. [Default is linear].

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify the region of interest. Using the -R option will  select  a  subsection  of
              in_grdfile  grid.  If  this subsection exceeds the boundaries of the grid, only the
              common region will be extracted.

       -V[level] (more ...)
              Select verbosity level [c].

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              just use -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation  of  all  options,
              then exits.

GRID FILE FORMATS

       By  default  GMT  writes  out grid as single precision floats in a COARDS-complaint netCDF
       file format. However, GMT is able to produce grid files in many other commonly  used  grid
       file formats and also facilitates so called "packing" of grids, writing out floating point
       data as 1- or 2-byte integers. (more ...)

EXAMPLES

       To find the height intervals that divide the file heights.nc into 16  divisions  of  equal
       area:

              gmt grdhisteq heights.nc -C16 -D > levels.d

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

              gmt grdhisteq raw_intens.nc -Gsmooth_intens.nc -N -V

NOTES

       1. For geographical grids we do a weighted histogram equalization since the area  of  each
          node varies with latitude.

       2. 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 grid (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 grid. But if N is  very
          large,  it  is possible for x to be greater than 4. Therefore, with the grdview 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

       gmt, gmt.conf, grd2cpt, grdgradient, grdimage, grdmath, grdview, makecpt

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe