GRDHISTEQ(1) Generic Mapping Tools GRDHISTEQ(1)NAMEgrdhisteq - Histogram equalization for grid files
SYNOPSISgrdhisteq in_grdfile [ -Gout_grdfile ] [ -Cn_cells ] [ -D ] [ -N[norm]
] [ -Q ] [ -V ]
DESCRIPTIONgrdhisteq 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/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 seg‐
ments, 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 cpt‐
file 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.
in_grdfile
2-D binary grid file to be equalized. (See GRID FILE FORMATS
below).
OPTIONS
No space between the option flag and the associated arguments.
-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 grid file. Used with -N only. (See GRID
FILE FORMATS below).
-N 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 Use quadratic intensity scaling. [Default is linear].
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
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 facili‐
tates so called "packing" of grids, writing out floating point data as
2- or 4-byte integers. To specify the precision, scale and offset, the
user should add the suffix =id[/scale/offset[/nan]], where id is a two-
letter identifier of the grid type and precision, and scale and offset
are optional scale factor and offset to be applied to all grid values,
and nan is the value used to indicate missing data. When reading
grids, the format is generally automatically recognized. If not, the
same suffix can be added to input grid file names. See grdreformat(1)
and Section 4.17 of the GMT Technical Reference and Cookbook for more
information.
When reading a netCDF file that contains multiple grids, GMT will read,
by default, the first 2-dimensional grid that can find in that file. To
coax GMT into reading another multi-dimensional variable in the grid
file, append ?varname to the file name, where varname is the name of
the variable. Note that you may need to escape the special meaning of ?
in your shell program by putting a backslash in front of it, or by
placing the filename and suffix between quotes or double quotes. The
?varname suffix can also be used for output grids to specify a variable
name different from the default: "z". See grdreformat(1) and Section
4.18 of the GMT Technical Reference and Cookbook for more information,
particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
EXAMPLES
To find the height intervals that divide the file heights.grd into 16
divisions of equal area:
grdhisteq heights.grd -C 16 -D > levels.d
To make the poorly distributed intensities in the file raw_intens.grd
suitable for use with grdimage or grdview, run
grdhisteq raw_intens.grd -G smooth_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 grid (nx * ny) and the cumulative gaussian distribution func‐
tion 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 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 bring‐
ing more than 68% of the image into the range [-1, 1]. Alternatively,
supply a normalization factor with -N.
SEE ALSOgmtdefaults(1), GMT(1), grd2cpt(1), grdgradient(1), grdimage(1), grd‐
math(1), grdview(1), makecpt(1)GMT 4.5.14 1 Nov 2015 GRDHISTEQ(1)
