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