NAME
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 equalization 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 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 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 output of grdgradient. For shading purposes it is desired that the
data have a smooth distribution, such as a gaussian. If you run grdhis-
teq on output from grdgradient and make a grdfile output with the Gaus-
sian 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 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.
No space between the option flag and the associated arguments.
Use upper case for the option flags and lower case for modifiers.
in_grdfile
2-D binary grd file to be equalized.
OPTIONS
-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 grdfile 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 linear].
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
EXAMPLES
To find the height intervals that divide the file heights.grd into 16
divisions of equal area:
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, run
grdhisteq raw_intens.grd -Gsmooth_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 grdfile (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 stan-
dard 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 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 multiply-
ing 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]. Alterna-
tively, supply a normalization factor with -N.
SEE ALSO
gmtdefaults(l), gmt(l), grd2cpt(l), grdgradient(l), grdimage(l), grd-
math(l), grdview(l), makecpt(l)
GMT4.0 1 Oct 2004 GRDHISTEQ(l)
Man(1) output converted with
man2html