Provided by: gmt-manpages_3.4.4-1_all 
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 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), 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 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 projection, and scale.
Give scale along oblique equator (1:xxxx or UNIT/degree).
-Jqlon0/scale or -JQlon0/width (Equidistant Cylindrical Projection (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 Mercator [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 Projections [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 distance
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 distance
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 center (in degrees, <
90).
Give scale as 1:xxxx or radius/lat, where radius is distance
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 distance
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 .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. Several
GMT parameters can affect the projection: ELLIPSOID, INTERPOLANT, 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 center [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 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)]. 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]
-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 inch 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 -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) 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 can
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(1gmt), gmt(1gmt), project(1gmt)
REFERENCES
Snyder, J. P., 1987, Map Projections - A Working Manual, U.S. Geological Survey Prof.
Paper 1395.
1 Jan 2004 MAPPROJECT(l)