## NAME

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

## SYNOPSIS

           mapproject    infiles    -Jparameters    -Rwest/east/south/north[r]   [
           -Ab|B|f|Flon0/lat0 ] [ -C[dx/dy] ]  [  -Dc|i|m|p  ]  [  -E[datum]  ]  [
           -F[k|m|n|i|c|p]  ]  [  -G[x0/y0][/unit]  ]  [  -H[nrec]  ]  [  -I  ]  [
           -Lline.xy[/unit] ] [ -M[flag] ] [ -Q[d|e] [ -S ] [ -T[h]from[/to]  ]  [
           -V ] [ -: ] [ -bi[s][n] ] [ -bo[s][n] ] [ -f[i|o]colinfo ]

## 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.  May  also
           calculate  distances along track, to a fixed point, or closest approach
           to a line.  Finally, can be used to perform various datum  conversions.
           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  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  .gmtdefaults4,  but
                  this can be overridden on the command line by appending c, i, or
                  m to the scale/width values. Append h, +,  or  -  to  the  given
                  width  if you instead want to set map height, the maximum dimen-
                  sion, or the minimum dimension, respectively [Default is  w  for
                  width].   Choose  one  of  the following projections (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
                  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 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:

                  [Except  for  polar aspects, -Rw/e/s/n will be reset to -Rg. Use
                  -R<...>r for smaller regions]

                  -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.
                          -JxscaleT|t - Time axis. T indicates input coordinates
                          are  absolute  time while t means they are time relative
                  to TIME_EPOCH.
                  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 axis lengths (see gmtdefaults) can be  invoked
                  using -JXh (for landscape); -JXv (for portrait) will swap the x-
                  and y-axis lengths.  The GMT default unit for this  installation
                  is  UNIT.  However,  you may change this by editing your .gmtde-
                  faults4 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 .gmtdefaults4 file in your  home  directory.
                  63  commonly  used  ellipsoids and a spheroid are currently sup-
                  ported, and users may also specify their own  ellipsoid  parame-
                  ters  (see  man  gmtdefaults  for more details).  GMT default is
                  WGS-84. Several GMT parameters can affect the projection: ELLIP-
                  SOID,  INTERPOLANT,  MAP_SCALE_FACTOR, and MEASURE_UNIT; see the
                  gmtdefaults man page for details.

           -R     xmin, xmax, ymin, and ymax specify the Region of  interest.  For
                  geographic  regions,  these  limits  correspond  to  west, east,
                  south, and north and you may specify them in decimal degrees  or
                  in  [+-]dd:mm[:ss.xxx][W|E|S|N]  format.  Append r if lower left
                  and upper right map coordinates are given instead of  wesn.  The
                  two  shorthands  -Rg  -Rd  stand  for  global  domain  (0/360 or
                  -180/+180 in longitude respectively, with -90/+90 in  latitude).
                  For  calendar time coordinates you may either give relative time
                  (relative  to  the  selected  TIME_EPOCH  and  in  the  selected
                  TIME_UNIT;  append  t  to  -JX|x),  or absolute time of the form
                  [date]T[clock] (append T to -JX|x). At least  one  of  date  and
                  clock must be present; the T is always required. The date string
                  must be of the form [-]yyyy[-mm[-dd]]  (Gregorian  calendar)  or
                  yyyy[-Www[-d]]  (ISO week calendar), while the clock string must
                  be of the form hh:mm:ss[.xxx]. The use of delimiters  and  their
                  type  and  positions must be as indicated (however, input/output
                  and plotting formats are flexible).

## OPTIONS

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

           -A

           -Af  calculates  the (forward) azimuth from fixed point lon/lat to each
           data point. Use -Ab to get
                  backazimuth  from  data points to fixed point. Upper case F or B
                  will convert from geodetic to geocentric latitudes and  estimate
                  azimuth  of  geodesics  (assuming the current ellipsoid is not a
                  sphere).  -C Set center of projected coordinates to  be  at  map
                  projection  center  [Default is lower left corner].  Optionally,
                  add offsets in the projected units to be  added  (or  subtracted
                  when  -I  is  set)  to (from) the projected coordinates, such as
                  false eastings and northings  for  particular  projection  zones
                  [0/0].   The unit used for the offsets is the plot distance unit
                  in effect (see MEASURE_UNTI) unless -F is used,  in  which  case
                  the offsets are in meters.

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

           -E     Convert from geodetic (lon, lat, height) to Earth Centered Earth
                  Fixed (ECEF) (x,y,z) coordinates (add -I for the inverse conver-
                  sion). Append datum ID  (see  -Qd)  or  give  ellipsoid:dx,dy,dz
                  where  ellipsoid  may  be  an ellipsoid ID (see -Qe) or given as
                  a,1/f. If datum is - or not given we assume WGS-84.

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

           -G     Calculate distances along track OR to  the  optional  point  set
                  with  -Gx0/y0.  Append  the distance unit; choose among e (m), k
                  (km), m (mile), n  (nautical  mile),  d  (spherical  degree),  c
                  (Cartesian  distance  using  input  coordinates) or C (Cartesian
                  distance using projected coordinates). The last unit requires -R
                  and  -J  to  be  set. Upper case E, K, M, N, or D will use exact
                  methods for geodesic distances (Rudoe’s method for distances  in
                  length  units and emplying geocentric latitudes in degree calcu-
                  lations, assuming the current ellipsoid is not a sphere).

           -H     Input file(s) has Header record(s). Number of header records can
                  be  changed  by  editing  your  .gmtdefaults4 file. If used, GMT
                  default is 1 header record. Use -Hi if only  input  data  should
                  have  header  records  [Default will write out header records if
                  the input data have them].

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

           -L     Determine  the  shortest  distance from the input data points to
                  the line(s) given  in  the  ASCII  multi-segment  file  line.xy.
                  Append  the distance unit; choose among e (m), k (km), m (mile),
                  n (nautical mile), d (spherical degree), c  (Cartesian  distance
                  using  input  coordinates)  or  C (Cartesian distance using pro-
                  jected coordinates). The last unit requires -R and -J to be set.
                  A spherical approximation is used for geographic 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 and
                  -bo[s]n must set the number of output columns explicitly.

           -Q     List all projection parameters. To only list datums, use -Qd. To
                  only list ellipsoids, use -Qe.

           -S     Suppress points that fall outside the region.

           -T     Coordinate  conversions  between  datums from and to. Use -Th if
                  3rd input column has height  above  ellipsoid  [Default  assumes
                  height = 0, i.e., on the ellipsoid]. Specify datums using the ID
                  (see -Qd) or give ellipsoid:dx,dy,dz, where ellipsoid may be  an
                  ellipsoid  ID  (see -Qe) or given as a,1/f. If datum is - or not
                  given we use WGS-84.  -T may be used in conjunction with  -R  -J
                  to  change  the  datum  before  coordinate projection (add -I to
                  apply the datum conversion after the inverse  projection).  Make
                  sure that the ELLIPSOID setting is correct for your case.

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

           -:     Toggles between  (longitude,latitude)  and  (latitude,longitude)
                  input  and/or output. [Default is (longitude,latitude)].  Append
                  i to select input only or o  to  select  output  only.  [Default
                  affects both].

           -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].  Append n for the  number  of  columns  in  the  binary
                  file(s).

           -f     Special  formatting  of  input  and output columns (time or geo-
                  graphical data) Specify i(nput) or  o(utput)  [Default  is  both
                  input  and output].  Give one or more columns (or column ranges)
                  separated by commas.  Append T (Absolute calendar time), t (time
                  relative  to  chosen TIME_EPOCH), x (longitude), y (latitude), g
                  (geographic coordinate), or f (floating point) to each column or
                  column range item.

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

           To convert the geodetic coordinates (lon,  lat,  height)  in  the  file
           old.dat  from  the  NAD27  CONUS  datum  (Datum  ID  131 which uses the
           Clarke-1866 ellipsoid) to WGS 84, run

           mapproject old.dat -Th131 > new.dat To compute the closest distance (in
           km)  between  each point in the input file quakes.dat and the line seg-
           ments given in the multi-segment ASCII file coastline.xy, run

           mapproject quakes.dat -Lcoastline.xy/k > quake_dist.dat

## 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 auxiliary latitudes) for larger maps. The ellipsoidal  for-
           mulae are used as follows: (a) Transverse Mercator: When all points are
           within 10 degrees of central meridian, (b) Conic projections when  lon-
           gitudinal  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  tens 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. Also, be aware that older  data  may
           be  referenced to different datums, and unless you know which datum was
           used and convert all data to a common datum  you  may  experience  mis-
           matches of tens to hundreds of meters.

## SEE ALSO

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

## REFERENCES

           Bomford, G., 1952, Geodesy, Oxford U. Press.
           Snyder,  J. P., 1987, Map Projections - A Working Manual, U.S. Geologi-
           cal Survey Prof. Paper 1395.
           Vanicek, P. and Krakiwsky, E, 1982, Geodesy - The Concepts,  North-Hol-
           land Publ., ISBN: 0 444 86149 1.

    GMT4.0                            1 Oct 2004                     MAPPROJECT(l)