project
project - project data along a line or great circle, gen
erate a profile track, or translate coordinates.
SYNOPSIS
project [ infile ] -Fflags -Ccx/cy [ -Aazimuth ] [ -Dd|g ]
[ -Ebx/by ] [ -Gdist ] [ -H[nrec] ] [ -L[w][l_min/l_max] ]
[ -M[flag] ] [ -N ] [ -Q ] [ -S ] [ -Tpx/py ] [ -V ] [
-Ww_min/w_max ] [ -: ] [ -bi[s][n] ] [ -bo[s] ]
DESCRIPTION
project reads arbitrary (x, y[, z]) data from standard
input [or infile ] and writes to standard output any com
bination of (x, y, z, p, q, r, s), where (p, q) are the
coordinates in the projection, (r, s) is the position in
the (x, y) coordinate system of the point on the profile
(q = 0 path) closest to (x, y), and z is all remaining
columns in the input (beyond the required x and y
columns). Alternatively, project may be used to generate
(r, s, p) triples at equal increments dist along a pro
file. In this case ( -G option), no input is read. Pro
jections are defined in any (but only) one of three ways:
(Definition 1) By a Center -C and an Azimuth -A in degrees
clockwise from North. (Definition 2) By a Center -C and
end point E of the projection path -E. (Definition 3) By
a Center -C and a roTation pole position -T. To spheri
cally project data along a great circle path, an oblique
coordinate system is created which has its equator along
that path, and the zero meridian through the Center. Then
the oblique longitude (p) corresponds to the distance from
the Center along the great circle, and the oblique lati
tude (q) corresponds to the distance perpendicular to the
great circle path. When moving in the increasing (p)
direction, (toward B or in the azimuth direction), the
positive (q) direction is to your left. If a Pole has
been specified, then the positive (q) direction is toward
the pole. To specify an oblique projection, use the -T
option to set the Pole. Then the equator of the projection
is already determined and the -C option is used to locate
the p = 0 meridian. The Center cx/cy will be taken as a
point through which the p = 0 meridian passes. If you do
not care to choose a particular point, use the South pole
(ox = 0, oy = -90). Data can be selectively windowed by
using the -L and -W options. If -W is used, the projection
Width is set to use only points with w_min < q < w_max. If
-L is set, then the Length is set to use only those points
with l_min < p < l_max. If the -E option has been used to
define the projection, then -Lw may be selected to window
the length of the projection to exactly the span from O to
B. Flat earth (cartesian) coordinate transformations can
also be made. Set -N and remember that azimuth is clock
wise from North (the y axis), NOT the usual cartesian
theta, which is counterclockwise from the x axis. azimuth
If -Q is selected, map units are assumed and x, y, r, s
must be in degrees and p, q, dist, l_min, l_max, w_min,
w_max will be in km. project is CASE SENSITIVE. Use UPPER
CASE for all one-letter designators which begin optional
arguments. Use lower case for the xyzpqrs letters in
-flags.
-C cx/cy sets the origin of the projection, in Defini
tion 1 or 2. If Definition 3 is used (-T), then
cx/cy are the coordinates of a point through which
the oblique zero meridian (p = 0) should pass.
OPTIONS
infile name of ASCII (or binary, see -bi) file(s) with 2
or more columns holding (x,y,[z]) data values. If
no filenames are given, project will read from
standard input. If the -G option is selected, no
input data are read.
-F Specify your desired output using any combination
of xyzpqrs, in any order. Do not space between the
letters. Use lower case. The output will be ASCII
(or binary) columns of values corresponding to
xyzpqrs. If both input and output are using ASCII
format then the z data are treated as
textstring(s). If the -G option is selected, the
output will be rsp.
-A azimuth defines the azimuth of the projection (Def
inition 1).
-D Set the location of the Discontinuity in longitude
(r coordinate). -Dd will place the discontinuity at
the Dateline, (-180 < r < 180); -Dg will place it
at Greenwich, (0 < r < 360). Default usually falls
at dateline due to atan2 calls.
-E bx/by defines the end point of the projection path
(Definition 2).
-G dist Generate mode. No input is read. Create (r, s,
p) output points every dist units of p. See -Q
option.
-H Input file(s) has Header record(s). Number of
header records can be changed by editing your .gmt
defaults file. If used, GMT default is 1 header
record.
-L Length controls. Project only those points whose p
coordinate is within l_min < p < l_max. If -E has
-M Multiple segment file(s). Segments are separated by
a special record. For ASCII files the first char
acter must be flag [Default is '>']. For binary
files all fields must be NaN.
-N Flat earth. Make a cartesian coordinate transforma
tion in the plane. [Default uses spherical
trigonometry.]
-Q Map type units, i.e., project assumes x, y, r, s
are in degrees while p, q, dist, l_min,l _max,
w_min, w_max are in km. If -Q is not set, then all
these are assumed in same units.
-S Sort the output into increasing p order. Useful
when projecting random data into a sequential pro
file.
-T px/py sets the position of the roTation pole of the
projection. (Definition 3).
-V Selects verbose mode, which will send progress
reports to stderr [Default runs "silently"].
-W Width controls. Project only those points whose q
coordinate is within w_min < q < w_max.
-: Toggles between (longitude,latitude) and (lati
tude,longitude) input/output. [Default is (longi
tude,latitude)]. Applies to geographic coordinates
only.
-bi Selects binary input. Append s for single precision
[Default is double]. Append n for the number of
columns in the binary file(s). [Default is 2 input
columns].
-bo Selects binary output. Append s for single preci
sion [Default is double].
EXAMPLES
To generate points every 10km along a great circle from
10N,50W to 30N,10W, try:
project -C-50/10 -E-10/30 -G10 -Q > great_cir
cle_points.xyp
(Note that great_circle_points.xyp could now be used as
input for grdtrack, etc. ).
To project the shiptrack gravity, magnetics, and
N20W at the origin, keeping only the data from NE of the
profile and within +/- 500 km of the origin, try:
project c2610.xygmb -C-30/-30 -A-20 -W-10000/0 -L-500/500
-Fpz -Q > c2610_projected.pgmb
(Note in this example that -W-10000/0 is used to admit any
value with a large negative q coordinate. This will take
those points which are on our right as we walk along the
great circle path, or to the NE in this example.)
To make a cartesian coordinate transformation of mydata.xy
so that the new origin is at 5,3 and the new x axis (p)
makes an angle of 20 degrees with the old x axis, try:
project mydata.xy -C5/3 -A70 -Fpq > mydata.pq
To take data in the file pacific.lonlat and transform it
into oblique coordinates using a pole from the hotspot
reference frame and placing the oblique zero meridian (p =
0 line) through Tahiti, try:
project pacific.lonlat -T-75/68 -C-149:26/-17:37 -Fpq >
pacific.pq
Suppose that pacific_topo.grd is a grdfile of bathymetry,
and you want to make a file of flowlines in the hotspot
reference frame. If you try:
grd2xyz pacific_topo.grd | project -T-75/68 -C0/-90 -Fxyq
| xyz2grd -Retc -Ietc -Cflow.grd
then flow.grd is a file in the same area as
pacific_topo.grd, but flow contains the latitudes about
the pole of the projection. You now can use grdcontour on
flow.grd to draw lines of constant oblique latitude, which
are flow lines in the hotspot frame.
If you have an arbitrarily rotation pole px/py and you
would like to draw an oblique small circle on a map, you
will first need to make a file with the oblique coordi
nates for the small circle (i.e., lon = 0-360, lat is con
stant), then create a file with two records: the north
pole (0/90) and the origin (0/0), and find what their
oblique coordinates are using your rotation pole. Now, use
the projected North pole and origin coordinates as the
rotation pole and center, respectively, and project your
file as in the pacific example above. This gives coordi
nates for an oblique small circle.
SEE ALSO
fitcircle(l), gmt(l), mapproject(l), grdproject(l)
Man(1) output converted with
man2html