NAME

       grd2cpt - Make linear or histogram-equalized color palette table from grid

SYNOPSIS

       grd2cpt  grid  [  -A[+]transparency ] [  -Ccpt ] [  -D[i] ] [  -E[nlevels] ] [  -F[R|r|h|c
       ][+c]] [  -Gzlo/zhi ] [  -I[c][z] ] [  -Lminlimit/maxlimit ] [  -M ] [  -N ] [  -Q[i|o]  ]
       [  -Rregion ] [  -Szstart/zstop/zinc ] [  -T-|+|_|= ] [  -V[level] ] [  -W[w] ] [  -Z ]

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

DESCRIPTION

       grd2cpt  reads  one  or  more  grid  files and writes a static color palette (CPT) file to
       standard output. The CPT is based on an existing dynamic master CPT of  your  choice,  and
       the  mapping  from  data  value  to  colors  is through the data's cumulative distribution
       function (CDF), so that the colors are histogram equalized. Thus if the  grid(s)  and  the
       resulting  CPT are used in grdimage with a linear projection, the colors will be uniformly
       distributed in area on the plot. Let z be the data values in the grid. Define CDF(Z) =  (#
       of  z  <  Z) / (# of z in grid). (NaNs are ignored). These z-values are then normalized to
       the master CPT and colors are sampled at the desired intervals.

       The color palette includes three additional colors beyond the range of z-values. These are
       the  background color (B) assigned to values lower than the lowest z-value, the foreground
       color (F) assigned to values higher than the  highest  z-value,  and  the  NaN  color  (N)
       painted  wherever  values  are  undefined.   For  color  tables  beyond  the  standard GMT
       offerings, visit cpt-city: http://soliton.vm.bytemark.co.uk/pub/cpt-city/.

       If the master CPT includes B, F, and N entries, these will be copied into the  new  master
       file.  If  not,  the parameters COLOR_BACKGROUND, COLOR_FOREGROUND, and COLOR_NAN from the
       gmt.conf file or the command line will be used. This default  behavior  can  be  overruled
       using the options -D, -M or -N.

       The  color  model (RGB, HSV or CMYK) of the palette created by makecpt will be the same as
       specified in the header of the master CPT. When there  is  no  COLOR_MODEL  entry  in  the
       master  CPT, the COLOR_MODEL specified in the gmt.conf file or on the command line will be
       used.

REQUIRED ARGUMENTS

       grid   Names of one or more grid files used to derive the color palette table.  All  grids
              need to have the same size and dimensions. (See GRID FILE FORMATS below).

OPTIONAL ARGUMENTS

       -A[+]transparency
              Sets  a  constant level of transparency (0-100) for all color slices.  Prepend + to
              also affect the fore-, back-, and nan-colors [Default is no transparency,  i.e.,  0
              (opaque)].

       -Ccpt  Selects  the  master  color  table  to  use  in the interpolation. Choose among the
              built-in tables (type grd2cpt to see the list) or give the name of an existing  CPT
              [Default   gives   a   rainbow   CPT].    Yet   another   option   is   to  specify
              -Ccolor1,color2[,color3,...]  to build a linear continuous CPT  from  those  colors
              automatically.   In  this  case  colorn can be a r/g/b triplet, a color name, or an
              HTML hexadecimal color (e.g. #aabbcc ).

       -D[i]  Select the back- and foreground colors to match the colors for lowest  and  highest
              z-values  in  the output CPT [Default uses the colors specified in the master file,
              or  those  defined  by  the  parameters  COLOR_BACKGROUND,  COLOR_FOREGROUND,   and
              COLOR_NAN].  Append  i to match the colors for the lowest and highest values in the
              input (instead of the output) CPT.

       -E[nlevels]
              Create a linear color table by using the grid z-range as the new limits in the CPT.
              Alternatively,  append  nlevels  and  we will resample the color table into nlevels
              equidistant slices.

       -F[R|r|h|c][+c]]
              Force output CPT to written with r/g/b codes, gray-scale values or color  name  (R,
              default)  or  r/g/b  codes  only  (r),  or  h-s-v  codes (h), or c/m/y/k codes (c).
              Optionally or alternatively, append +c to write discrete  palettes  in  categorical
              format.

       -Gzlo/zhi
              Truncate  the  incoming  CPT so that the lowest and highest z-levels are to zlo and
              zhi.  If one of these equal NaN then we leave that  end  of  the  CPT  alone.   The
              truncation takes place before any resampling. See also manipulating_CPTs

       -I[c][z]
              Append  c  [Default]  to  reverse the sense of color progression in the master CPT.
              Also exchanges the foreground and background colors, including those  specified  by
              the parameters COLOR_BACKGROUND and COLOR_FOREGROUND.  Append z to reverse the sign
              of z-values in the color table.  Note  that  this  change  of  z-direction  happens
              before  -G and -T values are used so the latter much be compatible with the changed
              z-range. See also manipulating_CPTs

       -Lminlimit/maxlimit
              Limit range of CPT to minlimit/maxlimit, and don't count data  outside  this  range
              when estimating CDF(Z). [Default uses min and max of data.]

       -M     Overrule  background,  foreground,  and NaN colors specified in the master CPT with
              the values of the  parameters  COLOR_BACKGROUND,  COLOR_FOREGROUND,  and  COLOR_NAN
              specified  in the gmt.conf file or on the command line. When combined with -D, only
              COLOR_NAN is considered.

       -N     Do not write out the background, foreground, and  NaN-color  fields  [Default  will
              write them].

       -Q[i|o]
              Selects  a logarithmic interpolation scheme [Default is linear].  -Qi expects input
              z-values to be log10(z), assigns colors, and writes  out  z  [Default].  -Qo  takes
              log10(z) first, assigns colors, and writes out z.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
              Specify the region of interest.

       -Szstart/zstop/zinc or -Sn
              Set steps in CPT. Calculate entries in CPT from zstart to zstop in steps of (zinc).
              Default chooses arbitrary values by a crazy scheme based on equidistant values  for
              a  Gaussian  CDF.   Use  -Sn  to  select  n  points  from  such a cumulative normal
              distribution [11].

       -T-|+|_|=
              Force the color table to be symmetric about zero (from -R to +R).  Append  flag  to
              set  the range R: - for R =|zmin|, + for R = |zmax|, _ for R = min(|zmin|, |zmax|),
              or = for R = max(|zmin|, |zmax|).

       -V     Verbose operation. This will write CDF(Z) estimates to stderr. [Default is silent.]

       -W     Do not interpolate the input color table but pick the output colors starting at the
              beginning of the map. This is particularly useful in combination with a categorical
              color table. Cannot be used in combination with  -Z.   Alternatively,  use  -Ww  to
              produce a wrapped (cyclic) color table that endlessly repeats its range.

       -Z     Will  create  a continuous color palette. [Default is discontinuous, i.e., constant
              color intervals]

       -^ or just -
              Print a short message about the syntax of the command, then exits (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 exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation  of  all  options,
              then exits.

GRID FILE FORMATS

       By  default  GMT  writes  out grid as single precision floats in a COARDS-complaint netCDF
       file format. However, GMT is able to produce grid files in many other commonly  used  grid
       file formats and also facilitates so called "packing" of grids, writing out floating point
       data as 1- or 2-byte integers. (more ...)

NOTES ON TRANSPARENCY

       The PostScript language originally had no accommodation for transparency.  However,  Adobe
       added  an  extension that allows developers to encode some forms of transparency using the
       PostScript language model but it is only realized when converting the  PostScript  to  PDF
       (and  via  PDF  to  any  raster  image  format).   GMT  uses this model but there are some
       limitations: Transparency can only be controlled on a per-object or per-layer basis.  This
       means  that  a  color  specifications  (such  as  those  in CPTs of given via command-line
       options) only apply to vector graphic items (i.e., text, lines, polygon fills)  or  to  an
       entire layer (which could include items such as PostScript images).  This limitation rules
       out any mechanism of controlling transparency in such images on a pixel level.

COLOR ALIASING

       For best result when -E is used we recommend you do no append a  specific  nlevels.   This
       way  the original CPT is used exactly as is but the z boundaries are adjusted to match the
       grid limits.  Otherwise you may, depending on the nature of the input CPT, miss aspects of
       the color changes by aliasing the signal.

EXAMPLES

       Sometimes you don't want to make a CPT (yet) but would find it helpful to know that 90% of
       your data lie between z1 and z2, something you cannot learn from grdinfo. So  you  can  do
       this to see some points on the CDF(Z) curve (use -V option to see more):

              gmt grd2cpt mydata.nc -V > /dev/null

       To  make  a  CPT  with entries from 0 to 200 in steps of 20, and ignore data below zero in
       computing CDF(Z), and use the built-in master cpt file relief, run

              gmt grd2cpt mydata.nc -Crelief -L0/10000 -S0/200/20 > mydata.cpt

SEE ALSO

       gmt, gmt.conf, grdhisteq, grdinfo, makecpt

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe