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