NAME

     splitxyz - filter to divide (x,y,z[,distance,heading])  data
     into (x,y,z) track segments.


SYNOPSIS

     splitxyz    [    xyz[dh]file     ]     -Ccourse_change     [
     -Aazimuth/tolerance    ]    [    -Dminimum_distance    ]   [
     -Fxy_filter/z_filter ] [ -Ggap_distance ] [ -H[nrec] ] [  -M
     ] [ -Nnamestem ] [ -S ] [ -V ] [ -Z ] [ -: ] [ -bi[s][n] ] [
     -bo[s] ]


DESCRIPTION

     splitxyz reads a series of (x,y[,z]) records [or  optionally
     (x,y,z,d,h);   see   -S  option]  from  standard  input  [or
     xyz[dh]file]  and  splits  this  into  separate   lists   of
     (x,y[,z])  series,  such  that each series has a nearly con-
     stant azimuth through the x,y plane. There  are  options  to
     choose  only  those series which have a certain orientation,
     to set a minimum length for series, and to high- or low-pass
     filter  the  z  values and/or the x,y values.  splitxyz is a
     useful filter between data extraction and pswiggle plotting,
     and  can  also  be used to divide a large x,y,z dataset into
     segments.  The output is always in the ASCII  format;  input
     may be ASCII or binary (see -b).

     xyz[dh]file(s)
          3 (but see -Z) [or 5] column ASCII file [or binary, see
          -b]   holding   (x,y,z[,d,h])   data  values.   To  use
          (x,y,z,d,h) input, sorted so that d is  non-decreasing,
          specify the -S option; default expects (x,y,z) only. If
          no file is specified, splitxyz will read from  standard
          input.

     -C   Terminate a segment  when  a  course  change  exceeding
          course_change degrees of heading is detected.


OPTIONS

     -A   Write out only those  segments  which  are  within  +/-
          tolerance  degrees  of  azimuth  in  heading,  measured
          clockwise from North, [0 - 360].  [Default  writes  all
          acceptable segments, regardless of orientation].

     -D   Do not write a  segment  out  unless  it  is  at  least
          minimum_distance  units  long.  [Default = 100 distance
          units].

     -F   Filter the z values and/or  the  x,y  values,  assuming
          these  are  functions  of  d  coordinate. xy_filter and
          z_filter are filter widths in  distance  units.   If  a
          filter  width  is zero, the filtering is not performed.
          The absolute value of the width is the full width of  a
          cosine-arch low-pass filter.  If the width is positive,
          the data are low-pass filtered; if negative,  the  data
          are  high-pass  filtered  by  subtracting  the low-pass
          value  from  the  observed  value.   If   z_filter   is
          non-zero,  the  entire series of input z values is fil-
          tered before any segmentation is performed, so that the
          only  edge  effects in the filtering will happen at the
          beginning and end of  the  complete  data  stream.   If
          xy_filter  is  non-zero, the data is first divided into
          segments and then the x,y values of  each  segment  are
          filtered  separately.   This may introduce edge effects
          at the ends of each segment, but  prevents  a  low-pass
          x,y  filter from rounding off the corners of track seg-
          ments.  [Default = no filtering].

     -G   Do  not  let  a   segment    have   a   gap   exceeding
          gap_distance;  instead,  split  it  into  two segments.
          [Default = 10 distance units].

     -H   Input file(s) has Header record(s).  Number  of  header
          records  can  be  changed  by editing your .gmtdefaults
          file.  If used, GMT default is 1  header  record.   Not
          used with binary data.

     -M   Use Map units.  Then x,y are in degrees  of  longitude,
          latitude, and distances in kilometers.  [Default:  dis-
          tances are cartesian in same units as x,y].

     -N   Create Named output files, writing each  segment  to  a
          separate   file   in   the   working   directory  named
          namestem.profile#, where # increases consecutively from
          1.  [Default writes entire output to stdout, separating
          segments by sub-headings that start with > marks].

     -S   d and h is supplied.   In  this  case,  input  contains
          x,y,z,d,h.  [Default expects (x,y,z) input, and d,h are
          computed from delta x, delta y, according to -M option]

     -V   Selects verbose mode, which will send progress  reports
          to stderr [Default runs "silently"].

     -Z   Data have x,y only (no z-column).

     -:   Toggles      between      (longitude,latitude)      and
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -bi  Selects binary input.  Append s  for  single  precision
          [Default  is  double].   Append  n  for  the  number of
          columns in the binary file(s).  [Default is 2, 3, or  5
          input columns as set by -S, -Z].

     -bo  Selects binary output.  Append s for  single  precision
          [Default is double].


EXAMPLES

     Suppose you want to make a wiggle plot of magnetic anomalies
     on  segments  oriented approximately east-west from a cruise
     called cag71 in the region -R300/315/12/20. You want to  use
     a  100km  low-pass  filter  to smooth the tracks and a 500km
     high-pass filter to detrend  the  magnetic  anomalies.   Try
     this:

     gmtlist cag71 -R300/315/12/20  -Fxyzdh  |  splitxyz  -A90/15
     -F100/-500  -M  -S  -V  |  pswiggle  -R300/315/12/20  -Jm0.6
     -Ba5f1:.cag71: -T1 -W3 -G200 -Z200 > cag71_wiggles.ps

     MGD-77 users: For this application  we  recommend  that  you
     extract  d, h from gmtlist rather than have splitxyz compute
     them separately.
     Suppose you have been given a binary, double-precision  file
     containing  lat,  lon, gravity values from a survey, and you
     want to split it into profiles named  survey.profile#  (when
     gap exceeds 100 km).  Try this:

     splitxyz survey.bin -Nsurvey -V -G100 -: -M -bi3


SEE ALSO

     gmt(l), gmtlist(l), pswiggle(l)