1MAPPROJECT(1) GMT MAPPROJECT(1)
2
6 mapproject - Do forward and inverse map transformations, datum conver‐
7 sions and geodesy
8
10 mapproject [ tables ] -Jparameters
11 -Rregion [ -Ab|B|f|F|o|O[lon0/lat0][+v] ] [ -C[dx/dy] ] [ -Dc|i|p ]
12 [ -E[datum] ] [ -F[unit] ] [ -G[lon0/lat0][+a][+i][+u[+|-]unit][+v]
13 ] [ -I ] [ -Lline.xy[+u[+|-]unit][+p] ] [ -N[a|c|g|m] ] [ -Q[d|e ]
14 [ -S ] [ -T[h]from[/to] ] [ -V[level] ] [ -W[w|h] ] [
15 -Z[speed][+a][+i][+f][+tepoch] ] [ -bbinary ] [ -dnodata ] [ -eregexp ]
16 [ -fflags ] [ -ggaps ] [ -hheaders ] [ -iflags ] [ -oflags ] [ -pflags
17 ] [ -sflags ] [ -:[i|o] ]
18 Note: No space is allowed between the option flag and the associated
20 arguments.
21
23 mapproject reads (longitude, latitude) positions from tables [or stan‐
24 dard input] and computes (x,y) coordinates using the specified map pro‐
25 jection and scales. Optionally, it can read (x,y) positions and compute
26 (longitude, latitude) values doing the inverse transformation. This
27 can be used to transform linear (x,y) points obtained by digitizing a
28 map of known projection to geographical coordinates. May also calculate
29 distances along track, to a fixed point, or closest approach to a line.
30 Alternatively, can be used to perform various datum conversions. Addi‐
31 tional data fields are permitted after the first 2 columns which must
32 have (longitude,latitude) or (x,y). See option -: on how to read (lati‐
33 tude,longitude) files. Finally, mapproject can compute a variety of
34 auxiliary output data from input coordinates that make up a track.
35 Items like azimuth, distances, distances to other lines, and
36 travel-times along lines can all be computed by using one or more of
37 the options -A, -G, -L, and -Z.
38
40 -Jparameters (more ...)
41 Select map projection.
42 -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
44 Specify the region of interest. Special case for the UTM projec‐
45 tion: If -C is used and -R is not given then the region is set
46 to coincide with the given UTM zone so as to preserve the full
47 ellipsoidal solution (See RESTRICTIONS for more information).
48
50 table One or more ASCII (or binary, see -bi[ncols][type]) data table
51 file(s) holding a number of data columns. If no tables are given
52 then we read from standard input.
53 -Ab|B|f|F|o|O[lon0/lat0][+v]
55 Calculate azimuth along track or to the optional fixed point set
56 with lon0/lat0. -Af calculates the (forward) azimuth to each
57 data point. Use -Ab to get back-azimuth from data points to
58 fixed point. Use -Ao to get orientations (-90/90) rather than
59 azimuths (0/360). Upper case F, B or O will convert from geodet‐
60 ic to geocentric latitudes and estimate azimuth of geodesics
61 (assuming the current ellipsoid is not a sphere). If no fixed
62 point is given then we compute the azimuth (or back-azimuth)
63 from the previous point. Alternatively, append +v to obtain a
64 variable 2nd point (lon0/lat0) via columns 3-4 in the input
65 file.
66 -C[dx/dy]
68 Set center of projected coordinates to be at map projection cen‐
69 ter [Default is lower left corner]. Optionally, add offsets in
70 the projected units to be added (or subtracted when -I is set)
71 to (from) the projected coordinates, such as false eastings and
72 northings for particular projection zones [0/0]. The unit used
73 for the offsets is the plot distance unit in effect (see
74 PROJ_LENGTH_UNIT) unless -F is used, in which case the offsets
75 are in meters.
76 -Dc|i|p
78 Temporarily override PROJ_LENGTH_UNIT and use c (cm), i (inch),
79 or p (points) instead. Cannot be used with -F.
80 -E[datum]
82 Convert from geodetic (lon, lat, height) to Earth Centered Earth
83 Fixed (ECEF) (x,y,z) coordinates (add -I for the inverse conver‐
84 sion). Append datum ID (see -Qd) or give ellipsoid:dx,dy,dz
85 where ellipsoid may be an ellipsoid ID (see -Qe) or given as
86 a[,inv_f], where a is the semi-major axis and inv_f is the
87 inverse flattening (0 if omitted). If datum is - or not given we
88 assume WGS-84.
89 -F[unit]
91 Force 1:1 scaling, i.e., output (or input, see -I) data are in
92 actual projected meters. To specify other units, append the
93 desired unit (see UNITS). Without -F, the output (or input, see
94 -I) are in the units specified by PROJ_LENGTH_UNIT (but see -D).
95 -G[lon0/lat0][+a][+i][+u[+|-]unit][+v]
97 Calculate distances along track or to the optional fixed point
98 set with -Glon0/lat0. Append the distance unit with +u (see
99 UNITS for available units and how distances are computed),
100 including c (Cartesian distance using input coordinates) or C
101 (Cartesian distance using projected coordinates). The C unit
102 requires -R and -J to be set. When no fixed point is given we
103 calculate accumulative distances [or by adding +a] along the
104 track defined by the input points. Append +i to obtain incremen‐
105 tal distances between successive points, or append both modi‐
106 fiers to get both distance measurements. Alternatively, append
107 +v to obtain a variable 2nd point (lon0/lat0) via columns 3-4 in
108 the input file.
109 -I Do the Inverse transformation, i.e., get (longitude,latitude)
111 from (x,y) data.
112 -Lline.xy[+u[+|-]unit][+p]
114 Determine the shortest distance from the input data points to
115 the line(s) given in the ASCII multisegment file line.xy. The
116 distance and the coordinates of the nearest point will be
117 appended to the output as three new columns. Append the distance
118 unit (see UNITS for available units and how distances are com‐
119 puted), including c (Cartesian distance using input coordinates)
120 or C (Cartesian distance using projected coordinates). The C
121 unit requires -R and -J to be set. Finally, append +p to report
122 the line segment id and the fractional point number instead of
123 lon/lat of the nearest point.
124 -N[a|c|g|m]
126 Convert from geodetic latitudes (using the current ellipsoid;
127 see PROJ_ELLIPSOID) to one of four different auxiliary latitudes
128 (longitudes are unaffected). Choose from authalic, conformal,
129 geocentric, and meridional latitudes [geocentric]. Use -I to
130 convert from auxiliary latitudes to geodetic latitudes.
131 -Q[d|e List all projection parameters. To only list datums, use -Qd. To
133 only list ellipsoids, use -Qe.
134 -S Suppress points that fall outside the region.
136 -T[h]from[/to]
138 Coordinate conversions between datums from and to using the
139 standard Molodensky transformation. Use -Th if 3rd input column
140 has height above ellipsoid [Default assumes height = 0, i.e., on
141 the ellipsoid]. Specify datums using the datum ID (see -Qd) or
142 give ellipsoid:dx,dy,dz where ellipsoid may be an ellipsoid ID
143 (see -Qe) or given as a[,inv_f], where a is the semi-major axis
144 and inv_f is the inverse flattening (0 if omitted). If datum is
145 - or not given we assume WGS-84. -T may be used in conjunction
146 with -R -J to change the datum before coordinate projection (add
147 -I to apply the datum conversion after the inverse projection).
148 Make sure that the PROJ_ELLIPSOID setting is correct for your
149 case.
150 -V[level] (more ...)
152 Select verbosity level [c].
153 -W[w|h]
155 Prints map width and height on standard output. No input files
156 are read. To only output the width or the height, append w or
157 h, respectively. The units of the dimensions may be changed via
158 -D.
159 -Z[speed][+a][+i][+f][+tepoch]
161 Calculate travel times along track as specified with -G. Append
162 a constant speed unit; if missing we expect to read a variable
163 speed from column 3. The speed is expected to be in the dis‐
164 tance units set via -G per time unit controlled by TIME_UNIT
165 [m/s]. Append +i to output incremental travel times between
166 successive points, +a to obtain accumulated travel times, or
167 both to get both kinds of time information. Use +f to format
168 the accumulated (elapsed) travel time according to the ISO 8601
169 convention. As for the number of decimals used to represent
170 seconds we consult the FORMAT_CLOCK_OUT setting. Finally, append
171 +tepoch to report absolute times (ETA) for successive points.
172 -bi[ncols][t] (more ...)
174 Select native binary input. [Default is 2 input columns].
175 -bo[ncols][type] (more ...)
177 Select native binary output. [Default is same as input].
178 -d[i|o]nodata (more ...)
180 Replace input columns that equal nodata with NaN and do the
181 reverse on output.
182 -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
184 Only accept data records that match the given pattern.
185 -f[i|o]colinfo (more ...)
187 Specify data types of input and/or output columns.
188 -g[a]x|y|d|X|Y|D|[col]z[+|-]gap[u] (more ...)
190 Determine data gaps and line breaks.
191 -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
193 Skip or produce header record(s).
194 -icols[+l][+sscale][+ooffset][,...] (more ...)
196 Select input columns and transformations (0 is first column).
197 -ocols[,...] (more ...)
199 Select output columns (0 is first column).
200 -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
202 Select perspective view.
203 -s[cols][a|r] (more ...)
205 Set handling of NaN records.
206 -:[i|o] (more ...)
208 Swap 1st and 2nd column on input and/or output.
209 -^ or just -
211 Print a short message about the syntax of the command, then
212 exits (NOTE: on Windows just use -).
213 -+ or just +
215 Print an extensive usage (help) message, including the explana‐
216 tion of any module-specific option (but not the GMT common
217 options), then exits.
218 -? or no arguments
220 Print a complete usage (help) message, including the explanation
221 of all options, then exits.
222
224 For map distance unit, append unit d for arc degree, m for arc minute,
225 and s for arc second, or e for meter [Default], f for foot, k for km, M
226 for statute mile, n for nautical mile, and u for US survey foot. By
227 default we compute such distances using a spherical approximation with
228 great circles. Prepend - to a distance (or the unit is no distance is
229 given) to perform "Flat Earth" calculations (quicker but less accurate)
230 or prepend + to perform exact geodesic calculations (slower but more
231 accurate).
232
234 The ASCII output formats of numerical data are controlled by parameters
235 in your gmt.conf file. Longitude and latitude are formatted according
236 to FORMAT_GEO_OUT, absolute time is under the control of FOR‐
237 MAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point val‐
238 ues are formatted according to FORMAT_FLOAT_OUT. Be aware that the for‐
239 mat in effect can lead to loss of precision in ASCII output, which can
240 lead to various problems downstream. If you find the output is not
241 written with enough precision, consider switching to binary output (-bo
242 if available) or specify more decimals using the FORMAT_FLOAT_OUT set‐
243 ting.
244
246 To convert UTM coordinates in meters to geographic locations, given a
247 file utm.txt and knowing the UTM zone (and zone or hemisphere), try
248 gmt mapproject utm.txt -Ju+11/1:1 -C -I -F
250 To transform a file with (longitude,latitude) into (x,y) positions in
252 cm on a Mercator grid for a given scale of 0.5 cm per degree, run
253 gmt mapproject lonlatfile -R20/50/12/25 -Jm0.5c > xyfile
255 To transform several 2-column, binary, double precision files with
257 (latitude,longitude) into (x,y) positions in inch on a Transverse Mer‐
258 cator grid (central longitude 75W) for scale = 1:500000 and suppress
259 those points that would fall outside the map area, run
260 gmt mapproject tracks.* -R-80/-70/20/40 -Jt-75/1:500000 -: -S -Di -bo -bi2 > tmfile.b
262 To convert the geodetic coordinates (lon, lat, height) in the file
264 old.dat from the NAD27 CONUS datum (Datum ID 131 which uses the
265 Clarke-1866 ellipsoid) to WGS 84, run
266 gmt mapproject old.dat -Th131 > new.dat
268 To compute the closest distance (in km) between each point in the input
270 file quakes.dat and the line segments given in the multisegment ASCII
271 file coastline.xy, run
272 gmt mapproject quakes.dat -Lcoastline.xy+uk > quake_dist.dat
274 Given a file with longitude and latitude, compute both incremental and
276 accumulated distance along track, and estimate travel times assuming a
277 fixed speed of 12 knots. We do this with
278 gmt mapproject track.txt -Gn+a+i -Z12+a --TIME_UNIT=h > elapsed_time.txt
280 where TIME_UNIT is set to hour so that the speed is measured in nm (set
282 by -G) per hour (set by TIME_UNIT). Elapsed times will be reported in
283 hours (unless +f is added to -Z for ISO elapsed time).
284
286 The rectangular input region set with -R will in general be mapped into
287 a non-rectangular grid. Unless -C is set, the leftmost point on this
288 grid has xvalue = 0.0, and the lowermost point will have yvalue = 0.0.
289 Thus, before you digitize a map, run the extreme map coordinates
290 through mapproject using the appropriate scale and see what (x,y) val‐
291 ues they are mapped onto. Use these values when setting up for digitiz‐
292 ing in order to have the inverse transformation work correctly, or
293 alternatively, use awk to scale and shift the (x,y) values before
294 transforming.
295 For some projection, a spherical solution may be used despite the user
297 having selected an ellipsoid. This occurs when the users -R setting
298 implies a region that exceeds the domain in which the ellipsoidal
299 series expansions are valid. These are the conditions: (1) Lambert Con‐
300 formal Conic (-JL)and Albers Equal-Area (-JB) will use the spherical
301 solution when the map scale exceeds 1.0E7. (2) Transverse Mercator
302 (-JT) and UTM (-JU) will will use the spherical solution when either
303 the west or east boundary given in -R is more than 10 degrees from the
304 central meridian, and (3) same for Cassini (-JC) but with a limit of
305 only 4 degrees.
306
308 GMT will use ellipsoidal formulae if they are implemented and the user
309 have selected an ellipsoid as the reference shape (see PROJ_ELLIPSOID).
310 The user needs to be aware of a few potential pitfalls: (1) For some
311 projections, such as Transverse Mercator, Albers, and Lambert's confor‐
312 mal conic we use the ellipsoidal expressions when the areas mapped are
313 small, and switch to the spherical expressions (and substituting the
314 appropriate auxiliary latitudes) for larger maps. The ellipsoidal for‐
315 mulae are used as follows: (a) Transverse Mercator: When all points are
316 within 10 degrees of central meridian, (b) Conic projections when lon‐
317 gitudinal range is less than 90 degrees, (c) Cassini projection when
318 all points are within 4 degrees of central meridian. (2) When you are
319 trying to match some historical data (e.g., coordinates obtained with a
320 certain projection and a certain reference ellipsoid) you may find that
321 GMT gives results that are slightly different. One likely source of
322 this mismatch is that older calculations often used less significant
323 digits. For instance, Snyder's examples often use the Clarke 1866
324 ellipsoid (defined by him as having a flattening f = 1/294.98). From f
325 we get the eccentricity squared to be 0.00676862818 (this is what GMT
326 uses), while Snyder rounds off and uses 0.00676866. This difference can
327 give discrepancies of several tens of cm. If you need to reproduce
328 coordinates projected with this slightly different eccentricity, you
329 should specify your own ellipsoid with the same parameters as Clarke
330 1866, but with f = 1/294.97861076. Also, be aware that older data may
331 be referenced to different datums, and unless you know which datum was
332 used and convert all data to a common datum you may experience mis‐
333 matches of tens to hundreds of meters. (3) Finally, be aware that
334 PROJ_SCALE_FACTOR have certain default values for some projections so
335 you may have to override the setting in order to match results produced
336 with other settings.
337
339 The production order for the geodetic and temporal columns produced by
340 the options -A, -G, -L, and -Z is fixed and follows the alphabetical
341 order of the options. Hence, the order these options appear on the
342 command line is irrelevant. The actual output order can of course be
343 modulated via -o.
344
346 gmt, gmt.conf, gmtvector, project
347
349 Bomford, G., 1952, Geodesy, Oxford U. Press.
350 Snyder, J. P., 1987, Map Projections - A Working Manual, U.S. Geologi‐
352 cal Survey Prof. Paper 1395.
353 Vanicek, P. and Krakiwsky, E, 1982, Geodesy - The Concepts, North-Hol‐
355 land Publ., ISBN: 0 444 86149 1.
356
358 2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
3595.4.5 Feb 24, 2019 MAPPROJECT(1)