1GEOCONVERT(1)               GeographicLib Utilities              GEOCONVERT(1)
2
3
4

NAME

6       GeoConvert -- convert geographic coordinates
7

SYNOPSIS

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

DESCRIPTION

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
24       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
31               33.3 44.4
32               E44.4 N33.3
33               33d18'N 44d24'E
34               44d24 33d18N
35               33:18 +44:24
36
37       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
43               38n 444140.54 3684706.36
44               444140.54 3684706.36 38n
45               s 2173854.98 2985980.58
46               2173854.98 2985980.58 s
47
48       MRGS
49           1 token (output option -m) is used to specify the center of an MGRS
50           grid square.  For example,
51
52               38SMB4484
53               38SMB44140847064
54

OPTIONS

56       -g  output latitude and longitude using decimal degrees.  Default
57           output mode.
58
59       -d  output latitude and longitude using degrees, minutes, and seconds
60           (DMS).
61
62       -:  like -d, except use : as a separator instead of the d, ', and "
63           delimiters.
64
65       -u  output UTM or UPS.
66
67       -m  output MGRS.
68
69       -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
73       -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
78       -s  use the standard UPS and UTM zones.
79
80       -t  similar to -s but forces UPS regions to the closest UTM zone.
81
82       -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
89       -n  on input, MGRS coordinates refer to the south-west corner of the
90           MGRS square instead of the center; see "MGRS".
91
92       -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
97       -p prec
98           set the output precision to prec (default 0); prec is the precision
99           relative to 1 m.  See "PRECISION".
100
101       -l  on output, UTM/UPS uses the long forms north and south to designate
102           the hemisphere instead of n or s.
103
104       -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
108       --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
115       --version
116           print version and exit.
117
118       -h  print usage and exit.
119
120       --help
121           print full documentation and exit.
122
123       --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
127       --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
133       --line-separator linesep
134           set the line separator character to linesep.  By default this is a
135           semicolon.
136
137       --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

PRECISION

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

GEOGRAPHIC COORDINATES

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
173       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
180           39N 70W+0:0:15E
181
182       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
186       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
191       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

QUOTING

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
202       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
207              echo 10d20\'30\" "20d30'40" | GeoConvert -d -p -1
208              => 10d20'30"N 020d30'40"E
209
210           Quoting of command line arguments is similar
211
212              GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
213              => 10d20'30"N 020d30'40"E
214
215       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
221              echo 10d20'30'' 20d30'40 | GeoConvert -d -p -1
222              => 10d20'30"N 020d30'40"E
223
224           Use \ to quote the " character in a command line argument
225
226              GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
227              => 10d20'30"N 020d30'40"E
228
229       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
233             GeoConvert -d -p -1 < input.txt
234

MGRS

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

ZONE

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
256          79.9S 6.1E
257
258       corresponds to possible MGRS coordinates
259
260          32CMS4324728161 (standard UTM zone = 32)
261          31CEM6066227959 (neighboring UTM zone = 31)
262            BBZ1945517770 (neighboring UPS zone)
263
264       then
265
266          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
271       Is zone is specified with a hemisphere, then this is honored when
272       printing UTM coordinates:
273
274          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
279       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

EXAMPLES

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
290       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
295           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

ERRORS

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

ABBREVIATIONS

319       UTM Universal Transverse Mercator,
320           <https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>.
321
322       UPS Universal Polar Stereographic,
323           <https://en.wikipedia.org/wiki/Universal_Polar_Stereographic>.
324
325       MGRS
326           Military Grid Reference System,
327           <https://en.wikipedia.org/wiki/Military_grid_reference_system>.
328
329       WGS84
330           World Geodetic System 1984, <https://en.wikipedia.org/wiki/WGS84>.
331

SEE ALSO

333       An online version of this utility is availbable at
334       <https://geographiclib.sourceforge.io/cgi-bin/GeoConvert>.
335
336       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

AUTHOR

343       GeoConvert was written by Charles Karney.
344

HISTORY

346       GeoConvert was added to GeographicLib,
347       <https://geographiclib.sourceforge.io>, in 2009-01.
348
349
350
351GeographicLib 1.52                2021-06-21                     GEOCONVERT(1)
Impressum