NAME
mapproject - Forward and Inverse map transformation of 2-D
coordinates
SYNOPSIS
mapproject infiles -Jparameters -Rwest/east/south/north[r] [
- C ] [ -F[k|m] ] [ -H ] [ -I ] [ -M[flag] ] [ -S ] [ -V ] [
-: ]
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, lati-
tude) 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
inch, 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, respec-
tively):
CYLINDRICAL PROJECTIONS:
-Jclon0/lat0/scale or -JClon0/lat0/width (Cassini)
Give projection center and scale (1:xxxx or
inch/degree).
-Jmparameters (Mercator [C]). Specify one of:
-Jmscale or -JMwidth
Give scale along equator (1:xxxx or
inch/degree).
-Jmlon0/lat0/scale or -JMlon0/lat0/width
Give central meridian, standard latitude and
scale along parallel (1:xxxx or inch/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 pro-
jection, and scale.
Give scale along oblique equator (1:xxxx or
inch/degree).
-Jqlon0/scale or -JQlon0/width (Equidistant Cylindrical
Projection (Plate Carree))
Give the central meridian and scale (1:xxxx or
inch/degree).
-Jtlon0/scale or -JTlon0/width (TM - Transverse Merca-
tor [C])
Give the central meridian and scale (1:xxxx or
inch/degree).
- Juzone/scale or - JUzone/width (UTM - Universal
Transverse Mercator [C])
Give the zone number and scale (1:xxxx or
inch/degree).
Use negative zone numbers for the southern hemi-
sphere.
- Jylon0/lats/scale or - JYlon0/lats/width (Basic
Cylindrical Projections [E])
Give the central meridian, standard parallel, and
scale (1:xxxx or inch/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 inch 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 inch from origin to the oblique latitude lat.
- Jglon0/lat0/scale or - JGlon0/lat0/width (Ortho-
graphic).
lon0/lat0 specifies the projection center.
Give scale as 1:xxxx or radius/lat, where radius
is distance
in inch 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 inch 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 inch/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 inch/degree).
MISCELLANEOUS PROJECTIONS:
-Jhlon0/scale or -JHlon0/width (Hammer [E])
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
-Jilon0/scale or -JIlon0/width (Sinusoidal [E])
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
-Jklon0/scale or -JKlon0/width (Eckert VI [E])
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
-Jnlon0/scale or -JNlon0/width (Robinson)
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
-Jrlon0/scale -JRlon0/width (Winkel Tripel)
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
-Jwlon0/scale or -JWlon0/width (Mollweide [E])
Give the central meridian and scale along equator
(1:xxxx or inch/degree).
NON-GEOGRAPHICAL PROJECTIONS:
-Jpscale or - JPwidth (Linear projection for polar
(theta,r) coordinates)
Give scale in inch/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 inch/x-unit and y-scale in inch/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 inch. 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. 12 commonly used ellipsoids and a
spheroid are currently supported, and users may also
specify their own ellipsoid parameters (see man gmtde-
faults 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 pro-
jection center [Default is lower left corner].
-F Force 1:1 scaling, i.e., input data is in actual pro-
jected meters. Append k to get projected km, or m to
get miles.
-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. Segments are separated by a
record whose first character is flag. [Default is
'>'].
-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)]
EXAMPLES
To transform a file with (longitude,latitude) into (x,y)
positions in inch on a Mercator grid for a given scale, run
mapproject lonlatfile -R20/50/12/25 -Jm0.25 > xyfile
To transform several files with (latitude,longitude) into
(x,y) positions in inch on a Transverse Mercator grid (cen-
tral 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 >
tmfile.xy
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 lower-
most 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 digi-
tizing in order to have the inverse transformation work
correctly, or alternatively, use awk to scale and shift the
(x,y) values before transforming.
SEE ALSO
gmtdefaults, gmt, project
REFERENCES
Wessel, P., and W. H. F. Smith, 1995, The Generic Mapping
Tools (GMT) version 3.0 Technical Reference & Cookbook,
SOEST/NOAA.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released, EOS Trans. AGU, 76, p. 329.
Wessel, P., and W. H. F. Smith, 1995, New Version of the
Generic Mapping Tools Released,
http://www.agu.org/eos_elec/95154e.html, Copyright 1995 by
the American Geophysical Union.
Wessel, P., and W. H. F. Smith, 1991, Free Software Helps
Map and Display Data, EOS Trans. AGU, 72, p. 441.
Snyder, J. P., 1987, Map Projections - A Working Manual,
U.S. Geological Survey Prof. Paper 1395.