NAME

       gmtstitch - Join line segments whose end points match within tolerance

SYNOPSIS

       gmtstitch  [  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] ]

DESCRIPTION

       gmtstitch  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 segments are joined into a  single  segment.   The  process  repeats  until  all  the
       remaining  endpoints  no  longer  pass the tolerance test; the resulting 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 standard 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  output  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 ELLIPSOID 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  geographical  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
              (absolute 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 precision,
       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 coordinates 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 possible, 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 ALSO

       GMT(1), mapproject(1)