.\" Man page generated from reStructuredText.
.
.TH "SPLITXYZ" "1gmt" "Jan 10, 2019" "5.4.5" "GMT"
.SH NAME
splitxyz \- Split xyz[dh] data tables into individual segments
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fBsplitxyz\fP [ \fItable\fP ]
[  \fB\-A\fP\fIazimuth\fP/\fItolerance\fP ]
[  \fB\-C\fP\fIcourse_change\fP]
[  \fB\-D\fP\fIminimum_distance\fP ]
[  \fB\-F\fP\fIxy_filter\fP/\fIz_filter\fP ]
[  \fB\-N\fP\fItemplate\fP ]
[  \fB\-Q\fP\fIflags\fP ]
[  \fB\-S\fP ]
[  \fB\-V\fP[\fIlevel\fP] ]
[ \fB\-b\fPbinary ]
[ \fB\-d\fPnodata ]
[ \fB\-e\fPregexp ]
[ \fB\-f\fPflags ]
[ \fB\-g\fPgaps ]
[ \fB\-h\fPheaders ]
[ \fB\-i\fPflags ]
[ \fB\-:\fP[\fBi\fP|\fBo\fP] ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
\fBsplitxyz\fP reads a series of (x,y[,z]) records [or optionally
(x,y,z,d,h); see \fB\-S\fP option] from standard input [or \fIxyz[dh]file\fP]
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. \fBsplitxyz\fP 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.
.SH REQUIRED ARGUMENTS
.sp
none.
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fItable\fP
One or more ASCII [or binary, see \fB\-bi\fP]
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 \fB\-S\fP option; default expects (x,y,z)
only. If no files are specified, \fBsplitxyz\fP will read from
standard input.
.UNINDENT
.INDENT 0.0
.TP
\fB\-A\fP\fIazimuth\fP/\fItolerance\fP
Write out only those segments which are within +/\- \fItolerance\fP
degrees of \fIazimuth\fP in heading, measured clockwise from North, [0 \-
360]. [Default writes all acceptable segments, regardless of
orientation].
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP\fIcourse_change\fP
Terminate a segment when a course change exceeding \fIcourse_change\fP
degrees of heading is detected [ignore course changes].
.UNINDENT
.INDENT 0.0
.TP
\fB\-D\fP\fIminimum_distance\fP
Do not write a segment out unless it is at least \fIminimum_distance\fP
units long [0]
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP\fIxy_filter\fP/\fIz_filter\fP
Filter the z values and/or the x,y values, assuming these are
functions of d coordinate. \fIxy_filter\fP and \fIz_filter\fP 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
\fIz_filter\fP 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 \fIxy_filter\fP 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].
.UNINDENT
.INDENT 0.0
.TP
\fB\-N\fP\fItemplate\fP
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 \fBmust\fP 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
\fB\-bo\fP]. 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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-Q\fP\fIflags\fP
Specify your desired output using any combination of \fIxyzdh\fP, in any
order. Do not space between the letters. Use lower case. The output
will be ASCII (or binary, see \fB\-bo\fP)
columns of values corresponding to \fIxyzdh\fP [Default is
\fB\-Q\fP\fIxyzdh\fP (\fB\-Q\fP\fIxydh\fP if only 2 input columns)].
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP
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 \fB\-fg\fP 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].
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-bi\fP[\fIncols\fP][\fBt\fP] (more ...)
Select native binary input. [Default is 2, 3, or 5 input columns as set by \fB\-S\fP].
.UNINDENT
.INDENT 0.0
.TP
\fB\-bo\fP[\fIncols\fP][\fItype\fP] (more ...)
Select native binary output. [Default is 1\-5 output columns as set by \fB\-Q\fP].
.UNINDENT
.INDENT 0.0
.TP
\fB\-d\fP[\fBi\fP|\fBo\fP]\fInodata\fP (more ...)
Replace input columns that equal \fInodata\fP with NaN and do the reverse on output.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-e\fP[\fB~\fP]\fI"pattern"\fP \fB|\fP \fB\-e\fP[\fB~\fP]/\fIregexp\fP/[\fBi\fP] (more ...)
Only accept data records that match the given pattern.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-f\fP[\fBi\fP|\fBo\fP]\fIcolinfo\fP (more ...)
Specify data types of input and/or output columns.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-g\fP[\fBa\fP]\fBx\fP|\fBy\fP|\fBd\fP|\fBX\fP|\fBY\fP|\fBD\fP|[\fIcol\fP]\fBz\fP[+|\-]\fIgap\fP[\fBu\fP] (more ...)
Determine data gaps and line breaks. Do not let a segment have a gap exceeding \fIgap\fP; instead, split it into two segments. [Default ignores gaps].
.UNINDENT
.INDENT 0.0
.TP
\fB\-h\fP[\fBi\fP|\fBo\fP][\fIn\fP][\fB+c\fP][\fB+d\fP][\fB+r\fP\fIremark\fP][\fB+r\fP\fItitle\fP] (more ...)
Skip or produce header record(s).  
.UNINDENT
.INDENT 0.0
.TP
\fB\-i\fP\fIcols\fP[\fB+l\fP][\fB+s\fP\fIscale\fP][\fB+o\fP\fIoffset\fP][,\fI\&...\fP] (more ...)
Select input columns and transformations (0 is first column).
.UNINDENT
.INDENT 0.0
.TP
\fB\-:\fP[\fBi\fP|\fBo\fP] (more ...)
Swap 1st and 2nd column on input and/or output.
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.UNINDENT
.SH ASCII FORMAT PRECISION
.sp
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 (\fB\-bo\fP if available) or
specify more decimals using the FORMAT_FLOAT_OUT setting.
.SH DISTANCE CALCULATIONS
.sp
The type of input data is dictated by the \fB\-f\fP option. If \fB\-fg\fP 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.
.SH EXAMPLES
.sp
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 \fB\-R\fP300/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:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt mgd77list JA020015 \-R300/315/12/20 \-Flon,lat,mag,dist,azim | gmt splitxyz \-A90/15 \-F100/\-500 \e
    \-D100 \-S \-V \-fg | gmt pswiggle \-R300/315/12/20 \-Jm0.6i \-Baf \-B+tJA020015 \-T1 \e
    \-W0.75p \-Ggray \-Z200 > JA020015_wiggles.ps
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
MGD\-77 users: For this application we recommend that you extract dist,azim
from mgd77list rather than have
\fBsplitxyz\fP compute them separately.
.sp
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 \fIsurvey\fP_\fI###.txt\fP (when gap exceeds 100 km). Try this:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt splitxyz survey.bin \-Nsurvey_%03d.txt \-V \-gd100k \-D100 \-: \-fg \-bi3d
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
gmt,
filter1d,
mgd77list,
pswiggle
.SH COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
.\" Generated by docutils manpage writer.
.