1GEOCONVERT(1) GeographicLib Utilities GEOCONVERT(1)
2
6 GeoConvert -- convert geographic coordinates
7
9 GeoConvert [ -g | -d | -: | -u | -m | -c ] [ -z zone | -s | -t | -S |
10 -T ] [ -n ] [ -w ] [ -p prec ] [ -l | -a ] [ --comment-delimiter
11 commentdelim ] [ --version | -h | --help ] [ --input-file infile |
12 --input-string instring ] [ --line-separator linesep ] [ --output-file
13 outfile ]
14
16 GeoConvert reads from standard input interpreting each line as a
17 geographic coordinate and prints the coordinate in the format specified
18 by the options on standard output. The input is interpreted in one of
19 three different ways depending on how many space or comma delimited
20 tokens there are on the line. The options -g, -d, -u, and -m govern
21 the format of output. In all cases, the WGS84 model of the earth is
22 used (a = 6378137 m, f = 1/298.257223563).
23 geographic
25 2 tokens (output options -g, -d, or -:) given as latitude longitude
26 using decimal degrees or degrees, minutes, and seconds. Latitude
27 is given first (unless the -w option is given). See "GEOGRAPHIC
28 COORDINATES" for a description of the format. For example, the
29 following are all equivalent
30 33.3 44.4
32 E44.4 N33.3
33 33d18'N 44d24'E
34 44d24 33d18N
35 33:18 +44:24
36 UTM/UPS
38 3 tokens (output option -u) given as zone+hemisphere easting
39 northing or easting northing zone+hemisphere, where hemisphere is
40 either n (or north) or s (or south). The zone is absent for a UPS
41 specification. For example,
42 38n 444140.54 3684706.36
44 444140.54 3684706.36 38n
45 s 2173854.98 2985980.58
46 2173854.98 2985980.58 s
47 MRGS
49 1 token (output option -m) is used to specify the center of an MGRS
50 grid square. For example,
51 38SMB4484
53 38SMB44140847064
54
56 -g output latitude and longitude using decimal degrees. Default
57 output mode.
58 -d output latitude and longitude using degrees, minutes, and seconds
60 (DMS).
61 -: like -d, except use : as a separator instead of the d, ', and "
63 delimiters.
64 -u output UTM or UPS.
66 -m output MGRS.
68 -c output meridian convergence and scale for the corresponding UTM or
70 UPS projection. The meridian convergence is the bearing of grid
71 north given as degrees clockwise from true north.
72 -z zone
74 set the zone to zone for output. Use either 0 < zone <= 60 for a
75 UTM zone or zone = 0 for UPS. Alternatively use a zone+hemisphere
76 designation, e.g., 38n. See "ZONE".
77 -s use the standard UPS and UTM zones.
79 -t similar to -s but forces UPS regions to the closest UTM zone.
81 -S or -T
83 behave the same as -s and -t, respectively, until the first legal
84 conversion is performed. For subsequent points, the zone and
85 hemisphere of that conversion are used. This enables a sequence of
86 points to be converted into UTM or UPS using a consistent
87 coordinate system.
88 -n on input, MGRS coordinates refer to the south-west corner of the
90 MGRS square instead of the center; see "MGRS".
91 -w toggle the longitude first flag (it starts off); if the flag is on,
93 then on input and output, longitude precedes latitude (except that,
94 on input, this can be overridden by a hemisphere designator, N, S,
95 E, W).
96 -p prec
98 set the output precision to prec (default 0); prec is the precision
99 relative to 1 m. See "PRECISION".
100 -l on output, UTM/UPS uses the long forms north and south to designate
102 the hemisphere instead of n or s.
103 -a on output, UTM/UPS uses the abbreviations n and s to designate the
105 hemisphere instead of north or south; this is the default
106 representation.
107 --comment-delimiter commentdelim
109 set the comment delimiter to commentdelim (e.g., "#" or "//"). If
110 set, the input lines will be scanned for this delimiter and, if
111 found, the delimiter and the rest of the line will be removed prior
112 to processing and subsequently appended to the output line
113 (separated by a space).
114 --version
116 print version and exit.
117 -h print usage and exit.
119 --help
121 print full documentation and exit.
122 --input-file infile
124 read input from the file infile instead of from standard input; a
125 file name of "-" stands for standard input.
126 --input-string instring
128 read input from the string instring instead of from standard input.
129 All occurrences of the line separator character (default is a
130 semicolon) in instring are converted to newlines before the reading
131 begins.
132 --line-separator linesep
134 set the line separator character to linesep. By default this is a
135 semicolon.
136 --output-file outfile
138 write output to the file outfile instead of to standard output; a
139 file name of "-" stands for standard output.
140
142 prec gives precision of the output with prec = 0 giving 1 m precision,
143 prec = 3 giving 1 mm precision, etc. prec is the number of digits
144 after the decimal point for UTM/UPS. For MGRS, The number of digits
145 per coordinate is 5 + prec; prec = -6 results in just the grid zone.
146 For decimal degrees, the number of digits after the decimal point is 5
147 + prec. For DMS (degree, minute, seconds) output, the number of digits
148 after the decimal point in the seconds components is 1 + prec; if this
149 is negative then use minutes (prec = -2 or -3) or degrees (prec <= -4)
150 as the least significant component. Print convergence, resp. scale,
151 with 5 + prec, resp. 7 + prec, digits after the decimal point. The
152 minimum value of prec is -5 (-6 for MGRS) and the maximum is 9 for
153 UTM/UPS, 9 for decimal degrees, 10 for DMS, 6 for MGRS, and 8 for
154 convergence and scale.
155
157 The utility accepts geographic coordinates, latitude and longitude, in
158 a number of common formats. Latitude precedes longitude, unless the -w
159 option is given which switches this convention. On input, either
160 coordinate may be given first by appending or prepending N or S to the
161 latitude and E or W to the longitude. These hemisphere designators
162 carry an implied sign, positive for N and E and negative for S and W.
163 This sign multiplies any +/- sign prefixing the coordinate. The
164 coordinates may be given as decimal degree or as degrees, minutes, and
165 seconds. d, ', and " are used to denote degrees, minutes, and seconds,
166 with the least significant designator optional. (See "QUOTING" for how
167 to quote the characters ' and " when entering coordinates on the
168 command line.) Alternatively, : (colon) may be used to separate the
169 various components. Only the final component of coordinate can include
170 a decimal point, and the minutes and seconds components must be less
171 than 60.
172 It is also possible to carry out addition or subtraction operations in
174 geographic coordinates. If the coordinate includes interior signs
175 (i.e., not at the beginning or immediately after an initial hemisphere
176 designator), then the coordinate is split before such signs; the pieces
177 are parsed separately and the results summed. For example the point
178 15" east of 39N 70W is
179 39N 70W+0:0:15E
181 WARNING: "Exponential" notation is not recognized for geographic
183 coordinates. Thus 7.0E1 is illegal, while 7.0E+1 is parsed as (7.0E) +
184 (+1), yielding the same result as 8.0E.
185 Various unicode characters (encoded with UTF-8) may also be used to
187 denote degrees, minutes, and seconds, e.g., the degree, prime, and
188 double prime symbols; in addition two single quotes can be used to
189 represent ".
190 The other GeographicLib utilities use the same rules for interpreting
192 geographic coordinates; in addition, azimuths and arc lengths are
193 interpreted the same way.
194
196 Unfortunately the characters ' and " have special meanings in many
197 shells and have to be entered with care. However note (1) that the
198 trailing designator is optional and that (2) you can use colons as a
199 separator character. Thus 10d20' can be entered as 10d20 or 10:20 and
200 10d20'30" can be entered as 10:20:30.
201 Unix shells (sh, bash, tsch)
203 The characters ' and " can be quoted by preceding them with a \
204 (backslash); or you can quote a string containing ' with a pair of
205 "s. The two alternatives are illustrated by
206 echo 10d20\'30\" "20d30'40" | GeoConvert -d -p -1
208 => 10d20'30"N 020d30'40"E
209 Quoting of command line arguments is similar
211 GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
213 => 10d20'30"N 020d30'40"E
214 Windows command shell (cmd)
216 The ' character needs no quoting; the " character can either be
217 quoted by a ^ or can be represented by typing ' twice. (This
218 quoting is usually unnecessary because the trailing designator can
219 be omitted.) Thus
220 echo 10d20'30'' 20d30'40 | GeoConvert -d -p -1
222 => 10d20'30"N 020d30'40"E
223 Use \ to quote the " character in a command line argument
225 GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
227 => 10d20'30"N 020d30'40"E
228 Input from a file
230 No quoting need be done if the input from a file. Thus each line
231 of the file "input.txt" should just contain the plain coordinates.
232 GeoConvert -d -p -1 < input.txt
234
236 MGRS coordinates represent a square patch of the earth, thus
237 "38SMB4488" is in zone "38n" with 444km <= easting < 445km and 3688km
238 <= northing < 3689km. Consistent with this representation, coordinates
239 are truncated (instead of rounded) to the requested precision. When an
240 MGRS coordinate is provided as input, GeoConvert treats this as a
241 representative point within the square. By default, this
242 representative point is the center of the square ("38n 444500 3688500"
243 in the example above). (This leads to a stable conversion between MGRS
244 and geographic coordinates.) However, if the -n option is given then
245 the south-west corner of the square is returned instead ("38n 444000
246 3688000" in the example above).
247
249 If the input is geographic, GeoConvert uses the standard rules of
250 selecting UTM vs UPS and for assigning the UTM zone (with the Norway
251 and Svalbard exceptions). If the input is UTM/UPS or MGRS, then the
252 choice between UTM and UPS and the UTM zone mirrors the input. The -z
253 zone, -s, and -t options allow these rules to be overridden with zone =
254 0 being used to indicate UPS. For example, the point
255 79.9S 6.1E
257 corresponds to possible MGRS coordinates
259 32CMS4324728161 (standard UTM zone = 32)
261 31CEM6066227959 (neighboring UTM zone = 31)
262 BBZ1945517770 (neighboring UPS zone)
263 then
265 echo 79.9S 6.1E | GeoConvert -p -3 -m => 32CMS4328
267 echo 31CEM6066227959 | GeoConvert -p -3 -m => 31CEM6027
268 echo 31CEM6066227959 | GeoConvert -p -3 -m -s => 32CMS4328
269 echo 31CEM6066227959 | GeoConvert -p -3 -m -z 0 => BBZ1917
270 Is zone is specified with a hemisphere, then this is honored when
272 printing UTM coordinates:
273 echo -1 3 | GeoConvert -u => 31s 500000 9889470
275 echo -1 3 | GeoConvert -u -z 31 => 31s 500000 9889470
276 echo -1 3 | GeoConvert -u -z 31s => 31s 500000 9889470
277 echo -1 3 | GeoConvert -u -z 31n => 31n 500000 -110530
278 NOTE: the letter in the zone specification for UTM is a hemisphere
280 designator n or s and not an MGRS latitude band letter. Convert the
281 MGRS latitude band letter to a hemisphere as follows: replace C thru M
282 by s (or south); replace N thru X by n (or north).
283
285 echo 38SMB4488 | GeoConvert => 33.33424 44.40363
286 echo 38SMB4488 | GeoConvert -: -p 1 => 33:20:03.25N 044:2413.06E
287 echo 38SMB4488 | GeoConvert -u => 38n 444500 3688500
288 echo E44d24 N33d20 | GeoConvert -m -p -3 => 38SMB4488
289 GeoConvert can be used to do simple arithmetic using degree, minutes,
291 and seconds. For example, sometimes data is tiled in 15 second squares
292 tagged by the DMS representation of the SW corner. The tags of the
293 tile at 38:59:45N 077:02:00W and its 8 neighbors are then given by
294 t=0:0:15
296 for y in -$t +0 +$t; do
297 for x in -$t +0 +$t; do
298 echo 38:59:45N$y 077:02:00W$x
299 done
300 done | GeoConvert -: -p -1 | tr -d ': '
301 =>
302 385930N0770215W
303 385930N0770200W
304 385930N0770145W
305 385945N0770215W
306 385945N0770200W
307 385945N0770145W
308 390000N0770215W
309 390000N0770200W
310 390000N0770145W
311
313 An illegal line of input will print an error message to standard output
314 beginning with "ERROR:" and causes GeoConvert to return an exit code of
315 1. However, an error does not cause GeoConvert to terminate; following
316 lines will be converted.
317
319 UTM Universal Transverse Mercator,
320 <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>.
321 UPS Universal Polar Stereographic,
323 <https://en.wikipedia.org/wiki/Universal_Polar_Stereographic>.
324 MGRS
326 Military Grid Reference System,
327 <https://en.wikipedia.org/wiki/Military_grid_reference_system>.
328 WGS84
330 World Geodetic System 1984, <https://en.wikipedia.org/wiki/WGS84>.
331
333 An online version of this utility is availbable at
334 <https://geographiclib.sourceforge.io/cgi-bin/GeoConvert>.
335 The algorithms for the transverse Mercator projection are described in
337 C. F. F. Karney, Transverse Mercator with an accuracy of a few
338 nanometers, J. Geodesy 85(8), 475-485 (Aug. 2011); DOI
339 <https://doi.org/10.1007/s00190-011-0445-3>; preprint
340 <https://arxiv.org/abs/1002.1417>.
341
343 GeoConvert was written by Charles Karney.
344
346 GeoConvert was added to GeographicLib,
347 <https://geographiclib.sourceforge.io>, in 2009-01.
348GeographicLib 1.52 2022-02-24 GEOCONVERT(1)