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

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 constant 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 filtered 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 segments.
              [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: distances 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)].  Applies to geographic coordinates only.

       -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(1gmt), gmtlist(1gmt), pswiggle(1gmt)

                                                   1 Jan 2004                                        SPLITXYZ(l)