# gmtvector

Operations on Cartesian vectors in 2-D and 3-D

## Synopsis

**gmt vector** [ *table* ]
[ **-A****m**[*conf*]|*vector* ]
[ **-C**[**i**|**o**] ]
[ **-E** ]
[ **-N** ]
[ **-S***vector* ]
[ **-T****a**|**d**|**D**|**p***azim*|**r**[*arg*]|**R**|**s**|**t**[*arg*]|**x** ]
[ **-V**[*level*] ]
[ **-b**binary ]
[ **-d**nodata[**+c***col*] ]
[ **-e**regexp ]
[ **-f**flags ]
[ **-g**gaps ]
[ **-h**headers ]
[ **-i**flags ]
[ **-j**flags ]
[ **-o**flags ]
[ **-q**flags ]
[ **-s**flags ]
[ **-:**[**i**|**o**] ]
[ **--PAR**=*value* ]

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

## Description

**vector** reads either (x, y), (x, y, z), (r, theta) or (*lon, lat*)
[or (*lat, lon*); see **-:**] coordinates from the first 2-3 columns on
standard input [or one or more tables]. If **-fg** is selected and only two items
are read (i.e., *lon, lat*) then these coordinates are converted to
Cartesian three-vectors on the unit sphere. Otherwise we expect (r,
theta) unless **-Ci** is in effect. If no file is found we expect a
single vector to be given as argument to **-A**; this argument will also
be interpreted as an x/y[/z], lon/lat, or r/theta vector. The input
vectors (or the one provided via **-A**) are denoted the prime
vector(s). Several standard vector operations (angle between vectors,
cross products, vector sums, and vector rotations) can be selected; most
require a single second vector, provided via **-S**. The output vectors
will be converted back to (*lon, lat*) or (*r, theta*) unless **-Co** is set,
which requests (*x, y*[*, z*]) Cartesian coordinates.

## Required Arguments

*table*One or more ASCII [or binary, see

**-bi**] file containing (*lon, lat*) [or (*lat, lon*) if**-:**] values in the first 2 columns (if**-fg**is given) or (*r, theta*), or perhaps (*x, y*[*, z*]) if**-Ci**is given). If no file is specified,**vector**, will read from standard input.

## Optional Arguments

**-A****m**[*conf*]|*vector*Specify a single, primary vector instead of reading data table(s); see

*table*for possible vector formats. Alternatively, append**m**to read*table*and set the single, primary vector to be the mean resultant vector first. We also compute the confidence ellipse for the mean vector (azimuth of major axis, major axis, and minor axis; for geographic data the axes will be reported in km). You may optionally append the confidence level in percent [95]. These three parameters are reported in the final three output columns.

**-C**[**i**|**o**]Select Cartesian coordinates on input and output. Append

**i**for input only or**o**for output only; otherwise both input and output will be assumed to be Cartesian [Default is polar r/theta for 2-D data and geographic lon/lat for 3-D].

**-E**Convert input geographic coordinates from geodetic to geocentric and output geographic coordinates from geocentric to geodetic. Ignored unless

**-fg**is in effect, and is bypassed if**-C**is selected.

**-N**Normalize the resultant vectors prior to reporting the output [No normalization]. This only has an effect if

**-Co**is selected.

**-S**[*vector*]Specify a single, secondary vector in the same format as the first vector. Required by operations in

**-T**that need two vectors (average, bisector, dot product, cross product, and sum).

**-T****a**|**d**|**D**|**p***azim*|**s**|**r**[*arg*]|**R**|**s**|**t**[*arg*]|**x**Specify the vector transformation of interest via these directives:

**a**: Compute the vector average.**b**: Determines the pole of the two points bisector.**d**: Compute dot product of the two vectors.**D**: Same as**+d**but returns the angle in degrees between the two vectors.**p**: The pole to the great circle specified by input vector and the circle’s*azim*(no second vector used).**s**: Evaluate the vector sum.**r**: Perform vector rotation (here,*par*is a single angle for 2-D Cartesian data and*lon/lat/angle*for a 3-D rotation pole and angle)**R**: Similar to**r**but will instead rotate the fixed secondary vector by the rotations implied by the input records.**t**: Translate the input point by a*distance*in the*azimuth*direction (append*azimuth*/*distance*[*unit*] for the same translation for all input points, or just append*unit*to read*azimuth*and*distance*(in specified*unit*[**e**]) from the third and fourth data column in the file.**x**: Compute the vectors or cross-product.

If

**-T**is not given then no transformation takes place; the output is determined by other options, such as**-A**,**-C**,**-E**, and**-N**.**Notes**for directive**t**: (1) If geographic coordinates we will perform a great circle calculation unless**-je**or**-jf**is selected; (2) if a distance is negative then we remove the sign and add 180 degrees to the azimuth.

**-V**[*level*]Select verbosity level [

**w**]. (See full description) (See cookbook information).

**-bi***record*[**+b**|**l**] (more …)Select native binary format for primary table input. [Default is 2 or 3 input columns].

**-bo***record*[**+b**|**l**] (more …)Select native binary format for table output. [Default is same as input].

**-d**[**i**|**o**][**+c***col*]*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****x**|**y**|**z**|**d**|**X**|**Y**|**D***gap*[**u**][**+a**][**+c***col*][**+n**|**p**] (more …)Determine data gaps and line breaks.

**-h**[**i**|**o**][*n*][**+c**][**+d**][**+m***segheader*][**+r***remark*][**+t***title*] (more …)Skip or produce header record(s).

**-i***cols*[**+l**][**+d***divisor*][**+s***scale*|**d**|**k**][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select input columns and transformations (0 is first column,

**t**is trailing text, append*word*to read one word only).

**-je**|**f**|**g**(more …)Determine how spherical distances or coordinate transformations are calculated.

**-o***cols*[**+l**][**+d***divisor*][**+s***scale*|**d**|**k**][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select output columns and transformations (0 is first column,

**t**is trailing text, append*word*to write one word only).

**-q**[**i**|**o**][~]*rows*|*limits*[**+c***col*][**+a**|**t**|**s**] (more …)Select input or output rows or data limit(s) [all].

**-:**[**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 exit (

**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 exit.

**-?**or no argumentsPrint a complete usage (help) message, including the explanation of all options, then exit.

**--PAR**=*value*Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

## 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.

## Examples

**Note**: Below are some examples of valid syntax for this module.
The examples that use remote files (file names starting with `@`

)
can be cut and pasted into your terminal for testing.
Other commands requiring input files are just dummy examples of the types
of uses that are common but cannot be run verbatim as written.

To determine the mean location of all points in the remote geographic file @ship_15.txt as well as the 95% confidence ellipse around that point, try:

```
gmt vector @ship_15.txt -Am -fg
```

Suppose you have a file with (*lon, lat*) called points.txt. You want to
compute the spherical angle between each of these points and the
location 133/34. Try:

```
gmt vector points.txt -S133/34 -TD -fg > angles.txt
```

To rotate the same points 35 degrees around a pole at 133/34, and output Cartesian 3-D vectors, use:

```
gmt vector points.txt -Tr133/34/35 -Co -fg > reconstructed.txt
```

To rotate the point 65/33 by all rotations given in file rots.txt, use:

```
gmt vector rots.txt -TR -S64/33 -fg > reconstructed.txt
```

To compute the cross-product between the two Cartesian vectors 0.5/1/2 and 1/0/0.4, and normalizing the result, try:

```
gmt vector -A0.5/1/2 -Tx -S1/0/0.4 -N -C > cross.txt
```

To rotate the 2-D vector, given in polar form as r = 2 and theta = 35, by an angle of 120, try:

```
gmt vector -A2/35 -Tr120 > rotated.txt
```

To find the mid-point along the great circle connecting the points 123/35 and -155/-30, use:

```
gmt vector -A123/35 -S-155/-30 -Ta -fg > midpoint.txt
```

To find the mean location of the geographical points listed in points.txt, with its 99% confidence ellipse, use:

```
gmt vector points.txt -Am99 -fg > centroid.txt
```

To find the pole corresponding to the great circle that goes through the point -30/60 at an azimuth of 105 degrees, use:

```
gmt vector -A-30/60 -Tp105 -fg > pole.txt
```

To translate all locations in the geographic file points.txt by 65 km to the NE on a spherical Earth, try:

```
gmt vector points -Tt45/65k -fg > shifted.txt
```

To determine the point that is 23 nautical miles along a geodesic with a bearing of 310 degrees from the origin at (8E, 50N), try:

```
echo 8 50 | gmt vector -Tt310/23n -je
```

## Rotations

For more advanced 3-D rotations as used in plate tectonic reconstructions, see the GMT “spotter” supplement.