NAME

     mapproject - Forward and Inverse map transformation  of  2-D
     coordinates


SYNOPSIS

     mapproject infiles -Jparameters -Rwest/east/south/north[r] [
     -C  ]  [  -Dc|i|m|p  ]  [  -F[k|m|n] ] [ -H[nrec] ] [ -I ] [
     -M[flag] ] [ -S ] [ -V ] [ -: ] [ -bi[s][n] ] [ -bo[s] ]


DESCRIPTION

     mapproject  reads  (longitude,  latitude)   positions   from
     infiles  [or  standard input] and computes (x,y) coordinates
     using the specified map projection and scales.   Optionally,
     it  can  read  (x,y) positions and compute (longitude, lati-
     tude) values doing the inverse transformation.  This can  be
     used to transform linear (x,y) points obtained by digitizing
     a map  of  known  projection  to  geographical  coordinates.
     Additional  data  fields  are  permitted  after  the first 2
     columns which must have (longitude,latitude) or (x,y).   See
     option -: on how to read (latitude,longitude) files.
          No space between the option  flag  and  the  associated
     arguments.   Use  upper  case for the option flags and lower
     case for modifiers.

     infiles
          Data file(s) to be transformed.  If not given, standard
          input is read.

     -J   Selects the map projection.   The  following  character
          determines  the  projection.  If the character is upper
          case then  the  argument(s)  supplied  as  scale(s)  is
          interpreted to be the map width (or axis lengths), else
          the scale argument(s) is the map scale (see its defini-
          tion  for  each  projection).   UNIT is cm, inch, or m,
          depending on the MEASURE_UNIT setting in  .gmtdefaults,
          but  this  can  be  overridden  on  the command line by
          appending c, i, or m to the scale/width values.  Choose
          one of the following projections (The E or C after pro-
          jection names  stands  for  Equal-Area  and  Conformal,
          respectively):

          CYLINDRICAL PROJECTIONS:

          -Jclon0/lat0/scale or -JClon0/lat0/width (Cassini)
               Give  projection  center  and  scale  (1:xxxx   or
          UNIT/degree).
          -Jjlon0/scale or -JJlon0/width (Miller Cylindrical Pro-
          jection)
               Give the central meridian  and  scale  (1:xxxx  or
          UNIT/degree).
          -Jmparameters (Mercator [C]).  Specify one of:
               -Jmscale or -JMwidth
                    Give   scale   along   equator   (1:xxxx   or
          UNIT/degree).
               -Jmlon0/lat0/scale or -JMlon0/lat0/width
                    Give central meridian, standard latitude  and
          scale along parallel (1:xxxx or UNIT/degree).
          -Joparameters (Oblique Mercator [C]).  Specify one of:
               -Joalon0/lat0/azimuth/scale                     or
          -JOalon0/lat0/azimuth/width
                    Set projection  center,  azimuth  of  oblique
          equator, and scale.
               -Joblon0/lat0/lon1/lat1/scale                   or
          -JOblon0/lat0/lon1/lat1/scale
                    Set projection center, another point  on  the
          oblique equator, and scale.
               -Joclon0/lat0/lonp/latp/scale                   or
          -JOclon0/lat0/lonp/latp/scale
                    Set projection center, pole of  oblique  pro-
          jection, and scale.
               Give  scale  along  oblique  equator  (1:xxxx   or
          UNIT/degree).
          -Jqlon0/scale or -JQlon0/width (Equidistant Cylindrical
          Projection (Plate Carree))
               Give the central meridian  and  scale  (1:xxxx  or
          UNIT/degree).
          -Jtparameters (Transverse Mercator [C]).   Specify  one
          of:
               -Jtlon0/scale or -JTlon0/width
                    Give the central meridian and  scale  (1:xxxx
          or UNIT/degree).
               -Jtlon0/lat0/scale or -JTlon0/lat0/width
                    Give projection center and scale  (1:xxxx  or
          UNIT/degree).
          -Juzone/scale  or  -JUzone/width   (UTM   -   Universal
          Transverse Mercator [C])
               Give  the  zone  number  and  scale   (1:xxxx   or
          UNIT/degree).
               Use negative zone numbers for the  southern  hemi-
          sphere.
          -Jylon0/lats/scale   or    -JYlon0/lats/width    (Basic
          Cylindrical Projections [E])
               Give the central meridian, standard parallel,  and
          scale (1:xxxx or UNIT/degree).
               The standard parallel is typically  one  of  these
          (but can be any value):
               45   - The Peters projection
               37.4 - The Trystan Edwards projection
               30   - The Behrman projection
               0    - The Lambert projection

          AZIMUTHAL PROJECTIONS:

          -Jalon0/lat0/scale or -JAlon0/lat0/width (Lambert [E]).
               lon0/lat0 specifies the projection center.
               Give scale as 1:xxxx or radius/lat,  where  radius
          is distance
               in UNIT from origin to the oblique latitude lat.
          -Jelon0/lat0/scale or -JElon0/lat0/width (Equidistant).
               lon0/lat0 specifies the projection center.
               Give scale as 1:xxxx or radius/lat,  where  radius
          is distance
               in UNIT from origin to the oblique latitude lat.
          -Jflon0/lat0/horizon/scale                           or
          -JFlon0/lat0/horizon/width (Gnomonic).
               lon0/lat0 specifies the projection center.
               horizon specifies the max distance from projection
          center (in degrees, < 90).
               Give scale as 1:xxxx or radius/lat,  where  radius
          is distance
               in UNIT from origin to the oblique latitude lat.
          -Jglon0/lat0/scale   or   -JGlon0/lat0/width    (Ortho-
          graphic).
               lon0/lat0 specifies the projection center.
               Give scale as 1:xxxx or radius/lat,  where  radius
          is distance
               in UNIT from origin to the oblique latitude lat.
          -Jslon0/lat0/scale   or   -JSlon0/lat0/width   (General
          Stereographic [C])
               lon0/lat0 specifies the projection center.
               Give scale as 1:xxxx or radius/lat,  where  radius
          is distance
               in UNIT from origin to the oblique latitude lat.

          CONIC PROJECTIONS:

          -Jblon0/lat0/lat1/lat2/scale                         or
          -JBlon0/lat0/lat1/lat2/width (Albers [E])
               Give projection center,  two  standard  parallels,
          and scale (1:xxxx or UNIT/degree).
          -Jdlon0/lat0/lat1/lat2/scale                         or
          -JDlon0/lat0/lat1/lat2/width (Equidistant)
               Give projection center,  two  standard  parallels,
          and scale (1:xxxx or UNIT/degree).
          -Jllon0/lat0/lat1/lat2/scale                         or
          -JLlon0/lat0/lat1/lat2/width (Lambert [C])
               Give origin, 2 standard parallels, and scale along
          these (1:xxxx or UNIT/degree).

          MISCELLANEOUS PROJECTIONS:

          -Jhlon0/scale or -JHlon0/width (Hammer [E])
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).
          -Jilon0/scale or -JIlon0/width (Sinusoidal [E])
               Give the central meridian and scale along  equator

          (1:xxxx or UNIT/degree).
          -Jk[f|s]lon0/scale or -JK[f|s]lon0/width (Eckert IV (f)
          and VI (s) [E])
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).
          -Jnlon0/scale or -JNlon0/width (Robinson)
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).
          -Jrlon0/scale -JRlon0/width (Winkel Tripel)
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).
          -Jvlon0/scale or -JVlon0/width (Van der Grinten)
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).
          -Jwlon0/scale or -JWlon0/width (Mollweide [E])
               Give the central meridian and scale along  equator
          (1:xxxx or UNIT/degree).

          NON-GEOGRAPHICAL PROJECTIONS:

          -Jpscale[/origin] or -JPwidth[/origin] (Linear  projec-
          tion for polar (theta,r) coordinates, optionally append
          /origin in degrees to indicate an angular offset [0]).
               Give scale in UNIT/r-unit.
          -Jxx-scale[/y-scale] or -JXwidth[/height]
          scale [or width] can be any of the following 3 types:
               -Jxscale       - Regular linear scaling.
               -Jxscalel - Take log10 of values before scaling.
               -Jxscaleppower -  Raise  values  to  power  before
          scaling.
          Give x-scale in UNIT/x-unit and y-scale in UNIT/y-unit.
          (y-scale  =  x-scale if not specified separately).  Use
          negative scale(s) to reverse the direction of  an  axis
          (e.g., to have y be positive down).

          Append d if x and y  are  geographical  coordinates  in
          degrees.  Default axes lengths (see gmtdefaults) can be
          invoked using -JXh (for landscape); -JXv (for portrait)
          will  swap  the x- and y-axes lengths.  The GMT default
          unit for this installation is UNIT.  However,  you  may
          change  this  by editing your .gmtdefaults file(s) (run
          gmtdefaults to create one if you don't have it).
               The ellipsoid  used  in  the  map  projections  is
          user-definable by editing the .gmtdefaults file in your
          home directory.  13  commonly  used  ellipsoids  and  a
          spheroid  are  currently  supported, and users may also
          specify their own ellipsoid parameters (see man  gmtde-
          faults for more details).  GMT default is WGS-84.

     -R   west, east, south, and  north  specify  the  Region  of
          interest.  To specify boundaries in degrees and minutes
          [and seconds], use the dd:mm[:ss] format.  Append r  if
          lower  left  and  upper right map coordinates are given
          instead of wesn.


OPTIONS

     infile(s)
          input file(s) with 2 or more columns. If no file(s)  is
          given, mapproject will read standard input.

     -C   Set center of projected coordinates to be at  map  pro-
          jection center [Default is lower left corner].

     -D   Temporarily override MEASURE_UNIT and  use  c  (cm),  i
          (inch), m (meter), or p (points) instead.

     -F   Force 1:1 scaling, i.e., output (or input, see -I) data
          are  in  actual  projected  meters.   To  specify other
          units, append k (km), m  (mile),n  (nautical  mile),  i
          (inch),  c (cm), or p (points).  Without -F, the output
          (or input, see  -I)  are  in  the  units  specified  by
          MEASURE_UNIT (but see -D).

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

     -I   Do    the    Inverse    transformation,    i.e.     get
          (longitude,latitude) from (x,y) data.

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

     -S   Suppress points that fall outside the region.

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

     -:   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 transform a file  with  (longitude,latitude)  into  (x,y)
     positions  in cm on a Mercator grid for a given scale of 0.5
     cm per degree, run

     mapproject lonlatfile -R20/50/12/25 -Jm0.5c > xyfile

     To transform  several  2-column,  binary,  double  precision
     files with (latitude,longitude) into (x,y) positions in inch
     on a Transverse Mercator grid (central  longitude  75W)  for
     scale  =  1:500000 and suppress those points that would fall
     outside the map area, run

     mapproject tracks.* -R-80/-70/20/40  -Jt-75/1:500000  -:  -S
     -Di -bo -bi2 > tmfile.b


RESTRICTIONS

     The rectangular input region set with -R will in general  be
     mapped  into  a non-rectangular grid.  Unless -C is set, the
     leftmost point on this grid has xvalue = 0.0, and the lower-
     most point will have yvalue = 0.0. Thus, before you digitize
     a map, run the extreme map  coordinates  through  mapproject
     using  the appropriate scale and see what  (x,y) values they
     are mapped onto.  Use these values when setting up for digi-
     tizing  in  order  to  have  the inverse transformation work
     correctly, or alternatively, use awk to scale and shift  the
     (x,y) values before transforming.


ELLIPSOIDS AND SPHEROIDS

     GMT will use ellipsoidal formulae if  they  are  implemented
     and  the  user  have  selected an ellipsoid as the reference
     shape (see gmtdefaults).  The user needs to be  aware  of  a
     few  potential  pitfalls: (1)  For some projections, such as
     Transverse Mercator, Albers, and Lamberts conformal conic we
     use  the  ellipsoidal  expressions when the areas mapped are
     small, and switch to the spherical expressions (and  substi-
     tuting the appropriate auxillary latitudes) for larger maps.
     The  ellipsoidal  formulae  are  used   are   follows:   (a)
     Transverse  Mercator:  When all points are within 10 degrees
     of central meridian, (b) Conic projections when longitudinal
     range  is  less than 90 degrees, (c) Cassini projection when
     all points are within 4 degrees  of  central  meridian.  (2)
     When  you  are  trying  to match some historical data (e.g.,
     coordinates obtained with a certain projection and a certain
     reference  ellipsoid)  you  may  find that GMT gives results
     that are slightly different.   One  likely  source  of  this
     mismatch is that older calculations often used less signifi-
     cant digits.  For instance, Snyder's examples often use  the
     Clarke 1866 ellipsoid (defined by him as having a flattening
     f = 1/294.98).  From f we get the eccentricity squared to be
     0.00676862818  (this  is what GMT uses), while Snyder rounds
     off  and  uses  0.00676866.   This   difference   can   give
     discrepancies of several 10 of cm.  If you need to reproduce
     coordinates   projected   with   this   slightly   different
     eccentricity, you should specify your own ellipsoid with the
     same parameters as Clarke 1866, but with f = 1/294.97861076.


SEE ALSO

     gmtdefaults(l), gmt(l), project(l)


REFERENCES

     Snyder, J. P., 1987, Map Projections  -  A  Working  Manual,
     U.S. Geological Survey Prof. Paper 1395.