## 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 stan-
           dard input] and computes (x,y) coordinates using the specified map pro-
           jection  and  scales.  Optionally, it can read (x,y) positions and com-
           pute (longitude, latitude) values  doing  the  inverse  transformation.
           This  can be used to transform linear (x,y) points obtained by digitiz-
           ing 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  (lati-
           tude,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  argu-
                  ment(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 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  pro-
                  jections  (The  E  or C after projection 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 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  equa-
                  tor, 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  projec-
                  tion, and scale.
                          Give    scale   along   oblique   equator   (1:xxxx   or
                  UNIT/degree).
                  -Jqlon0/scale or -JQlon0/width (Equidistant Cylindrical  Projec-
                  tion (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  Mer-
                  cator [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 Pro-
                  jections [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 dis-
                  tance
                          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 dis-
                  tance
                          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 cen-
                  ter (in degrees, < 90).
                          Give scale as 1:xxxx or radius/lat, where radius is dis-
                  tance
                          in UNIT from origin to the oblique latitude lat.
                  -Jglon0/lat0/scale or -JGlon0/lat0/width (Orthographic).
                          lon0/lat0 specifies the projection center.
                          Give scale as 1:xxxx or radius/lat, where radius is dis-
                  tance
                          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  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:

                  -Jp[a]scale[/origin]  or -JP[a]width[/origin] (Linear 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  separately).  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  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  .gmtde-
                  faults  file(s) (run gmtdefaults to create one if you don’t have
                  it).’
                          The ellipsoid used in the map projections is user-defin-
                  able 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.  Sev-
                  eral GMT parameters can affect the projection: ELLIPSOID, INTER-
                  POLANT, MAP_SCALE_FACTOR, and MEASURE_UNIT; see the  gmtdefaults
                  man page for details.

           -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 projection cen-
                  ter [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 spec-
                  ified 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)].   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]

           -O     Selects  Overlay  plot mode [Default initializes a new plot sys-
                  tem].

## 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  Mer-
           cator  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) val-
           ues they are mapped onto. Use these values when setting up for digitiz-
           ing  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  confor-
           mal  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 for-
           mulae 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 significant
           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 coor-
           dinates 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. Geologi-
           cal Survey Prof. Paper 1395.

    GMT3.4.6                          1 Jan 2005                     MAPPROJECT(l)