Provided by: gmt-common_5.4.5+dfsg-2_all 
NAME
mapproject - Do forward and inverse map transformations, datum conversions and geodesy
SYNOPSIS
mapproject [ tables ] -Jparameters
-Rregion [ -Ab|B|f|F|o|O[lon0/lat0][+v] ] [ -C[dx/dy] ] [ -Dc|i|p ] [ -E[datum] ] [
-F[unit] ] [ -G[lon0/lat0][+a][+i][+u[+|-]unit][+v] ] [ -I ] [
-Lline.xy[+u[+|-]unit][+p] ] [ -N[a|c|g|m] ] [ -Q[d|e ] [ -S ] [ -T[h]from[/to] ] [
-V[level] ] [ -W[w|h] ] [ -Z[speed][+a][+i][+f][+tepoch] ] [ -bbinary ] [ -dnodata ] [
-eregexp ] [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [ -pflags ] [
-sflags ] [ -:[i|o] ]
Note: No space is allowed between the option flag and the associated arguments.
DESCRIPTION
mapproject reads (longitude, latitude) positions from tables [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. May also calculate distances along
track, to a fixed point, or closest approach to a line. Alternatively, 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. Finally, mapproject can compute a variety of auxiliary output
data from input coordinates that make up a track. Items like azimuth, distances,
distances to other lines, and travel-times along lines can all be computed by using one or
more of the options -A, -G, -L, and -Z.
REQUIRED ARGUMENTS
-Jparameters (more ...)
Select map projection.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
Specify the region of interest. Special case for the UTM projection: If -C is used
and -R is not given then the region is set to coincide with the given UTM zone so
as to preserve the full ellipsoidal solution (See RESTRICTIONS for more
information).
OPTIONAL ARGUMENTS
table One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a
number of data columns. If no tables are given then we read from standard input.
-Ab|B|f|F|o|O[lon0/lat0][+v]
Calculate azimuth along track or to the optional fixed point set with lon0/lat0.
-Af calculates the (forward) azimuth to each data point. Use -Ab to get
back-azimuth from data points to fixed point. Use -Ao to get orientations (-90/90)
rather than azimuths (0/360). Upper case F, B or O will convert from geodetic to
geocentric latitudes and estimate azimuth of geodesics (assuming the current
ellipsoid is not a sphere). If no fixed point is given then we compute the azimuth
(or back-azimuth) from the previous point. Alternatively, append +v to obtain a
variable 2nd point (lon0/lat0) via columns 3-4 in the input file.
-C[dx/dy]
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 PROJ_LENGTH_UNIT) unless -F is
used, in which case the offsets are in meters.
-Dc|i|p
Temporarily override PROJ_LENGTH_UNIT and use c (cm), i (inch), or p (points)
instead. Cannot be used with -F.
-E[datum]
Convert from geodetic (lon, lat, height) to Earth Centered Earth Fixed (ECEF)
(x,y,z) coordinates (add -I for the inverse conversion). Append datum ID (see -Qd)
or give ellipsoid:dx,dy,dz where ellipsoid may be an ellipsoid ID (see -Qe) or
given as a[,inv_f], where a is the semi-major axis and inv_f is the inverse
flattening (0 if omitted). If datum is - or not given we assume WGS-84.
-F[unit]
Force 1:1 scaling, i.e., output (or input, see -I) data are in actual projected
meters. To specify other units, append the desired unit (see UNITS). Without -F,
the output (or input, see -I) are in the units specified by PROJ_LENGTH_UNIT (but
see -D).
-G[lon0/lat0][+a][+i][+u[+|-]unit][+v]
Calculate distances along track or to the optional fixed point set with
-Glon0/lat0. Append the distance unit with +u (see UNITS for available units and
how distances are computed), including c (Cartesian distance using input
coordinates) or C (Cartesian distance using projected coordinates). The C unit
requires -R and -J to be set. When no fixed point is given we calculate
accumulative distances [or by adding +a] along the track defined by the input
points. Append +i to obtain incremental distances between successive points, or
append both modifiers to get both distance measurements. Alternatively, append +v
to obtain a variable 2nd point (lon0/lat0) via columns 3-4 in the input file.
-I Do the Inverse transformation, i.e., get (longitude,latitude) from (x,y) data.
-Lline.xy[+u[+|-]unit][+p]
Determine the shortest distance from the input data points to the line(s) given in
the ASCII multisegment file line.xy. The distance and the coordinates of the
nearest point will be appended to the output as three new columns. Append the
distance unit (see UNITS for available units and how distances are computed),
including c (Cartesian distance using input coordinates) or C (Cartesian distance
using projected coordinates). The C unit requires -R and -J to be set. Finally,
append +p to report the line segment id and the fractional point number instead of
lon/lat of the nearest point.
-N[a|c|g|m]
Convert from geodetic latitudes (using the current ellipsoid; see PROJ_ELLIPSOID)
to one of four different auxiliary latitudes (longitudes are unaffected). Choose
from authalic, conformal, geocentric, and meridional latitudes [geocentric]. Use -I
to convert from auxiliary latitudes to geodetic latitudes.
-Q[d|e 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[h]from[/to]
Coordinate conversions between datums from and to using the standard Molodensky
transformation. Use -Th if 3rd input column has height above ellipsoid [Default
assumes height = 0, i.e., on the ellipsoid]. Specify datums using the datum ID (see
-Qd) or give ellipsoid:dx,dy,dz where ellipsoid may be an ellipsoid ID (see -Qe) or
given as a[,inv_f], where a is the semi-major axis and inv_f is the inverse
flattening (0 if omitted). If datum is - or not given we assume 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 PROJ_ELLIPSOID setting is correct for your case.
-V[level] (more ...)
Select verbosity level [c].
-W[w|h]
Prints map width and height on standard output. No input files are read. To only
output the width or the height, append w or h, respectively. The units of the
dimensions may be changed via -D.
-Z[speed][+a][+i][+f][+tepoch]
Calculate travel times along track as specified with -G. Append a constant speed
unit; if missing we expect to read a variable speed from column 3. The speed is
expected to be in the distance units set via -G per time unit controlled by
TIME_UNIT [m/s]. Append +i to output incremental travel times between successive
points, +a to obtain accumulated travel times, or both to get both kinds of time
information. Use +f to format the accumulated (elapsed) travel time according to
the ISO 8601 convention. As for the number of decimals used to represent seconds
we consult the FORMAT_CLOCK_OUT setting. Finally, append +tepoch to report absolute
times (ETA) for successive points.
-bi[ncols][t] (more ...)
Select native binary input. [Default is 2 input columns].
-bo[ncols][type] (more ...)
Select native binary output. [Default is same as input].
-d[i|o]nodata (more ...)
Replace input columns that equal nodata with NaN and do the reverse on output.
-e[~]"pattern" | -e[~]/regexp/[i] (more ...)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,...] (more ...)
Select input columns and transformations (0 is first column).
-ocols[,...] (more ...)
Select output columns (0 is first column).
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
Select perspective view.
-s[cols][a|r] (more ...)
Set handling of NaN records.
-:[i|o] (more ...)
Swap 1st and 2nd column on input and/or output.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows
just use -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any
module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options,
then exits.
UNITS
For map distance unit, append unit d for arc degree, m for arc minute, and s for arc
second, or e for meter [Default], f for foot, k for km, M for statute mile, n for nautical
mile, and u for US survey foot. By default we compute such distances using a spherical
approximation with great circles. Prepend - to a distance (or the unit is no distance is
given) to perform "Flat Earth" calculations (quicker but less accurate) or prepend + to
perform exact geodesic calculations (slower but more accurate).
ASCII FORMAT PRECISION
The ASCII output formats of numerical data are controlled by parameters in your gmt.conf
file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, absolute time is
under the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point
values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can
lead to loss of precision in ASCII output, which can lead to various problems downstream.
If you find the output is not written with enough precision, consider switching to binary
output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.
EXAMPLES
To convert UTM coordinates in meters to geographic locations, given a file utm.txt and
knowing the UTM zone (and zone or hemisphere), try
gmt mapproject utm.txt -Ju+11/1:1 -C -I -F
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
gmt 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
gmt 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
gmt 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 segments given in the multisegment ASCII file coastline.xy, run
gmt mapproject quakes.dat -Lcoastline.xy+uk > quake_dist.dat
Given a file with longitude and latitude, compute both incremental and accumulated
distance along track, and estimate travel times assuming a fixed speed of 12 knots. We do
this with
gmt mapproject track.txt -Gn+a+i -Z12+a --TIME_UNIT=h > elapsed_time.txt
where TIME_UNIT is set to hour so that the speed is measured in nm (set by -G) per hour
(set by TIME_UNIT). Elapsed times will be reported in hours (unless +f is added to -Z for
ISO elapsed time).
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.
For some projection, a spherical solution may be used despite the user having selected an
ellipsoid. This occurs when the users -R setting implies a region that exceeds the domain
in which the ellipsoidal series expansions are valid. These are the conditions: (1)
Lambert Conformal Conic (-JL)and Albers Equal-Area (-JB) will use the spherical solution
when the map scale exceeds 1.0E7. (2) Transverse Mercator (-JT) and UTM (-JU) will will
use the spherical solution when either the west or east boundary given in -R is more than
10 degrees from the central meridian, and (3) same for Cassini (-JC) but with a limit of
only 4 degrees.
ELLIPSOIDS AND SPHEROIDS
GMT will use ellipsoidal formulae if they are implemented and the user have selected an
ellipsoid as the reference shape (see PROJ_ELLIPSOID). The user needs to be aware of a few
potential pitfalls: (1) For some projections, such as Transverse Mercator, Albers, and
Lambert's conformal 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 formulae are used as 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 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 mismatches of tens to hundreds of
meters. (3) Finally, be aware that PROJ_SCALE_FACTOR have certain default values for some
projections so you may have to override the setting in order to match results produced
with other settings.
OUTPUT ORDER
The production order for the geodetic and temporal columns produced by the options -A, -G,
-L, and -Z is fixed and follows the alphabetical order of the options. Hence, the order
these options appear on the command line is irrelevant. The actual output order can of
course be modulated via -o.
SEE ALSO
gmt, gmt.conf, gmtvector, project
REFERENCES
Bomford, G., 1952, Geodesy, Oxford U. Press.
Snyder, J. P., 1987, Map Projections - A Working Manual, U.S. Geological Survey Prof.
Paper 1395.
Vanicek, P. and Krakiwsky, E, 1982, Geodesy - The Concepts, North-Holland Publ., ISBN: 0
444 86149 1.
COPYRIGHT
2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe