mapproject(1) GMT mapproject(1)
NAME
mapproject - Do forward and inverse map transformations, datum conver-
sions 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 stan-
dard input] and computes (x,y) coordinates using the specified map pro-
jection 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. Addi-
tional data fields are permitted after the first 2 columns which must
have (longitude,latitude) or (x,y). See option -: on how to read (lati-
tude,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 a|)
Select map projection.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more a|)
Specify the region of interest. Special case for the UTM projec-
tion: 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 geodet-
ic 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 cen-
ter [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 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[,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 incremen-
tal distances between successive points, or append both modi-
fiers 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 com-
puted), 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 a|)
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 dis-
tance 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 a|)
Select native binary input. [Default is 2 input columns].
-bo[ncols][type] (more a|)
Select native binary output. [Default is same as input].
-d[i|o]nodata (more a|)
Replace input columns that equal nodata with NaN and do the
reverse on output.
-e[~]^<i>apattern^<i>a | -e[~]/regexp/[i] (more a|)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more a|)
Specify data types of input and/or output columns.
-g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more a|)
Determine data gaps and line breaks.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more a|)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,^<i>a|] (more a|)
Select input columns and transformations (0 is first column).
-ocols[,a|] (more a|)
Select output columns (0 is first column).
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more a|)
Select perspective view.
-s[cols][a|r] (more a|)
Set handling of NaN records.
-:[i|o] (more a|)
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 explana-
tion 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 aFlat Eartha 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 FOR-
MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val-
ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for-
mat 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 set-
ting.
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 Mer-
cator 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) 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.
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 Con-
formal 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 Lambertas 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, Snyderas 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. (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(1), gmt.conf(5), gmtvector(1), project(1)
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.
COPYRIGHT
2017, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
5.4.2 Jun 24, 2017 mapproject(1)
gmt5 5.4.2 - Generated Thu Jun 29 14:05:35 CDT 2017