1TRIANGULATE(1)               Generic Mapping Tools              TRIANGULATE(1)
2
3
4

NAME

6       triangulate  -  Perform  optimal Delauney triangulation and gridding of
7       Cartesian data [method]
8

SYNOPSIS

10       triangulate infiles [ -Dx|y ] [ -Eempty ]  [  -F  ]  [  -Ggrdfile  ]  [
11       -H[i][nrec]  ] [ -Ixinc[unit][=|+][/yinc[unit][=|+]] ] [ -Jparameters ]
12       [ -M[i|o][flag] ] [ -Rwest/east/south/north[r] ]  [  -V  ]  [  -Z  ]  [
13       -:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ]
14

DESCRIPTION

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

OPTIONS

37       -D     Take either the x- or y-derivatives of  surface  represented  by
38              the planar facets (only used when -G is set).
39
40       -E     Set the value assigned to empty nodes when -G is set [NaN].
41
42       -F     Force  pixel  node  registration  [Default is gridline registra‐
43              tion].  (Node registrations are defined in GMT Cookbook Appendix
44              B on grid file formats.)  Only valid with -G).
45
46       -G     Use  triangulation to grid the data onto an even grid (specified
47              with -I, -R).  Append the name of the  output  grid  file.   The
48              interpolation  is  performed  in the original coordinates, so if
49              your triangles are close to the poles you are  better  off  pro‐
50              jecting  all data to a local coordinate system before using tri‐
51              angulate (this is true of all gridding routines).
52
53       -H     Input file(s) has Header record(s).  Number  of  header  records
54              can be changed by editing your .gmtdefaults4 file.  If used, GMT
55              default is 1 header record. Use -Hi if only  input  data  should
56              have  header  records  [Default will write out header records if
57              the input data have them]. Blank lines and lines starting with #
58              are always skipped.
59
60       -I     x_inc  [and  optionally  y_inc] sets the grid  size for optional
61              grid output (see -G).  Append m to  indicate  minutes  or  c  to
62              indicate seconds.
63
64       -J     Selects  the  map  projection. Scale is UNIT/degree, 1:xxxxx, or
65              width in UNIT (upper case modifier).  UNIT is cm,  inch,  or  m,
66              depending on the MEASURE_UNIT setting in .gmtdefaults4, but this
67              can be overridden on the command line by appending c, i, or m to
68              the  scale/width  value.   When  central  meridian  is optional,
69              default is center of longitude  range  on  -R  option.   Default
70              standard  parallel  is  the equator.  For map height, max dimen‐
71              sion, or min dimension, append h, +, or - to the width,  respec‐
72              tively.
73              More details can be found in the psbasemap man pages.
74
75              CYLINDRICAL PROJECTIONS:
76
77              -Jclon0/lat0/scale (Cassini)
78              -Jcyl_stere/[lon0/[lat0/]]scale (Cylindrical Stereographic)
79              -Jj[lon0/]scale (Miller)
80              -Jm[lon0/[lat0/]]scale (Mercator)
81              -Jmlon0/lat0/scale (Mercator - Give meridian and standard paral‐
82              lel)
83              -Jo[a]lon0/lat0/azimuth/scale  (Oblique  Mercator  -  point  and
84              azimuth)
85              -Jo[b]lon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
86              -Joclon0/lat0/lonp/latp/scale  (Oblique  Mercator  -  point  and
87              pole)
88              -Jq[lon0/[lat0/]]scale (Cylindrical Equidistant)
89              -Jtlon0/[lat0/]scale (TM - Transverse Mercator)
90              -Juzone/scale (UTM - Universal Transverse Mercator)
91              -Jy[lon0/[lat0/]]scale (Cylindrical Equal-Area)
92
93              CONIC PROJECTIONS:
94
95              -Jblon0/lat0/lat1/lat2/scale (Albers)
96              -Jdlon0/lat0/lat1/lat2/scale (Conic Equidistant)
97              -Jllon0/lat0/lat1/lat2/scale (Lambert Conic Conformal)
98
99              AZIMUTHAL PROJECTIONS:
100
101              -Jalon0/lat0[/horizon]/scale (Lambert Azimuthal Equal-Area)
102              -Jelon0/lat0[/horizon]/scale (Azimuthal Equidistant)
103              -Jflon0/lat0[/horizon]/scale (Gnomonic)
104              -Jglon0/lat0[/horizon]/scale (Orthographic)
105              -Jglon0/lat0/altitude/azimuth/tilt/twist/Width/Height/scale
106              (General Perspective).
107              -Jslon0/lat0[/horizon][/slat]/scale (General Stereographic)
108
109              MISCELLANEOUS PROJECTIONS:
110
111              -Jh[lon0/]scale (Hammer)
112              -Ji[lon0/]scale (Sinusoidal)
113              -Jkf[lon0/]scale (Eckert IV)
114              -Jk[s][lon0/]scale (Eckert IV)
115              -Jn[lon0/]scale (Robinson)
116              -Jr[lon0/]scale (Winkel Tripel)
117              -Jv[lon0/]scale (Van der Grinten)
118              -Jw[lon0/]scale (Mollweide)
119
120              NON-GEOGRAPHICAL PROJECTIONS:
121
122              -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
123              -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]]  (Linear,  log,
124              and power scaling)
125
126       -M     Output triangulation network as multiple line segments separated
127              by  a  record  whose  first character is flag [>].  To plot, use
128              psxy with the -M option (see Examples).
129
130       -R     xmin, xmax, ymin, and ymax specify the Region of interest.   For
131              geographic  regions,  these  limits  correspond  to  west, east,
132              south, and north and you may specify them in decimal degrees  or
133              in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
134              and upper right map coordinates are given  instead  of  w/e/s/n.
135              The  two  shorthands  -Rg and -Rd stand for global domain (0/360
136              and -180/+180 in longitude respectively, with -90/+90  in  lati‐
137              tude).   For  calendar  time coordinates you may either give (a)
138              relative time (relative to the selected TIME_EPOCH  and  in  the
139              selected  TIME_UNIT; append t to -JX|x), or (b) absolute time of
140              the form [date]T[clock] (append T to -JX|x).  At  least  one  of
141              date  and  clock must be present; the T is always required.  The
142              date string must be of  the  form  [-]yyyy[-mm[-dd]]  (Gregorian
143              calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
144              string must be of the form hh:mm:ss[.xxx].  The  use  of  delim‐
145              iters  and their type and positions must be exactly as indicated
146              (however, input, output and plot formats are  customizable;  see
147              gmtdefaults).
148
149       -V     Selects verbose mode, which will send progress reports to stderr
150              [Default runs "silently"].
151
152       -Z     Controls whether binary data file has two or three columns  [2].
153              Ignored if -b is not set.
154
155       -:     Toggles  between  (longitude,latitude)  and (latitude,longitude)
156              input and/or output.  [Default is (longitude,latitude)].  Append
157              i  to  select  input  only or o to select output only.  [Default
158              affects both].
159
160       -bi    Selects binary input.  Append s for single precision [Default is
161              d  (double)].   Uppercase  S  or  D  will  force  byte-swapping.
162              Optionally, append ncol, the number of columns  in  your  binary
163              input  file if it exceeds the columns needed by the program.  Or
164              append c  if  the  input  file  is  netCDF.  Optionally,  append
165              var1/var2/...  to specify the variables to be read.  [Default is
166              2 input columns].
167
168       -bo    Selects binary output.  Append s for single  precision  [Default
169              is  d  (double)].   Uppercase  S  or D will force byte-swapping.
170              Optionally, append ncol, the number of desired columns  in  your
171              binary  output  file.  [Default is same as input].  Node ids are
172              stored as binary 4-byte integer triplets.  -bo is ignored if  -M
173              is selected.
174
175       -f     Special  formatting of input and/or output columns (time or geo‐
176              graphical data).  Specify i or o to  make  this  apply  only  to
177              input  or  output  [Default  applies to both].  Give one or more
178              columns (or column ranges) separated by commas.  Append T (abso‐
179              lute  calendar time), t (relative time in chosen TIME_UNIT since
180              TIME_EPOCH), x (longitude), y (latitude), or f (floating  point)
181              to  each  column or column range item.  Shorthand -f[i|o]g means
182              -f[i|o]0x,1y (geographic coordinates).
183

ASCII FORMAT PRECISION

185       The ASCII output formats of numerical data are controlled by parameters
186       in  your  .gmtdefaults4  file.   Longitude  and  latitude are formatted
187       according to OUTPUT_DEGREE_FORMAT, whereas other values  are  formatted
188       according  to D_FORMAT.  Be aware that the format in effect can lead to
189       loss of precision in the output, which can  lead  to  various  problems
190       downstream.   If  you find the output is not written with enough preci‐
191       sion, consider switching to binary output (-bo if available) or specify
192       more decimals using the D_FORMAT setting.
193

GRID VALUES PRECISION

195       Regardless of the precision of the input data, GMT programs that create
196       gridded files will internally hold the grids in 4-byte  floating  point
197       arrays.  This is done to conserve memory and futhermore most if not all
198       real data can be stored using 4-byte floating point values.  Data  with
199       higher  precision (i.e., double precision values) will lose that preci‐
200       sion once GMT operates on the grid or writes out new grids.   To  limit
201       loss  of precision when processing data you should always consider nor‐
202       malizing the data prior to processing.
203

EXAMPLES

205       To triangulate the points in the file samples.xyz, store  the  triangle
206       information  in  a  binary file, and make a grid for the given area and
207       spacing, use
208
209       triangulate samples.xyz -bo -R0/30/0/30 -I2 -Gsurf.grd > samples.ijk
210
211       To draw the optimal Delauney triangulation network based  on  the  same
212       file using a 15-cm-wide Mercator map, use
213
214       triangulate   samples.xyz   -M   -R-100/-90/30/34   -JM15c  |  psxy  -M
215       -R-100/-90/30/34 -JM15c -W0.5p -B1 > network.ps
216

SEE ALSO

218       GMT(1), pscontour(1)
219

REFERENCES

221       Watson, D. F., 1982, Acord: Automatic contouring of raw data,  Comp.  &
222       Geosci., 8, 97-101.
223       Shewchuk,  J. R., 1996, Triangle: Engineering a 2D Quality Mesh Genera‐
224       tor and Delaunay Triangulator, First Workshop on Applied  Computational
225       Geometry (Philadelphia, PA), 124-133, ACM, May 1996.
226       www.cs.cmu.edu/~quake/triangle.html
227
228
229
230GMT 4.3.1                         15 May 2008                   TRIANGULATE(1)
Impressum