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)

Man(1) output converted with man2html