1GRDHISTEQ(1) GMT GRDHISTEQ(1)
2
6 grdhisteq - Perform histogram equalization for a grid
7
9 grdhisteq in_grdfile [ -Gout_grdfile ] [ -Cn_cells ] [ -D[file] ] [
10 -N[norm] ] [ -Q ]
11 -Rregion
12 -V[level]
13 Note: No space is allowed between the option flag and the associated
15 arguments.
16
18 grdhisteq allows the user to find the data values which divide a given
19 grid file into patches of equal area. One common use of grdhisteq is in
20 a kind of histogram equalization of an image. In this application, the
21 user might have a grid of flat topography with a mountain in the mid‐
22 dle. Ordinary gray shading of this file (using grdimage or grdview)
23 with a linear mapping from topography to graytone will result in most
24 of the image being very dark gray, with the mountain being almost
25 white. One could use grdhisteq to write to stdout or file an ASCII list
26 of those data values which divide the range of the data into n_cells
27 segments, each of which has an equal area in the image. Using awk or
28 makecpt one can take this output and build a CPT; using the CPT with
29 grdimage will result in an image with all levels of gray occurring
30 equally. Alternatively, see grd2cpt.
31 The second common use of grdhisteq is in writing a grid with statistics
33 based on some kind of cumulative distribution function. In this appli‐
34 cation, the output has relative highs and lows in the same (x,y) loca‐
35 tions as the input file, but the values are changed to reflect their
36 place in some cumulative distribution. One example would be to find the
37 lowest 10% of the data: Take a grid, run grdhisteq and make a grid
38 using n_cells = 10, and then contour the result to trace the 1 contour.
39 This will enclose the lowest 10% of the data, regardless of their orig‐
40 inal values. Another example is in equalizing the output of grdgradi‐
41 ent. For shading purposes it is desired that the data have a smooth
42 distribution, such as a Gaussian. If you run grdhisteq on output from
43 grdgradient and make a grid file output with the Gaussian option, you
44 will have a grid whose values are distributed according to a Gaussian
45 distribution with zero mean and unit variance. The locations of these
46 values will correspond to the locations of the input; that is, the most
47 negative output value will be in the (x,y) location of the most nega‐
48 tive input value, and so on.
49
51 in_grdfile
52 2-D grid file to be equalized. (See GRID FILE FORMATS below).
53
55 -Cn_cells
56 Sets how many cells (or divisions) of data range to make [16].
57 -D Dump level information to file, or standard output if no file is
59 provided.
60 -Gout_grdfile
62 Name of output 2-D grid file. Used with -N only. (See GRID FILE
63 FORMATS below).
64 -N[norm]
66 Gaussian output. Use with -G to make an output grid with stan‐
67 dard normal scores. Append norm to force the scores to fall in
68 the <-1,+1> range [Default is standard normal scores].
69 -Q Quadratic output. Selects quadratic histogram equalization.
71 [Default is linear].
72 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
74 Specify the region of interest. Using the -R option will select
75 a subsection of in_grdfile grid. If this subsection exceeds the
76 boundaries of the grid, only the common region will be
77 extracted.
78 -V[level] (more ...)
80 Select verbosity level [c].
81 -^ or just -
83 Print a short message about the syntax of the command, then
84 exits (NOTE: on Windows just use -).
85 -+ or just +
87 Print an extensive usage (help) message, including the explana‐
88 tion of any module-specific option (but not the GMT common
89 options), then exits.
90 -? or no arguments
92 Print a complete usage (help) message, including the explanation
93 of all options, then exits.
94
96 By default GMT writes out grid as single precision floats in a
97 COARDS-complaint netCDF file format. However, GMT is able to produce
98 grid files in many other commonly used grid file formats and also
99 facilitates so called "packing" of grids, writing out floating point
100 data as 1- or 2-byte integers. (more ...)
101
103 To find the height intervals that divide the file heights.nc into 16
104 divisions of equal area:
105 gmt grdhisteq heights.nc -C16 -D > levels.d
107 To make the poorly distributed intensities in the file raw_intens.nc
109 suitable for use with grdimage or grdview, run
110 gmt grdhisteq raw_intens.nc -Gsmooth_intens.nc -N -V
112
114 1. For geographical grids we do a weighted histogram equalization since
115 the area of each node varies with latitude.
116 2. If you use grdhisteq to make a Gaussian output for gradient shading
118 in grdimage or grdview, you should be aware of the following: the
119 output will be in the range [-x, x], where x is based on the number
120 of data in the input grid (nx * ny) and the cumulative Gaussian dis‐
121 tribution function F(x). That is, let N = nx * ny. Then x will be
122 adjusted so that F(x) = (N - 1 + 0.5)/N. Since about 68% of the val‐
123 ues from a standard normal distribution fall within +/- 1, this will
124 be true of the output grid. But if N is very large, it is possible
125 for x to be greater than 4. Therefore, with the grdview program
126 clipping gradients to the range [-1, 1], you will get correct shad‐
127 ing of 68% of your data, while 16% of them will be clipped to -1 and
128 16% of them clipped to +1. If this makes too much of the image too
129 light or too dark, you should take the output of grdhisteq and
130 rescale it using grdmath and multiplying by something less than 1.0,
131 to shrink the range of the values, thus bringing more than 68% of
132 the image into the range [-1, 1]. Alternatively, supply a normaliza‐
133 tion factor with -N.
134
136 gmt, gmt.conf, grd2cpt, grdgradient, grdimage, grdmath, grdview,
137 makecpt
138
140 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
1415.4.5 Feb 24, 2019 GRDHISTEQ(1)