GMTSTITCH(1) Generic Mapping Tools GMTSTITCH(1)NAMEgmtstitch - Join line segments whose end points match within tolerance
SYNOPSISgmtstitch [ infiles ] [ -C[closed] ] [ -D[template] ] [ -H[i][nrec] ] [
-L[linkfile] ] [ -Q[template] ] [ -Tcutoff[m|c|e|E|k|K][/nn_dist] ] [
-V ] [ -:[i|o] ] [ -b[i|o][s|S|d|D[ncol]|c[var1/...]] ] [
-bo[s|S|d|D[ncol]|c[var1/...]] ] [ -m[i|o][flag] ]
DESCRIPTIONgmtstitch reads one or more data files (which may be multisegment
files; see -m) and examines the coordinates of the end points of all
line segments. If a pair of end points are identical or closer to each
other than the specified separation tolerance then the two line seg‐
ments are joined into a single segment. The process repeats until all
the remaining endpoints no longer pass the tolerance test; the result‐
ing segments are then written out to standard output. It it is not
clear what the separation tolerance should be then use -L to get a list
of all separation distances and analyze them to determine a suitable
cutoff.
file(s)
One of more data files. If none are supplied then we read stan‐
dard input.
OPTIONS-C Write all the closed polygons to closed [gmtstitch_closed.d] and
all other segments as they are to stdout. No stitching takes
place. Use -Tcutoff to set a minimum separation [0], and if
cutoff is > 0 then we also close the polygons on output.
-D For multiple segment data, dump each segment to a separate out‐
put file [Default writes a multiple segment file to stdout].
Append a format template for the individual file names; this
template must contain a C format specifier that can format an
integer argument (the segment number); this is usually %d but
could be %8.8d which gives leading zeros, etc. Optionally, it
may also contain the format %c before the integer; this will
then be replaced by C (closed) or O (open) to indicate segment
type. [Default is gmtstitch_segment_%d.d]. Note that segment
headers will be written in either case. For composite segments,
a generic segment header will be written and the segment headers
of individual pieces will be written out as comments to make it
possible to identify where the stitched pieces came from.
-H Input file(s) has header record(s). If used, the default number
of header records is N_HEADER_RECS. Use -Hi if only input data
should have header records [Default will write out header
records if the input data have them]. Blank lines and lines
starting with # are always skipped.
-L Writes the link information to the specified file [links.d]. For
each segment we write the original segment id, and for the
beginning and end point of the segment we report the id of the
closest segment, whether it is the beginning (B) or end (E)
point that is closest, and the distance between those points in
units determined by -T.
-Q Used with -D to a list file with the names of the individual
output files. Optionally, append a filename template for the
individual file names; this template may contain a C format
specifier that can format an character (C or O for closed or
open, respectively). [Default is gmtstitch_list.d].
-T Specifies the separation tolerance in the data coordinate units
[0]. Append m or c for minutes or seconds, or e or k for meters
or km (implies -fg using use flat Earth approximation. Use E or
K for exact geodesic distances; however. if the current ELLIP‐
SOID is Sphere then spherical great circle distances are used.
If two lines has endpoints that are closer than this cutoff they
will be joined. Optionally, append /nn_dist which adds the
requirement that a link will only be made if the second closest
connection exceeds the nn_dist. The latter distance is assumed
to be in the same units as cutoff.
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-: Toggles between (longitude,latitude) and (latitude,longitude)
input and/or output. [Default is (longitude,latitude)]. Append
i to select input only or o to select output only. [Default
affects both].
-bi Selects binary input. Append s for single precision [Default is
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
2 input columns].
-bo Selects binary output. Append s for single precision [Default
is d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of desired columns in your
binary output file. [Default is same as input].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
-m Multiple segment file(s). Segments are separated by a special
record. For ASCII files the first character must be flag
[Default is '>']. For binary files all fields must be NaN and
-b must set the number of output columns explicitly. By default
the -m setting applies to both input and output. Use -mi and
-mo to give separate settings to input and output.
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters
in your .gmtdefaults4 file. Longitude and latitude are formatted
according to OUTPUT_DEGREE_FORMAT, whereas other values are formatted
according to D_FORMAT. 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 preci‐
sion, consider switching to binary output (-bo if available) or specify
more decimals using the D_FORMAT setting.
EXAMPLES
To combine the digitized multisegment lines segment_*.d (whose coordi‐
nates are in cm) into as few complete lines as possible, assuming the
end points slop could be up to 0.1 mm, run
gmtstitch segment_*.d -Tf 0.1 -m > new_segments.d
To combine the digitized segments in the multisegment file my_lines.d
(whose coordinates are in lon,lat) into as few complete lines as possi‐
ble, assuming the end points slop could be up to 150 m, and write the
complete segments to separate files called Map_segment_0001.dat,
Map_segment_0002.dat, etc., run
gmtstitch my_lines.d -Tf 0.15k -m -D Map_segment_%4.4d.dat
BUGS
The line connection does not work if a line only has a single point.
However, gmtstitch will correctly add the point to the nearest segment.
Running gmtstitch again on the new set of lines will eventually connect
all close lines.
SEE ALSOGMT(1), mapproject(1)GMT 4.5.14 1 Nov 2015 GMTSTITCH(1)
