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 com-
mon 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 segments, 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
cptfile with grdimage will result in an image with all lev-
els 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 ori-
ginal 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 grdfile
output with the Gaussian option, you will have a grdfile
whose values are distributed according to a gaussian distri-
bution 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 stan-
dard 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 devide the file
heights.grd into 16 divisions of equal area, try
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,
try
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 standard 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 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
gmtdefaults(l), gmt(l), grd2cpt(l), grdgradient(l),
grdimage(l), grdmath(l), grdview(l), makecpt(l)