NAME

       triangulate  -  Do  optimal  (Delaunay) triangulation and gridding of Cartesian table data
       [method]

SYNOPSIS

       triangulate [ table ] [ x|y ] [ empty ] [ grdfile ] [ increment ] [ parameters ] [  ] [  ]
       [   ]  [  region  ]  [   ]  [ [level] ] [  ] [ -b<binary> ] [ -d<nodata> ] [ -f<flags> ] [
       -h<headers> ] [ -i<flags> ] [ -r ] [ -:[i|o] ]

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

DESCRIPTION

       triangulate reads one or more ASCII [or  binary]  files  (or  standard  input)  containing
       x,y[,z]  and  performs  Delaunay  triangulation,  i.e.,  it  find how the points should be
       connected to give the most equilateral triangulation possible. If a map  projection  (give
       -R  and  -J)  is  chosen  then  it  is  applied before the triangulation is calculated. By
       default, the output is triplets of point id numbers that make  up  each  triangle  and  is
       written  to  standard  output.  The  id numbers refer to the points position (line number,
       starting at 0 for the first line) in the input file. As  an  option,  you  may  choose  to
       create  a  multiple  segment file that can be piped through psxy to draw the triangulation
       network. If -G -I are set a grid will be calculated based on the surface  defined  by  the
       planar triangles. The actual algorithm used in the triangulations is either that of Watson
       [1982] [Default] or Shewchuk [1996] (if installed; type triangulate - to see which  method
       is selected). This choice is made during the GMT installation.

REQUIRED ARGUMENTS

       None.

OPTIONAL ARGUMENTS

       table  One  or  more  ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a
              number of data columns. If no tables are given then we read from standard input.

       -Dx|y  Take either the x- or y-derivatives of surface represented  by  the  planar  facets
              (only used when -G is set).

       -Eempty
              Set the value assigned to empty nodes when -G is set [NaN].

       -Ggrdfile
              Use triangulation to grid the data onto an even grid (specified with -R -I). Append
              the name of the output grid file. The interpolation is performed  in  the  original
              coordinates,  so  if  your  triangles  are  close  to  the poles you are better off
              projecting all data to a local coordinate system before using triangulate (this  is
              true of all gridding routines).

       -I     x_inc  [and optionally y_inc] sets the grid size for optional grid output (see -G).
              Append m to indicate arc minutes or s to indicate arc seconds.

       -Jparameters (more ...)
              Select map projection.

       -M     Output triangulation network as multiple  line  segments  separated  by  a  segment
              header record.

       -N     Used  in  conjunction  with  -G  to  also  write the triplets of the ids of all the
              Delaunay vertices [Default only writes the grid].

       -Q     Output the edges of the Voronoi cells instead [Default is Delaunay triangle edges].
              Requires  -R and is only available if linked with the Shewchuk [1996] library. Note
              that -Z is ignored on output.

       -R[unit]xmin/xmax/ymin/ymax[r] (more ...)
              Specify the region of interest.

       -S     Output triangles as polygon segments separated by a segment header record. Requires
              Delaunay triangulation.

       -V[level] (more ...)
              Select verbosity level [c].

       -Z     Controls whether we read (x,y) or (x,y,z) data and if z should be output when -M or
              -S are used [Read (x,y) only].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is same as input].  Node ids  are  stored  as
              double triplets.

       -d[i|o]nodata (more ...)
              Replace input columns that equal nodata with NaN and do the reverse on output.

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

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

       -icols[l][sscale][ooffset][,...] (more ...)
              Select input columns (0 is first column).

       -r (more ...)
              Set pixel node registration [gridline]. (Only valid with -G).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              use just -).

       -+ 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 options, then
              exits.

       --version
              Print GMT version and exit.

       --show-datadir
              Print full path to GMT share directory and exit.

ASCII FORMAT PRECISION

       The ASCII output formats of numerical data are controlled by parameters in  your  gmt.conf
       file.  Longitude  and  latitude  are  formatted according to FORMAT_GEO_OUT, whereas other
       values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can
       lead to loss of precision in the output, which can lead to various problems downstream. If
       you find the output is not written with enough precision,  consider  switching  to  binary
       output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.

GRID VALUES PRECISION

       Regardless  of  the  precision of the input data, GMT programs that create grid files will
       internally hold the grids in 4-byte floating point arrays. This is done to conserve memory
       and  furthermore  most  if  not  all  real  data can be stored using 4-byte floating point
       values. Data with  higher  precision  (i.e.,  double  precision  values)  will  lose  that
       precision  once  GMT  operates  on  the  grid  or  writes  out new grids. To limit loss of
       precision when processing data you should always consider normalizing the  data  prior  to
       processing.

EXAMPLES

       To  triangulate  the  points  in the file samples.xyz, store the triangle information in a
       binary file, and make a grid for the given area and spacing, use

              gmt triangulate samples.xyz -bo -R0/30/0/30 -I2 -Gsurf.nc > samples.ijk

       To draw the optimal Delaunay  triangulation  network  based  on  the  same  file  using  a
       15-cm-wide Mercator map, use

              gmt triangulate samples.xyz -M -R-100/-90/30/34 -JM15c | gmt psxy \
                  -R-100/-90/30/34 -JM15c -W0.5p -B1 > network.ps

       To instead plot the Voronoi cell outlines, try

              gmt triangulate samples.xyz -M -Q -R-100/-90/30/34 -JM15c | \
                  gmt psxy -R-100/-90/30/34 -JM15c -W0.5p -B1 > cells.ps

SEE ALSO

       gmt, greenspline, nearneighbor, pscontour, sphinterpolate, sphtriangulate, surface

REFERENCES

       Watson, D. F., 1982, Acord: Automatic contouring of raw data, Comp. & Geosci., 8, 97-101.

       Shewchuk,  J.  R.,  1996,  Triangle:  Engineering a 2D Quality Mesh Generator and Delaunay
       Triangulator,  First  Workshop  on  Applied  Computational  Geometry  (Philadelphia,  PA),
       124-133, ACM, May 1996.

       Shewchuk's Homepage

COPYRIGHT

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