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|i|c|p] ] [ -H[nrec] ] [ -I
       ] [ -M[flag] ] [ -S ] [ -V ]  [  -:  ]  [  -bi[s][n]  ]  [
       -bo[s][n] ]


DESCRIPTION

       mapproject  reads  (longitude,  latitude)  positions  from
       infiles [or standard input] and computes (x,y) coordinates
       using  the  specified  map projection and scales.  Option­
       ally, it can read (x,y) positions and compute  (longitude,
       latitude)  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 coor­
       dinates.  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 associ­
       ated arguments. Use upper case for the  option  flags  and
       lower case for modifiers.

       infiles
              Data file(s) to be transformed. If not given, stan­
              dard 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 definition for each projection).
              UNIT is cm, inch,  or  m,  depending  on  the  MEA­
              SURE_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  projection
              names  stands for Equal-Area and Conformal, respec­
              tively):

              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
              Projection).
                      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 projection, and scale.
                      Give scale along oblique equator (1:xxxx or
              UNIT/degree).
              -Jqlon0/scale  or -JQlon0/width (Equidistant Cylin­
              drical 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  (1-60)  and  scale
              (1:xxxx or UNIT/degree).
                      zones: prepend - or + to  enforce  southern
              or  northern  hemisphere  conventions  [northern if
              south > 0].
              -Jylon0/lats/scale  or  -JYlon0/lats/width   (Basic
              Cylindrical Projections [E]).
                      Give  the central meridian, standard paral­
              lel, 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 (Equidis­
              tant).
                      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/hori­
              zon/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  (true  at  pole)  or
              slat/1:xxxx (true at standard parallel slat)
                      or  radius/lat  (radius 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 paral­
              lels, and scale (1:xxxx or UNIT/degree).
              -Jdlon0/lat0/lat1/lat2/scale                     or
              -JDlon0/lat0/lat1/lat2/width (Equidistant)
                      Give projection center, two standard paral­
              lels, 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:

              -Jp[a]scale[/origin] or -JP[a]width[/origin]  (Lin­
              ear  projection  for  polar  (theta,r) coordinates,
              optionally  insert  a  after  -Jp  [  or  -JP]  for
              azimuths  CW  from  North instead of directions CCW
              from East [default], 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 sepa­
              rately).  Use  negative  scale(s)  to  reverse  the
              direction  of  an axis (e.g., to have y be positive
              down).

              Append a single d if data are geographical  coordi­
              nates in degrees.  Default axes lengths (see gmtde­
              faults) can be invoked using -JXh (for  landscape);
              -JXv  (for  portrait)  will  swap the x- and y-axes
              lengths.  The GMT default unit for  this  installa­
              tion is UNIT. However, you may change this by edit­
              ing 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  gmtdefaults  for  more  details).    GMT
              default  is  WGS-84.  Several  GMT  parameters  can
              affect  the  projection:  ELLIPSOID,   INTERPOLANT,
              MAP_SCALE_FACTOR,  and MEASURE_UNIT; see the gmtde­
              faults man page for details.

       -R     west, east, south, and north specify the Region  of
              interest. To specify boundaries in degrees and min­
              utes [and  seconds],  use  the  dd:mm[:ss]  format.
              Append  r if lower left and upper right map coordi­
              nates 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
              projection center [Default is lower left corner].

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

       -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 .gmt­
              defaults  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  char­
              acter  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  (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 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
       lowermost 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 digitizing in order to have the inverse transforma­
       tion  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
       substituting  the  appropriate  auxillary  latitudes)  for
       larger maps. The ellipsoidal formulae are  used  are  fol­
       lows:  (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 significant digits. For instance, Snyder's exam­
       ples  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.



                            1 Mar 2002              MAPPROJECT(l)

Man(1) output converted with man2html