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


DESCRIPTION

      mapproject reads (longitude, latitude) positions from infiles [or
      standard input] and computes (x,y) coordinates using the specified map
      projection and scales.  Optionally, 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 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
      (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
           argument(s) supplied as scale(s) is interpreted to be the map
           width (or axis lengths) in cm, else the scale argument(s) is the
           map scale (see its definition for each projection).  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 cm/degree).
           -Jjlon0/scale or -JJlon0/width (Miller Cylindrical Projection)
                Give the central meridian and scale (1:xxxx or cm/degree).
           -Jmparameters (Mercator [C]).  Specify one of:
                -Jmscale or -JMwidth
                     Give scale along equator (1:xxxx or cm/degree).
                -Jmlon0/lat0/scale or -JMlon0/lat0/width
                     Give central meridian, standard latitude and scale
           along parallel (1:xxxx or cm/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 cm/degree).
           -Jqlon0/scale or -JQlon0/width (Equidistant Cylindrical
           Projection (Plate Carree))
                Give the central meridian and scale (1:xxxx or cm/degree).
           -Jtparameters (Transverse Mercator [C]).  Specify one of:
                -Jtlon0/scale or -JTlon0/width
                     Give the central meridian and scale (1:xxxx or
           cm/degree).
                -Jtlon0/lat0/scale or -JTlon0/lat0/width
                     Give projection center and scale (1:xxxx or cm/degree).
           -Juzone/scale or -JUzone/width (UTM - Universal Transverse
           Mercator [C])
                Give the zone number and scale (1:xxxx or cm/degree).
                Use negative zone numbers for the southern hemisphere.
           -Jylon0/lats/scale or -JYlon0/lats/width (Basic Cylindrical
           Projections [E])
                Give the central meridian, standard parallel, and scale
           (1:xxxx or cm/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 cm 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 distance
                in cm 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 center
           (in degrees, < 90).
                Give scale as 1:xxxx or radius/lat, where radius is distance
                in cm 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 distance
                in cm 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 or radius/lat, where radius is distance
                in cm 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 cm/degree).
           -Jdlon0/lat0/lat1/lat2/scale or -JDlon0/lat0/lat1/lat2/width
           (Equidistant)
                Give projection center, two standard parallels, and scale
           (1:xxxx or cm/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 cm/degree).

           MISCELLANEOUS PROJECTIONS:

           -Jhlon0/scale or -JHlon0/width (Hammer [E])
                Give the central meridian and scale along equator (1:xxxx or
           cm/degree).
           -Jilon0/scale or -JIlon0/width (Sinusoidal [E])
                Give the central meridian and scale along equator (1:xxxx or
           cm/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
           cm/degree).
           -Jnlon0/scale or -JNlon0/width (Robinson)
                Give the central meridian and scale along equator (1:xxxx or
           cm/degree).
           -Jrlon0/scale -JRlon0/width (Winkel Tripel)
                Give the central meridian and scale along equator (1:xxxx or
           cm/degree).
           -Jvlon0/scale or -JVlon0/width (Van der Grinten)
                Give the central meridian and scale along equator (1:xxxx or
           cm/degree).
           -Jwlon0/scale or -JWlon0/width (Mollweide [E])
                Give the central meridian and scale along equator (1:xxxx or
           cm/degree).

           NON-GEOGRAPHICAL PROJECTIONS:

           -Jpscale or -JPwidth (Linear projection for polar (theta,r)
           coordinates)
                Give scale in cm/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 cm/x-unit and y-scale in cm/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 d if x and y 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 cm.
           However, you may change this by editing 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.

      -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
           center [Default is lower left corner].

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

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

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


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 cm 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 -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 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
      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 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 gan 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, gmt, project


REFERENCES

      Snyder, J. P., 1987, Map Projections - A Working Manual, U.S.
      Geological Survey Prof. Paper 1395.



























Man(1) output converted with man2html