1TRIANGULATE(1)                        GMT                       TRIANGULATE(1)
2
3
4

NAME

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

SYNOPSIS

10       triangulate [ table ] [  -Cslpfile ] [  -Dx|y ] [  -Eempty ] [   -Ggrd‐
11       file  ] [  -Iincrement ] [  -Jparameters ] [  -M ] [  -N ] [  -Q[n] ] [
12       -Rregion ] [  -S ] [  -V[level] ] [  -Z ] [ -bbinary ] [ -dnodata  ]  [
13       -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -r ] [ -:[i|o] ]
14
15       Note:  No  space  is allowed between the option flag and the associated
16       arguments.
17

DESCRIPTION

19       triangulate reads one or more ASCII  [or  binary]  files  (or  standard
20       input) containing x,y[,z] and performs Delaunay triangulation, i.e., it
21       find how the points should be connected to give  the  most  equilateral
22       triangulation  possible. If a map projection (give -R and -J) is chosen
23       then it is applied before the triangulation is calculated. By  default,
24       the  output  is triplets of point id numbers that make up each triangle
25       and is written to standard output. The id numbers refer to  the  points
26       position  (line  number, starting at 0 for the first line) in the input
27       file. As an option, you may choose to create a  multiple  segment  file
28       that can be piped through psxy to draw the triangulation network. If -G
29       -I are set a grid will be calculated based on the  surface  defined  by
30       the  planar  triangles. The actual algorithm used in the triangulations
31       is either that of  Watson  [1982]  [Default]  or  Shewchuk  [1996]  (if
32       installed;  type  triangulate  - to see which method is selected). This
33       choice is made  during  the  GMT  installation.   Furthermore,  if  the
34       Shewchuk  algorithm is installed then you can also perform the calcula‐
35       tion of Voronoi polygons and optionally grid your data via the  natural
36       nearest neighbor algorithm.
37

REQUIRED ARGUMENTS

39       None.
40

OPTIONAL ARGUMENTS

42       table  One  or  more ASCII (or binary, see -bi[ncols][type]) data table
43              file(s) holding a number of data columns. If no tables are given
44              then we read from standard input.
45
46       -Cslpfile
47
48              Read a slope grid (in radians) and compute the propagated uncer‐
49              tainty in the
50                     bathymetry using the CURVE algorithm [Zambo et al, 20xx].
51                     Requires  the -G option to specify the output grid.  Note
52                     that the slpgrid sets the domain for the output  grid  so
53                     -R,  -I,  [-r]  are not required.  Cannot be used in con‐
54                     junction with -D, -F, -M, -N, -Q, -S and -T.
55
56       -Dx|y  Take either the x- or y-derivatives of  surface  represented  by
57              the planar facets (only used when -G is set).
58
59       -Eempty
60              Set the value assigned to empty nodes when -G is set [NaN].
61
62       -Ggrdfile
63              Use  triangulation to grid the data onto an even grid (specified
64              with -R -I). Append the name of the output grid file. The inter‐
65              polation  is  performed  in the original coordinates, so if your
66              triangles are close to the poles you are better  off  projecting
67              all  data  to a local coordinate system before using triangulate
68              (this is true of all gridding routines) or instead  select  sph‐
69              triangulate.  For natural nearest neighbor gridding you must add
70              -Qn.
71
72       -Ixinc[unit][+e|n][/yinc[unit][+e|n]]
73              x_inc [and optionally y_inc] is the  grid  spacing.  Optionally,
74              append  a  suffix  modifier. Geographical (degrees) coordinates:
75              Append m to indicate arc minutes or s to indicate  arc  seconds.
76              If  one of the units e, f, k, M, n or u is appended instead, the
77              increment is assumed to be given in meter, foot, km, Mile,  nau‐
78              tical  mile  or  US  survey foot, respectively, and will be con‐
79              verted to the equivalent degrees longitude at the  middle  lati‐
80              tude  of  the region (the conversion depends on PROJ_ELLIPSOID).
81              If y_inc is given but set to 0 it will be reset equal to  x_inc;
82              otherwise  it will be converted to degrees latitude. All coordi‐
83              nates: If +e is appended then the corresponding max x (east)  or
84              y  (north)  may  be  slightly  adjusted to fit exactly the given
85              increment [by default the increment may be adjusted slightly  to
86              fit  the  given domain]. Finally, instead of giving an increment
87              you may specify the number of nodes desired by appending  +n  to
88              the  supplied  integer  argument; the increment is then recalcu‐
89              lated from the number of nodes and  the  domain.  The  resulting
90              increment  value  depends  on  whether you have selected a grid‐
91              line-registered or pixel-registered grid;  see  App-file-formats
92              for  details.  Note:  if -Rgrdfile is used then the grid spacing
93              has already been initialized; use -I to override the values.
94
95       -Jparameters (more ...)
96              Select map projection.
97
98       -M     Output triangulation network as multiple line segments separated
99              by a segment header record.
100
101       -N     Used  in  conjunction  with -G to also write the triplets of the
102              ids of all the Delaunay vertices [Default only writes the grid].
103
104       -Q[n]  Output the edges of the Voronoi cells instead [Default is Delau‐
105              nay triangle edges]. Requires -R and is only available if linked
106              with the Shewchuk [1996] library. Note that  -Z  is  ignored  on
107              output. Optionally, append n for combining the edges into closed
108              Voronoi polygons.
109
110       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
111              Specify the region of interest.
112
113       -S     Output triangles as polygon  segments  separated  by  a  segment
114              header record. Requires Delaunay triangulation.
115
116       -T     Output edges or polygons even if gridding has been selected with
117              the -G option [Default will  not  output  the  triangulation  or
118              Voronoi polygons is gridding is selected].
119
120       -V[level] (more ...)
121              Select verbosity level [c].
122
123       -Z     Controls  whether  we read (x,y) or (x,y,z) data and if z should
124              be output when -M or -S are used [Read (x,y) only].
125
126       -bi[ncols][t] (more ...)
127              Select native binary input. [Default is 2 input columns].
128
129       -bo[ncols][type] (more ...)
130              Select native binary output. [Default is same as  input].   Node
131              ids are stored as double triplets.
132
133       -d[i|o]nodata (more ...)
134              Replace  input  columns  that  equal  nodata with NaN and do the
135              reverse on output.
136
137       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
138              Only accept data records that match the given pattern.
139
140       -f[i|o]colinfo (more ...)
141              Specify data types of input and/or output columns.
142
143       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
144              Skip or produce header record(s).
145
146       -icols[+l][+sscale][+ooffset][,...] (more ...)
147              Select input columns and transformations (0 is first column).
148
149       -r (more ...)
150              Set pixel node registration [gridline]. (Only valid with -G).
151
152       -:[i|o] (more ...)
153              Swap 1st and 2nd column on input and/or output.
154
155       -^ or just -
156              Print a short message about the  syntax  of  the  command,  then
157              exits (NOTE: on Windows just use -).
158
159       -+ or just +
160              Print  an extensive usage (help) message, including the explana‐
161              tion of any module-specific  option  (but  not  the  GMT  common
162              options), then exits.
163
164       -? or no arguments
165              Print a complete usage (help) message, including the explanation
166              of all options, then exits.
167

ASCII FORMAT PRECISION

169       The ASCII output formats of numerical data are controlled by parameters
170       in  your  gmt.conf file. Longitude and latitude are formatted according
171       to  FORMAT_GEO_OUT,  absolute  time  is  under  the  control  of   FOR‐
172       MAT_DATE_OUT  and FORMAT_CLOCK_OUT, whereas general floating point val‐
173       ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
174       mat  in effect can lead to loss of precision in ASCII output, which can
175       lead to various problems downstream. If you  find  the  output  is  not
176       written with enough precision, consider switching to binary output (-bo
177       if available) or specify more decimals using the FORMAT_FLOAT_OUT  set‐
178       ting.
179

GRID VALUES PRECISION

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

EXAMPLES

191       To triangulate the points in the file samples.xyz, store  the  triangle
192       information  in  a  binary file, and make a grid for the given area and
193       spacing, use
194
195              gmt triangulate samples.xyz -bo -R0/30/0/30 -I2 -Gsurf.nc > samples.ijk
196
197       To draw the optimal Delaunay triangulation network based  on  the  same
198       file using a 15-cm-wide Mercator map, use
199
200              gmt triangulate samples.xyz -M -R-100/-90/30/34 -JM15c | gmt psxy \
201                  -R-100/-90/30/34 -JM15c -W0.5p -B1 > network.ps
202
203       To instead plot the Voronoi cell outlines, try
204
205              gmt triangulate samples.xyz -M -Q -R-100/-90/30/34 -JM15c | \
206                  gmt psxy -R-100/-90/30/34 -JM15c -W0.5p -B1 > cells.ps
207
208       To  combine the Voronoi outlines into polygons and paint them according
209       to their ID, try
210
211              gmt triangulate samples.xyz -M -Qn -R-100/-90/30/34 -JM15c | \
212                  gmt psxy -R-100/-90/30/34 -JM15c -W0.5p+cf -L -B1 -Ccolors.cpt -L > polygons.ps
213
214       To grid the data using the natural nearest neighbor algorithm, try
215
216              gmt triangulate samples.xyz -Gnnn.nc -Qn -R-100/-90/30/34 -I0.5
217

NOTES

219       The uncertainty propagation for bathymetric grids requires  both  hori‐
220       zontal  and  vertical  uncertainties  and  these are weighted given the
221       local slope.  See the references for more details.
222

SEE ALSO

224       gmt, greenspline, nearneighbor, pscontour, sphdistance, sphinterpolate,
225       sphtriangulate, surface
226

REFERENCES

228       Watson,  D.  F., 1982, Acord: Automatic contouring of raw data, Comp. &
229       Geosci., 8, 97-101.
230
231       Shewchuk, J. R., 1996, Triangle: Engineering a 2D Quality Mesh  Genera‐
232       tor  and Delaunay Triangulator, First Workshop on Applied Computational
233       Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
234
235       Shewchuk's Homepage
236
238       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
239
240
241
242
2435.4.5                            Feb 24, 2019                   TRIANGULATE(1)
Impressum