grdhisteq(1)

1GRDHISTEQ(1)                 Generic Mapping Tools                GRDHISTEQ(1)
2
3
4

NAME

6       grdhisteq - Histogram equalization for grid files
7

SYNOPSIS

9       grdhisteq  in_grdfile [ -Gout_grdfile ] [ -Cn_cells ] [ -D ] [ -N[norm]
10       ] [ -Q ] [ -V ]
11

DESCRIPTION

13       grdhisteq allows the user to find the data values which divide a  given
14       grid  file  into patches of equal area.  One common use of grdhisteq is
15       in a kind of histogram equalization of an image.  In this  application,
16       the  user  might  have a grid of flat topography with a mountain in the
17       middle.  Ordinary gray shading of this  file  (using  grdimage/grdview)
18       with  a  linear mapping from topography to graytone will result in most
19       of the image being very dark  gray,  with  the  mountain  being  almost
20       white.   One  could  use  grdhisteq to write to stdout an ASCII list of
21       those data values which divide the range of the data into n_cells  seg‐
22       ments,  each  of  which  has  an equal area in the image.  Using awk or
23       makecpt one can take this output and build a cpt file; using  the  cpt‐
24       file  with  grdimage  will  result  in an image with all levels of gray
25       occurring equally.  Alternatively, see grd2cpt.
26
27       The second common use of grdhisteq is in writing a grid with statistics
28       based on some kind of cumulative distribution function.  In this appli‐
29       cation, the output has relative highs and lows in the same (x,y)  loca‐
30       tions  as  the  input file, but the values are changed to reflect their
31       place in some cumulative distribution.  One example would  be  to  find
32       the lowest 10% of the data:  Take a grid, run grdhisteq and make a grid
33       using n_cells = 10, and then contour the result to trace the 1 contour.
34       This will enclose the lowest 10% of the data, regardless of their orig‐
35       inal values.  Another example is in equalizing the output of  grdgradi‐
36       ent.   For  shading  purposes it is desired that the data have a smooth
37       distribution, such as a gaussian.  If you run grdhisteq on output  from
38       grdgradient  and  make a grid file output with the Gaussian option, you
39       will have a grid whose values are distributed according to  a  gaussian
40       distribution  with zero mean and unit variance.  The locations of these
41       values will correspond to the locations of the input; that is, the most
42       negative  output  value will be in the (x,y) location of the most nega‐
43       tive input value, and so on.
44
45       in_grdfile
46              2-D binary grid file to be equalized.  (See  GRID  FILE  FORMATS
47              below).
48

OPTIONS

50       No space between the option flag and the associated arguments.
51
52       -C     Sets how many cells (or divisions) of data range to make.
53
54       -D     Dump level information to standard output.
55
56       -G     Name  of  output  2-D  grid file.  Used with -N only.  (See GRID
57              FILE FORMATS below).
58
59       -N     Gaussian output.  Use with -G to make an output grid with  stan‐
60              dard  normal scores.  Append norm to force the scores to fall in
61              the <-1,+1> range [Default is standard normal scores].
62
63       -Q     Use quadratic intensity scaling.  [Default is linear].
64
65       -V     Selects verbose mode, which will send progress reports to stderr
66              [Default runs "silently"].
67

GRID FILE FORMATS

69       By  default GMT writes out grid as single precision floats in a COARDS-
70       complaint netCDF file format.  However, GMT is  able  to  produce  grid
71       files  in  many  other commonly used grid file formats and also facili‐
72       tates so called "packing" of grids, writing out floating point data  as
73       2-  or 4-byte integers. To specify the precision, scale and offset, the
74       user should add the suffix =id[/scale/offset[/nan]], where id is a two-
75       letter  identifier of the grid type and precision, and scale and offset
76       are optional scale factor and offset to be applied to all grid  values,
77       and  nan  is  the  value  used  to indicate missing data.  When reading
78       grids, the format is generally automatically recognized.  If  not,  the
79       same  suffix can be added to input grid file names.  See grdreformat(1)
80       and Section 4.17 of the GMT Technical Reference and Cookbook  for  more
81       information.
82
83       When reading a netCDF file that contains multiple grids, GMT will read,
84       by default, the first 2-dimensional grid that can find in that file. To
85       coax  GMT  into  reading another multi-dimensional variable in the grid
86       file, append ?varname to the file name, where varname is  the  name  of
87       the variable. Note that you may need to escape the special meaning of ?
88       in your shell program by putting a backslash in  front  of  it,  or  by
89       placing  the  filename and suffix between quotes or double quotes.  The
90       ?varname suffix can also be used for output grids to specify a variable
91       name  different  from the default: "z".  See grdreformat(1) and Section
92       4.18 of the GMT Technical Reference and Cookbook for more  information,
93       particularly on how to read splices of 3-, 4-, or 5-dimensional grids.
94

EXAMPLES

96       To  find  the height intervals that divide the file heights.grd into 16
97       divisions of equal area:
98
99       grdhisteq heights.grd -C16 -D > levels.d
100
101       To make the poorly distributed intensities in the  file  raw_intens.grd
102       suitable for use with grdimage or grdview, run
103
104       grdhisteq raw_intens.grd -Gsmooth_intens.grd -N -V
105

RESTRICTIONS

107       If  you use grdhisteq to make a gaussian output for gradient shading in
108       grdimage or grdview, you should be aware of the following:  the  output
109       will be in the range [-x, x], where x is based on the number of data in
110       the input grid (nx * ny) and the cumulative gaussian distribution func‐
111       tion  F(x).  That is, let N = nx * ny.  Then x will be adjusted so that
112       F(x) = (N - 1 + 0.5)/N.  Since about 68% of the values from a  standard
113       normal  distribution fall within +/- 1, this will be true of the output
114       grid.  But if N is very large, it is possible for x to be greater  than
115       4.   Therefore,  with  the  grdimage  program clipping gradients to the
116       range [-1, 1], you will get correct shading of 68% of your data,  while
117       16%  of  them  will be clipped to -1 and 16% of them clipped to +1.  If
118       this makes too much of the image too light or too dark, you should take
119       the output of grdhisteq and rescale it using grdmath and multiplying by
120       something less than 1.0, to shrink the range of the values, thus bring‐
121       ing  more than 68% of the image into the range [-1, 1].  Alternatively,
122       supply a normalization factor with -N.
123