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)

Man(1) output converted with man2html