x2sys_cross - Calculate crossovers between track data files
x2sys_cross track(s) -TTAG [
-Acombi.lis ] [ -C[runtimes] ] [
-Il|a|c ] [ -Jparameters ] [
-Qe|i ] [
-Sl|u|hspeed ] [ -V[level]
] [ -Wsize ] [ -Z ] [ -bobinary ] [
-donodata ]
Note: No space is allowed between the option flag and the
associated arguments.
x2sys_cross is used to determine all intersections between
("external cross-overs") or within ("internal
cross-overs") tracks (Cartesian or geographic), and report the time,
position, distance along track, heading and speed along each track segment,
and the crossover error (COE) and mean values for all observables. The names
of the tracks are passed on the command line. By default, x2sys_cross
will look for both external and internal COEs. As an option, you may choose
to project all data using one of the map-projections prior to calculating
the COE.
- tracks
- Can be one or more ASCII, native binary, or COARDS netCDF 1-D data files.
To supply the data files via a text file with a list of tracks (one per
record), specify the name of the track list after a leading equal-sign
(e.g., =tracks.lis). If the names are missing their file extension we will
append the suffix specified for this TAG. Track files will be
searched for first in the current directory and second in all directories
listed in $X2SYS_HOME/TAG/TAG_paths.txt (if it
exists). [If $X2SYS_HOME is not set it will default to
$GMT_SHAREDIR/x2sys]. (Note: MGD77 files will also be looked for
via MGD77_HOME/mgd77_paths.txt and *.gmt files will be searched for
via $GMT_SHAREDIR/mgg/gmtfile_paths).
- -TTAG
- Specify the x2sys TAG which tracks the attributes of this data
type.
- -Acombi.lis
- Only process the pair-combinations found in the file combi.lis
[Default process all possible combinations among the specified files]. The
file combi.lis created by x2sys_get -L option
- -C[runtimes]
- Compute and append the processing run-time for each pair to the progress
message. Append a filename to save these run-times to file. The idea here
is to use the knowledge of run-times to split the main process in a number
of sub-processes that can each be launched in a different processor of
your multi-core machine. See the MATLAB function split_file4coes.m
that lives in the x2sys supplement source code.
- -Il|a|c
- Sets the interpolation mode for estimating values at the crossover. Choose
among:
l Linear interpolation [Default].
a Akima spline interpolation.
c Cubic spline interpolation.
- -Qe|i
- Append e for external COEs only, and i for internal COEs
only [Default is all COEs].
- -Rwest/east/south/north[/zmin/zmax][+r][+uunit]
- west, east, south, and north specify the
region of interest, and you may specify them in decimal degrees or in
[±]dd:mm[:ss.xxx][W|E|S|N] format
Append +r if lower left and upper right map coordinates are given
instead of w/e/s/n. The two shorthands -Rg and -Rd stand for
global domain (0/360 and -180/+180 in longitude respectively, with -90/+90
in latitude). Alternatively for grid creation, give
Rcodelon/lat/nx/ny, where
code is a 2-character combination of L, C, R (for left, center, or
right) and T, M, B for top, middle, or bottom. e.g., BL for lower left.
This indicates which point on a rectangular region the
lon/lat coordinate refers to, and the grid dimensions
nx and ny with grid spacings via -I is used to create
the corresponding region. Alternatively, specify the name of an existing
grid file and the -R settings (and grid spacing, if applicable) are
copied from the grid. Appending +uunit expects projected
(Cartesian) coordinates compatible with chosen -J and we inversely
project to determine actual rectangular geographic region. For perspective
view (-p), optionally append /zmin/zmax. In case of
perspective view (-p), a z-range (zmin, zmax) can be
appended to indicate the third dimension. This needs to be done only when
using the -Jz option, not when using only the -p option. In
the latter case a perspective view of the plane is plotted, with no third
dimension. For Cartesian data just give xmin/xmax/ymin/ymax. This
option limits the COEs to those that fall inside the specified
domain.
- -Sl|u|hspeed
- Defines window of track speeds. If speeds are outside this window we do
not calculate a COE. Specify
-Sl sets lower speed [Default is 0].
-Su sets upper speed [Default is Infinity].
-Sh does not limit the speed but sets a lower speed
below which headings will not be computed (i.e., set to NaN) [Default
calculates headings regardless of speed].
- -Wsize
- Give the maximum number of data points on either side of the crossover to
use in the spline interpolation [3].
- -Z
- Report the values of each track at the crossover [Default reports the
crossover value and the mean value].
- -^ 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.
The COEs found are printed out to standard output in ASCII format
(unless -bo is set). When ASCII is chosen, the output format depends
on whether or not old-style XOVER output (-L) has been selected [See
the x_over man page for more details]. If ASCII, then the first
record contains the name of the tag used, the second records specifies the
exact command line used for this run, and the third record contains the
names of each column. For each track pair, there will be a segment header
record containing the two file names and their start/stop/dist information
(start/stop is absolute time or NaN if unavailable while dist is the total
track length), whereas subsequent records have the data for each COE
encountered. The fields written out are x, y, time along track #1 and #2,
distance along track #1 and #2, heading along track #1 and #2, velocity
along track #1 and #2, and then pairs of columns for each selected
observable. These are either pairs of (COE, average value) for each data
type (or track-values #1 and #2; see -Z). It is recommended that the
Akima spline is used instead of the natural cubic spline, since it is less
sensitive to outliers that tend to introduce wild oscillations in the
interpolation.
If track_a and track_b are passed on the command line, then the
COE value is Value (track_a) - Value (track_b).
The output format of individual columns are controlled by
FORMAT_FLOAT_OUT except for geographic coordinates (FORMAT_GEO_OUT) and
absolute calendar time (FORMAT_DATE_OUT, FORMAT_CLOCK_OUT). Make sure these
are setto give you enough significant digits to achieve the desired
precision.
To compute all internal crossovers in the gmt-formatted file
c2104.gmt, and using the tag GMT, try
gmt x2sys_cross c2104.gmt -TGMT > c2104.d
To find the crossover locations with bathymetry between the two
MGD77 files A13232.mgd77 and A99938.mgd77, using the MGD77 tag, try
gmt x2sys_cross A13232.mgd77 A99938.mgd77 -Qe -TMGD77 > crossovers.d
Wessel, P. (2010), Tools for analyzing intersecting tracks: the
x2sys package. Computers and Geosciences, 36, 348-354.
Wessel, P. (1989), XOVER: A cross-over error detector for track
data, Computers and Geosciences, 15(3), 333-346.
gmt, x2sys_binlist, x2sys_init, x2sys_datalist, x2sys_get,
x2sys_list, x2sys_put, x2sys_report, x2sys_solve, x_over
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F.
Wobbe