manpagez: man pages & more
man grdhisteq(1)
Home | html | info | man
grdhisteq(1)                          GMT                         grdhisteq(1)




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  mid-
       dle.  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  appli-
       cation,  the output has relative highs and lows in the same (x,y) loca-
       tions 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 orig-
       inal  values.  Another example is in equalizing the output of grdgradi-
       ent. 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  nega-
       tive 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 stan-
              dard 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 a|)
              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 a|)
              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  explana-
              tion  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 apackinga of grids, writing  out  floating  point
       data as 1- or 2-byte integers. (more a|)


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 dis-
          tribution 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 val-
          ues 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 shad-
          ing 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 normaliza-
          tion factor with -N.


SEE ALSO

       gmt(1), gmt.conft(5), grd2cptt(1), grdgradientt(1), grdimaget(1),
       grdmatht(1), grdviewt(1), makecptt(1)


COPYRIGHT

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



5.4.2                            Jun 24, 2017                     grdhisteq(1)

gmt5 5.4.2 - Generated Wed Jun 28 19:20:54 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.