X2SYS_CROSS(1)

NAME
x2sys_cross - Find and compute Cross-Over Errors

SYNOPSIS
x2sys_cross track(s) -TTAG [ -Cc|f|g|e ] [ -Fflags ] [ -Il|a|c ] [ -Jparameters ] [ -Kcombi.lis] [ -O ] [ -Nd|sunit ] [ -Qe|i ] [ -Sl|uspeed ] [ -V ][ -Wt|d|nsize ] [ -2 ] [ -bo[s|S|d|D][ncol] ]

DESCRIPTION
x2sys_cross is used to determine all intersections between ("external cross-overs") or within ("internal cross-overs") tracks, and report the time, position, distance along track, heading and speed along each tracksegment, and the crossover 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 cross-overs. As an option, you may choose to project all data using one of the map-projections prior to calculating the crossovers.

tracks
    Can be one or more binary or ASCII data files. To give a list of names, use `cat tracks.lis`. If the names are missing the suffix we will append the suffix that goes with this TAG. Track files will be looked for first in the current directory and second in all directories listed in $X2SYS_HOME/TAG_paths.txt (if it exists). [If $X2SYS_HOME is not set it will default to $GMTHOME/share/x2sys].

-T  Sets the data set TAG which, among other things, sets the definition file.

OPTIONS
No space between the option flag and the associated arguments.

-C  Select procedure for along-track distance calculation:
    c Cartesian distances [Default].
    f Flat Earth distances.
    g Great circle distances.
    e Geodesic distances on current GMT ellipsoid.

-F  Sets which columns to use. Give a comma-separated list of column names; this list must include x, y or lon, lat and ideally time [Default selects all columns].

-I  Sets the interpolation mode. Choose among:
    l Linear interpolation [Default].
    a Akima spline interpolation.
    c Cubic spline interpolation.

-J  Selects the map projection. Scale is UNIT/degree, 1:xxxxx, or width in UNIT (upper case modifier). UNIT is cm, inch, or m, depending on the MEASURE_UNIT setting in .gmtdefaults4, but this can be overridden on the command line by appending c, i, or m to the scale/width value. For map height, max dimension, or min dimension, append h, +, or - to the width, respectively.
    More details can be found in the psbasemap man pages.

    CYLINDRICAL PROJECTIONS:

    -Jclon0/lat0/scale (Cassini)
    -Jjlon0/scale (Miller)
    -Jmscale (Mercator - Greenwich and Equator as origin)
    -Jmlon0/lat0/scale (Mercator - Give meridian and standard parallel)
    -Joalon0/lat0/azimuth/scale (Oblique Mercator - point and azimuth)
    -Joblon0/lat0/lon1/lat1/scale (Oblique Mercator - two points)
    -Joclon0/lat0/lonp/latp/scale (Oblique Mercator - point and pole)
    -Jqlon0/scale (Equidistant Cylindrical Projection (Plate Carree))
    -Jtlon0/scale (TM - Transverse Mercator, with Equator as y = 0)
    -Jtlon0/lat0/scale (TM - Transverse Mercator, set origin)
    -Juzone/scale (UTM - Universal Transverse Mercator)
    -Jylon0/lats/scale (Basic Cylindrical Projection)

    AZIMUTHAL PROJECTIONS:

    -Jalon0/lat0/scale (Lambert)
    -Jelon0/lat0/scale (Equidistant)
    -Jflon0/lat0/horizon/scale (Gnomonic)
    -Jglon0/lat0/scale (Orthographic)
    -Jslon0/lat0/[slat/]scale (General Stereographic)

    CONIC PROJECTIONS:

    -Jblon0/lat0/lat1/lat2/scale (Albers)
    -Jdlon0/lat0/lat1/lat2/scale (Equidistant)
    -Jllon0/lat0/lat1/lat2/scale (Lambert)

    MISCELLANEOUS PROJECTIONS:

    -Jhlon0/scale (Hammer)
    -Jilon0/scale (Sinusoidal)
    -Jk[f|s]lon0/scale (Eckert IV (f) and VI (s))
    -Jnlon0/scale (Robinson)
    -Jrlon0/scale (Winkel Tripel)
    -Jvlon0/scale (Van der Grinten)
    -Jwlon0/scale (Mollweide)

    NON-GEOGRAPHICAL PROJECTIONS:

    -Jp[a]scale[/origin][r|z] (Polar coordinates (theta,r))
    -Jxx-scale[d|l|ppow|t|T][/y-scale[d|l|ppow|t|T]] (Linear, log, and power scaling)

-K  Only process the pair-combinations found in the file combi.lis [Default process all possible combinations among the specified files].

-L  Output results using the old XOVER format [Default is X2SYS format]. This option should only be used with *.gmt-formatted MGD77 files.

-N  Append d for distance or s for speed, then give the desired unit as e (meter or m/s), k (km or km/hr), m (miles or miles/hr), or n (nautical miles or knots). [Default is -Ndk -Nse (km and m/s)].

-Q  Append e for external crossovers only, and i for internal crossovers only [Default is all crossovers].

-R  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 wesn. The two shorthands -Rg -Rd stand for global domain (0/360 or -180/+180 in longitude respectively, with -90/+90 in latitude).

-S  Defines window of track speeds. If speeds are outside this window we do not calculate a crossover. Specify
        -Sl sets lower speed [Default is 0].
        -Su sets upper speed [Default is Infinity].

-V  Selects verbose mode, which will send progress reports to stderr [Default runs "silently"].

-W  Give t, d, or n and append the corresponding maximum time gap [Infinity], or distance gap [Infinity] (both in user units) allowed between the two points immediately on either side of a crossover. If the gap exceeds this maximum gap we skip the crossover calculation. For -Wn, give the maximum number of points on either side to use in the interpolation [3].

-2  Report the values of each track at the crossover [Default reports the crossover value and the mean value].

-bo Selects binary output. Append s for single precision [Default is d (double)]. Uppercase S (or D) will force byte-swapping. Optionally, append ncol, the number of desired columns in your binary output file.

REMARKS
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. If so, then the first record contains the file names and their start year, whereas subsequent records have the data for each COE encountered. The fields written out are lat, lon, time along track #1 and #2, x_gravity, x_magnetics, x_bathymetry, average gravity, average magnetics, average bathymetry, heading along track #1 and #2. If the default format is chosen then the header record starts with "> ", and the output format for crossovers are first 10 columns that contain 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 (COE, average value) for each data type (or track-values; see -2). 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.

SIGN CONVENTION
If lega and legb are passed on the command line, then the COE value is Value (lega) - Value (legb).

EXAMPLES
To compute all internal crossovers in the gmt-formatted file c2104.gmt, and output in the old XOVER format, using the tag MGG, try

x2sys_cross c2104.gmt -L -TMGG > c2104.d

To find the crossover locations with bathymetry between the two MGD77 files A13232.mgd77 and A99938.mgd77, using the MGD77 tag, try

x2sys_cross A13232.mgd77 A99938.mgd77 -Qe -TNGD77 -Flon,lat,depth > crossovers.d

SEE ALSO
GMT(1), x2sys_init(1) x2sys_datalist(1) x2sys_get(1) x2sys_put(1)