Provided by: gmt-common_5.4.5+dfsg-1_all bug

NAME

       splitxyz - Split xyz[dh] data tables into individual segments

SYNOPSIS

       splitxyz  [ table ] [  -Aazimuth/tolerance ] [  -Ccourse_change] [  -Dminimum_distance ] [
       -Fxy_filter/z_filter ] [  -Ntemplate ] [  -Qflags ] [  -S ] [  -V[level] ] [ -bbinary ]  [
       -dnodata ] [ -eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -:[i|o] ]

       Note: No space is allowed between the option flag and the associated arguments.

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.

REQUIRED ARGUMENTS

       none.

OPTIONAL ARGUMENTS

       table  One  or  more  ASCII  [or  binary,  see  -bi] files with 2, 3, or 5 columns 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 files
              are specified, splitxyz will read from standard input.

       -Aazimuth/tolerance
              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].

       -Ccourse_change
              Terminate a segment when a course change exceeding course_change degrees of heading
              is detected [ignore course changes].

       -Dminimum_distance
              Do not write a segment out unless it is at least minimum_distance units long [0]

       -Fxy_filter/z_filter
              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].

       -Ntemplate
              Write 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
              running  segment  number  across  all tables); this is usually %d but could be %08d
              which  gives  leading  zeros,  etc.  [Default   is   splitxyz_segment_%d.{txt|bin},
              depending  on -bo]. Alternatively, give a template with two C format specifiers and
              we will supply the table number and the segment number within the  table  to  build
              the file name.

       -Qflags
              Specify  your  desired  output using any combination of xyzdh, in any order. Do not
              space between the letters. Use lower case. The output will be ASCII (or binary, see
              -bo) columns of values corresponding to xyzdh [Default is -Qxyzdh (-Qxydh if only 2
              input columns)].

       -S     Both d and h are 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. Use -fg to
              indicate map data; then x,y are assumed to be in degrees  of  longitude,  latitude,
              distances  are  considered  to  be in kilometers, and angles are actually azimuths.
              Otherwise,  distances  are  Cartesian  in  same  units  as  x,y  and   angles   are
              counter-clockwise from horizontal].

       -V[level] (more ...)
              Select verbosity level [c].

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2, 3, or 5 input columns as set by -S].

       -bo[ncols][type] (more ...)
              Select native binary output. [Default is 1-5 output columns as set by -Q].

       -d[i|o]nodata (more ...)
              Replace input columns that equal nodata with NaN and do the reverse on output.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

       -f[i|o]colinfo (more ...)
              Specify data types of input and/or output columns.

       -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
              Determine data gaps and line breaks. Do not let a segment have a gap exceeding gap;
              instead, split it into two segments. [Default ignores gaps].

       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
              Skip or produce header record(s).

       -icols[+l][+sscale][+ooffset][,...] (more ...)
              Select input columns and transformations (0 is first column).

       -:[i|o] (more ...)
              Swap 1st and 2nd column on input and/or output.

       -^ or just -
              Print a short message about the syntax of the command, then exits (NOTE: on Windows
              just use -).

       -+ or just +
              Print  an  extensive  usage  (help)  message,  including  the  explanation  of  any
              module-specific option (but not the GMT common options), then exits.

       -? or no arguments
              Print a complete usage (help) message, including the explanation  of  all  options,
              then exits.

ASCII FORMAT PRECISION

       The  ASCII  output formats of numerical data are controlled by parameters in your gmt.conf
       file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, absolute  time  is
       under  the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point
       values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can
       lead  to loss of precision in ASCII 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 FORMAT_FLOAT_OUT setting.

DISTANCE CALCULATIONS

       The  type  of  input  data  is  dictated by the -f option. If -fg is given then x,y are in
       degrees of longitude, latitude, distances are in  kilometers,  and  angles  are  azimuths.
       Otherwise,  distances  are Cartesian in same units as x,y and angles are counter-clockwise
       from horizontal.

EXAMPLES

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

              gmt mgd77list JA020015 -R300/315/12/20 -Flon,lat,mag,dist,azim | gmt splitxyz -A90/15 -F100/-500 \
                  -D100 -S -V -fg | gmt pswiggle -R300/315/12/20 -Jm0.6i -Baf -B+tJA020015 -T1 \
                  -W0.75p -Ggray -Z200 > JA020015_wiggles.ps

       MGD-77  users: For this application we recommend that you extract dist,azim from mgd77list
       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_###.txt (when
       gap exceeds 100 km). Try this:

              gmt splitxyz survey.bin -Nsurvey_%03d.txt -V -gd100k -D100 -: -fg -bi3d

SEE ALSO

       gmt, filter1d, mgd77list, pswiggle

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe