NAME

     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 combination
     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 profile.  In this case ( -G option),
     no input is read.  Projections 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 spherically project data along a great circle  path,
     an  oblique coordinate system is created which has its equa-
     tor 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 latitude (q) corresponds to the distance perpendicu-
     lar 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 projec-
     tion,  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  clockwise  from  North
     (the  y axis), NOT the usual cartesian theta, which is coun-
     terclockwise from the x axis.  azimuth  =  90  -  theta.  No
     assumptions  are made regarding the units for x, y, r, s, p,
     q, dist, l_min,l _max, w_min, w_max.  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 desig-
     nators which begin optional arguments.  Use lower  case  for
     the xyzpqrs letters in -flags.


     -C   cx/cy sets the origin of the projection, in  Definition
          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  (Defini-
          tion 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 .gmtdefaults
          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 been
          set, then you may use -Lw to stay within  the  distance
          from C to E.

     -M   Multiple segment file(s).  Segments are separated by  a
          special  record.   For  ASCII files the first character
          must be flag [Default is '>'].  For  binary  files  all
          fields must be NaN.

     -N   Flat earth.  Make a cartesian coordinate transformation
          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 profile.

     -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
          (latitude,longitude)    input/output.     [Default   is
          (longitude,latitude)].

     -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  precision
          [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_circle_points.xyp

     (Note that great_circle_points.xyp  could  now  be  used  as
     input for grdtrack, etc. ).

     To project the shiptrack gravity, magnetics, and  bathymetry
     in  c2610.xygmb  along  a  great circle through an origin at
     30S, 30W, the great circle having an azimuth of 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  coordinates  for
     the  small circle (i.e., lon = 0-360, lat is constant), 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  exam-
     ple above.  This gives coordinates for an oblique small cir-
     cle.



SEE ALSO

     fitcircle(l), gmt(l), mapproject(l), grdproject(l)