.. index:: ! grdhisteq .. include:: module_core_purpose.rst_ ********* grdhisteq ********* |grdhisteq_purpose| Synopsis -------- .. include:: common_SYN_OPTs.rst_ **gmt grdhisteq** *ingrid* [ |-G|\ *outgrid* ] [ |-C|\ *n_cells* ] [ |-D|\ [*file*] ] [ |-N|\ [*norm*] ] [ |-Q| ] [ |SYN_OPT-R| ] [ |SYN_OPT-V| ] [ |SYN_OPT-h| ] [ |SYN_OPT--| ] |No-spaces| 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 :doc:`grdimage` or :doc:`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 standard output 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 :doc:`makecpt` one can take this output and build a CPT; using the CPT with :doc:`grdimage` will result in an image with all levels of gray occurring equally. Alternatively, see :doc:`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 :doc:`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 :doc:`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 ------------------ .. |Add_ingrid| replace:: 2-D grid file to be equalized. .. include:: explain_grd_inout.rst_ :start-after: ingrid-syntax-begins :end-before: ingrid-syntax-ends Optional Arguments ------------------ .. _-C: **-C**\ *n_cells* Sets how many cells (or divisions) of data range to make [16]. .. _-D: **-D**\ [*file*] Dump level information to *file*, or standard output if no file is provided. .. _-G: .. |Add_outgrid| replace:: Give the name of the output grid file. Used with |-N| only. .. include:: /explain_grd_inout.rst_ :start-after: outgrid-syntax-begins :end-before: outgrid-syntax-ends .. _-N: **-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: **-Q** Quadratic output. Selects quadratic histogram equalization. [Default is linear]. .. |Add_-R| replace:: 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. |Add_-R_links| .. include:: explain_-R.rst_ :start-after: **Syntax** :end-before: **Description** .. |Add_-V| replace:: |Add_-V_links| .. include:: explain_-V.rst_ :start-after: **Syntax** :end-before: **Description** .. |Add_-h| unicode:: 0x20 .. just an invisible code .. include:: explain_-h.rst_ .. include:: explain_help.rst_ Examples -------- .. include:: explain_example.rst_ 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 :doc:`grdimage` or :doc:`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 :doc:`grdimage` or :doc:`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 :doc:`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 :doc:`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 -------- :doc:`gmt`, :doc:`gmt.conf`, :doc:`grd2cpt`, :doc:`grdgradient`, :doc:`grdimage`, :doc:`grdmath`, :doc:`grdview`, :doc:`makecpt`