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