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)