grdhisteq¶

Perform histogram equalization for a grid

Synopsis¶

gmt grdhisteq ingrid [ -Goutgrid ] [ -Cn_cells ] [ -D[file] ] [ -N[norm] ] [ -Q ] [ -Rregion ] [ -V[level] ] [ -hheaders ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description¶

grdhisteq 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 or 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 or file 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; using the CPT 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 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 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 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 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 negative input value, and so on.

Required Arguments¶

ingrid[=ID|?varname][+bband][+ddivisor][+ninvalid] [+ooffset][+sscale]

2-D grid file to be equalized. Optionally, append =ID for reading a specific file format [Default is =nf] or ?varname for a specific netCDF variable [Default is the first 2-D grid found by GMT] (See full description). The following modifiers are supported:

+b - Select a band (for images only) [Default is 0].

+d - Divide data values by the given divisor [Default is 1].

+n - Replace data values matching invalid with NaN.

+o - Offset data values by the given offset [Default is 0].

+s - Scale data values by the given scale [Default is 1].

Note: Any offset is added after any scaling.

Optional Arguments¶

-Cn_cells: Sets how many cells (or divisions) of data range to make [16].

-D[file]: Dump level information to file, or standard output if no file is provided.

-Goutgrid[=ID][+ddivisor][+ninvalid] [+ooffset|a][+sscale|a] [:driver[dataType][+coptions]]

Give the name of the output grid file. Used with -N only. Optionally, append =ID for writing a specific file format (See full description). The following modifiers are supported:

+d - Divide data values by given divisor [Default is 1].

+n - Replace data values matching invalid with a NaN.

+o - Offset data values by the given offset, or append a for automatic range offset to preserve precision for integer grids [Default is 0].

+s - Scale data values by the given scale, or append a for automatic scaling to preserve precision for integer grids [Default is 1].

Note: Any offset is added before any scaling. +sa also sets +oa (unless overridden). To write specific formats via GDAL, use = gd and supply driver (and optionally dataType) and/or one or more concatenated GDAL -co options using +c. See the “Writing grids and images” cookbook section for more details.

-N[norm]: Gaussian output. Use with -G to make an output grid with standard normal scores. Append norm to force the scores to fall in the ±*norm* range [Default is standard normal scores].

-Q: Quadratic output. Selects quadratic histogram equalization. [Default is linear].

-Rxmin/xmax/ymin/ymax[+r][+uunit]: Specify the region of interest. Using the -R option will select a subsection of ingrid grid. If this subsection exceeds the boundaries of the grid, only the common region will be extracted. (See full description) (See cookbook information).

-V[level]: Select verbosity level [w]. (See full description) (See cookbook information).

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …): Skip or produce header record(s).

-^ or just -: Print a short message about the syntax of the command, then exit (NOTE: on Windows just use -).
-+ or just +: Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.
-? or no arguments: Print a complete usage (help) message, including the explanation of all options, then exit.
--PAR=value: Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Examples¶

Note: Below are some examples of valid syntax for this module. The examples that use remote files (file names starting with @) can be cut and pasted into your terminal for testing. Other commands requiring input files are just dummy examples of the types of uses that are common but cannot be run verbatim as written.

To find the height intervals that divide the selected region of the remote file earth_relief_05m into 16 divisions of equal area:

gmt grdhisteq -C16 -D @earth_relief_05m -R0/20/0/20 > levels.txt

To make the poorly distributed intensities in the file raw_intens.nc suitable for use with grdimage or grdview, run

gmt grdhisteq raw_intens.nc -Gsmooth_intens.nc -N -V

Notes¶

For geographical grids we do a weighted histogram equalization since the area of each node varies with latitude.
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 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 grid. But if N is very large, it is possible for x to be greater than 4. Therefore, with the grdview 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.