sphtriangulate
Delaunay or Voronoi construction of spherical data
Synopsis
gmt sphtriangulate [ table ] [ -A ] [ -C ] [ -D ] [ -Lunit ] [ -Nfile ] [ -Qd|v ] [ -T ] [ -V[level] ] [ -bbinary ] [ -dnodata[+ccol] ] [ -eregexp ] [ -hheaders ] [ -iflags ] [ -jflags ] [ -qiflags ] [ -rreg ] [ -sflags ] [ -:[i|o] ] [ --PAR=value ]
Note: No space is allowed between the option flag and the associated arguments.
Description
sphtriangulate reads one or more ASCII [or binary] files (or standard input) containing (lon, lat) and performs a spherical Delaunay triangulation, i.e., it determines how the points should be connected to give the most equilateral triangulation possible on the sphere. Optionally, you may choose -Qv which will do further processing to obtain the Voronoi polygons. Normally, either set of polygons will be written as closed fillable segment output; use -T to write unique arcs instead. As an option, compute the area of each triangle or polygon. The algorithm used is STRIPACK [Renka, 1997].
Required 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.
Optional Arguments
- -A
Compute the area of the spherical triangles (-Qd) or polygons (-Qv) and write the areas (in chosen units; see -L) in the output segment headers [no areas calculated].
- -C
For large data set you can save some memory (at the expense of more processing) by only storing one form of location coordinates (geographic or Cartesian 3-D vectors) at any given time, translating from one form to the other when necessary [Default keeps both arrays in memory].
- -D
Used to skip the last (repeated) input vertex at the end of a closed segment if it equals the first point in the segment. [Default uses all points].
- -Lunit
Specify the unit used for distance and area calculations. Choose among e (m), f (foot), k (km), M (mile), n (nautical mile), u (survey foot), or d (spherical degree). A spherical approximation is used unless -je is set, in which case we convert latitudes to authalic latitudes before calculating areas. When degree is selected the areas are given in steradians.
- -Nfile
Write the information pertaining to each polygon. For Delaunay: the three node number and the triangle area (if -A was set); for Voronoi the unique node (lon, lat) and polygon area (if -A was set)) to a separate file. This information is also encoded in the segment headers of ASCII output files. Required if binary output is needed.
- -Qd|v
Append one of two directives to set the output type:
d: Create Delaunay triangles [Default].
v: Create Voronoi polygons.
Note: If -bo is active then -N may be used to specify a separate file where the polygon information normally is written.
- -T
Write the unique arcs of the construction [Default writes fillable triangles or polygons]. When used with -A we store arc length in the segment header in chosen unit (see -L).
- -V[level]
Select verbosity level [w]. (See full description) (See technical reference).
- -birecord[+b|l] (more …)
Select native binary format for primary table input. [Default is 2 input columns].
- -borecord[+b|l] (more …)
Select native binary format for table output. [Default is same as input].
- -d[i|o][+ccol]nodata (more …)
Replace input columns that equal nodata with NaN and do the reverse on output.
- -e[~]“pattern” | -e[~]/regexp/[i] (more …)
Only accept data records that match the given pattern.
- -h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle] (more …)
Skip or produce header record(s).
- -je|f|g (more …)
Determine how spherical distances or coordinate transformations are calculated.
- -qi[~]rows|limits[+ccol][+a|t|s] (more …)
Select input rows or data limit(s) [default is all rows].
- -s[cols][+a][+r] (more …)
Set handling of NaN records for output.
- -:[i|o] (more …)
Swap 1st and 2nd column on input and/or output.
- -r[g|p] (more …)
Set node registration [gridline].
- -^ or just -
Print a short message about the syntax of the command, then exit (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 exit.
- -? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exit.
- --PAR=value
Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.
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, absolute time is under the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in ASCII 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.
Examples
Note: Below are some examples of valid syntax for this module.
The examples that use remote files (file names starting with @)
can be cut and pasted into your terminal for testing.
Other commands requiring input files are just dummy examples of the types
of uses that are common but cannot be run verbatim as written.
Note: Since many GMT plot examples are very short (i.e., one module call between the gmt begin and gmt end commands), we will often present them using the quick modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.
To create a spherical triangulation from the remote data set hotspots.txt and then plot it on a sphere, try:
gmt sphtriangulate @hotspots.txt -Qd -T | gmt plot -Rg -JG-120/-30/7i -Bafg -W3p -pdf map
To triangulate the points in the file testdata.txt, and make a Voronoi diagram via plot, use
gmt sphtriangulate testdata.txt -Qv | gmt plot -Rg -JG30/30/6i -L -W1p -Bag -pdf testdata
To compute the optimal Delaunay triangulation network based on the multiple segment file globalnodes.txt and save the area of each triangle in the header record, try
gmt sphtriangulate globalnodes.txt -Qd -A > global_tri.txt
Notes
The STRIPACK algorithm and implementation expect that there are no duplicate points in the input. It is best that the user ensures that this is the case. GMT has tools, such as blockmean and others, to combine close points into single entries. Also, sphtriangulate has a -D option to determine and exclude duplicates, but it is a very brute-force yet exact comparison that is very slow for large data sets. Detection of duplicates in the STRIPACK library will exit the module.
See Also
References
Renka, R, J., 1997, Algorithm 772: STRIPACK: Delaunay Triangulation and Voronoi Diagram on the Surface of a Sphere, AMC Trans. Math. Software, 23(3), 416-434.