425 lines
14 KiB
Plaintext
425 lines
14 KiB
Plaintext
=head1 NAME
|
|
|
|
GeoConvert -- convert geographic coordinates
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<GeoConvert> [ B<-g> | B<-d> | B<-:> | B<-u> | B<-m> | B<-c> ]
|
|
[ B<-z> I<zone> | B<-s> | B<-t> | B<-S> | B<-T> ]
|
|
[ B<-n> ] [ B<-w> ] [ B<-p> I<prec> ] [ B<-l> | B<-a> ]
|
|
[ B<--comment-delimiter> I<commentdelim> ]
|
|
[ B<--version> | B<-h> | B<--help> ]
|
|
[ B<--input-file> I<infile> | B<--input-string> I<instring> ]
|
|
[ B<--line-separator> I<linesep> ]
|
|
[ B<--output-file> I<outfile> ]
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<GeoConvert> reads from standard input interpreting each line as a
|
|
geographic coordinate and prints the coordinate in the format specified
|
|
by the options on standard output. The input is interpreted in one of
|
|
three different ways depending on how many space or comma delimited
|
|
tokens there are on the line. The options B<-g>, B<-d>, B<-u>, and B<-m>
|
|
govern the format of output. In all cases, the WGS84 model of the earth
|
|
is used (I<a> = 6378137 m, I<f> = 1/298.257223563).
|
|
|
|
=over
|
|
|
|
=item B<geographic>
|
|
|
|
2 tokens (output options B<-g>, B<-d>, or B<-:>) given as I<latitude>
|
|
I<longitude> using decimal degrees or degrees, minutes, and seconds.
|
|
Latitude is given first (unless the B<-w> option is given). See
|
|
L</GEOGRAPHIC COORDINATES> for a description of the format. For
|
|
example, the following are all equivalent
|
|
|
|
33.3 44.4
|
|
E44.4 N33.3
|
|
33d18'N 44d24'E
|
|
44d24 33d18N
|
|
33:18 +44:24
|
|
|
|
=item B<UTM/UPS>
|
|
|
|
3 tokens (output option B<-u>) given as I<zone>+I<hemisphere> I<easting>
|
|
I<northing> or I<easting> I<northing> I<zone>+I<hemisphere>, where
|
|
I<hemisphere> is either I<n> (or I<north>) or I<s> (or I<south>). The
|
|
I<zone> is absent for a UPS specification. For example,
|
|
|
|
38n 444140.54 3684706.36
|
|
444140.54 3684706.36 38n
|
|
s 2173854.98 2985980.58
|
|
2173854.98 2985980.58 s
|
|
|
|
=item B<MRGS>
|
|
|
|
1 token (output option B<-m>) is used to specify the center of an MGRS
|
|
grid square. For example,
|
|
|
|
38SMB4484
|
|
38SMB44140847064
|
|
|
|
=back
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over
|
|
|
|
=item B<-g>
|
|
|
|
output latitude and longitude using decimal degrees. Default output mode.
|
|
|
|
=item B<-d>
|
|
|
|
output latitude and longitude using degrees, minutes, and seconds (DMS).
|
|
|
|
=item B<-:>
|
|
|
|
like B<-d>, except use : as a separator instead of the d, ', and "
|
|
delimiters.
|
|
|
|
=item B<-u>
|
|
|
|
output UTM or UPS.
|
|
|
|
=item B<-m>
|
|
|
|
output MGRS.
|
|
|
|
=item B<-c>
|
|
|
|
output meridian convergence and scale for the corresponding UTM or UPS
|
|
projection. The meridian convergence is the bearing of grid north given
|
|
as degrees clockwise from true north.
|
|
|
|
=item B<-z> I<zone>
|
|
|
|
set the zone to I<zone> for output. Use either 0 E<lt> I<zone> E<lt>=
|
|
60 for a UTM zone or I<zone> = 0 for UPS. Alternatively use a
|
|
I<zone>+I<hemisphere> designation, e.g., 38n. See L</ZONE>.
|
|
|
|
=item B<-s>
|
|
|
|
use the standard UPS and UTM zones.
|
|
|
|
=item B<-t>
|
|
|
|
similar to B<-s> but forces UPS regions to the closest UTM zone.
|
|
|
|
=item B<-S> or B<-T>
|
|
|
|
behave the same as B<-s> and B<-t>, respectively, until the first legal
|
|
conversion is performed. For subsequent points, the zone and hemisphere
|
|
of that conversion are used. This enables a sequence of points to be
|
|
converted into UTM or UPS using a consistent coordinate system.
|
|
|
|
=item B<-n>
|
|
|
|
on input, MGRS coordinates refer to the south-west corner of the MGRS
|
|
square instead of the center; see L</MGRS>.
|
|
|
|
=item B<-w>
|
|
|
|
toggle the longitude first flag (it starts off); if the flag is on, then
|
|
on input and output, longitude precedes latitude (except that, on input,
|
|
this can be overridden by a hemisphere designator, I<N>, I<S>, I<E>,
|
|
I<W>).
|
|
|
|
=item B<-p> I<prec>
|
|
|
|
set the output precision to I<prec> (default 0); I<prec> is the
|
|
precision relative to 1 m. See L</PRECISION>.
|
|
|
|
=item B<-l>
|
|
|
|
on output, UTM/UPS uses the long forms I<north> and I<south> to
|
|
designate the hemisphere instead of I<n> or I<s>.
|
|
|
|
=item B<-a>
|
|
|
|
on output, UTM/UPS uses the abbreviations I<n> and I<s> to designate the
|
|
hemisphere instead of I<north> or I<south>; this is the default
|
|
representation.
|
|
|
|
=item B<--comment-delimiter> I<commentdelim>
|
|
|
|
set the comment delimiter to I<commentdelim> (e.g., "#" or "//"). If
|
|
set, the input lines will be scanned for this delimiter and, if found,
|
|
the delimiter and the rest of the line will be removed prior to
|
|
processing and subsequently appended to the output line (separated by a
|
|
space).
|
|
|
|
=item B<--version>
|
|
|
|
print version and exit.
|
|
|
|
=item B<-h>
|
|
|
|
print usage and exit.
|
|
|
|
=item B<--help>
|
|
|
|
print full documentation and exit.
|
|
|
|
=item B<--input-file> I<infile>
|
|
|
|
read input from the file I<infile> instead of from standard input; a file
|
|
name of "-" stands for standard input.
|
|
|
|
=item B<--input-string> I<instring>
|
|
|
|
read input from the string I<instring> instead of from standard input.
|
|
All occurrences of the line separator character (default is a semicolon)
|
|
in I<instring> are converted to newlines before the reading begins.
|
|
|
|
=item B<--line-separator> I<linesep>
|
|
|
|
set the line separator character to I<linesep>. By default this is a
|
|
semicolon.
|
|
|
|
=item B<--output-file> I<outfile>
|
|
|
|
write output to the file I<outfile> instead of to standard output; a
|
|
file name of "-" stands for standard output.
|
|
|
|
=back
|
|
|
|
=head1 PRECISION
|
|
|
|
I<prec> gives precision of the output with I<prec> = 0 giving 1 m
|
|
precision, I<prec> = 3 giving 1 mm precision, etc. I<prec> is the
|
|
number of digits after the decimal point for UTM/UPS. For MGRS, The
|
|
number of digits per coordinate is 5 + I<prec>; I<prec> = -6 results in
|
|
just the grid zone. For decimal degrees, the number of digits after the
|
|
decimal point is 5 + I<prec>. For DMS (degree, minute, seconds) output,
|
|
the number of digits after the decimal point in the seconds components
|
|
is 1 + I<prec>; if this is negative then use minutes (I<prec> = -2 or
|
|
-3) or degrees (I<prec> E<lt>= -4) as the least significant component.
|
|
Print convergence, resp. scale, with 5 + I<prec>, resp. 7 + I<prec>,
|
|
digits after the decimal point. The minimum value of I<prec> is -5 (-6
|
|
for MGRS) and the maximum is 9 for UTM/UPS, 9 for decimal degrees, 10
|
|
for DMS, 6 for MGRS, and 8 for convergence and scale.
|
|
|
|
=head1 GEOGRAPHIC COORDINATES
|
|
|
|
The utility accepts geographic coordinates, latitude and longitude, in a
|
|
number of common formats. Latitude precedes longitude, unless the B<-w>
|
|
option is given which switches this convention. On input, either
|
|
coordinate may be given first by appending or prepending I<N> or I<S> to
|
|
the latitude and I<E> or I<W> to the longitude. These hemisphere
|
|
designators carry an implied sign, positive for I<N> and I<E> and
|
|
negative for I<S> and I<W>. This sign multiplies any +/- sign prefixing
|
|
the coordinate. The coordinates may be given as decimal degree or as
|
|
degrees, minutes, and seconds. d, ', and " are used to denote degrees,
|
|
minutes, and seconds, with the least significant designator optional.
|
|
(See L</QUOTING> for how to quote the characters ' and " when entering
|
|
coordinates on the command line.) Alternatively, : (colon) may be used
|
|
to separate the various components. Only the final component of
|
|
coordinate can include a decimal point, and the minutes and seconds
|
|
components must be less than 60.
|
|
|
|
It is also possible to carry out addition or subtraction operations in
|
|
geographic coordinates. If the coordinate includes interior signs
|
|
(i.e., not at the beginning or immediately after an initial hemisphere
|
|
designator), then the coordinate is split before such signs; the pieces
|
|
are parsed separately and the results summed. For example the point 15"
|
|
east of 39N 70W is
|
|
|
|
39N 70W+0:0:15E
|
|
|
|
B<WARNING:> "Exponential" notation is not recognized for geographic
|
|
coordinates. Thus 7.0E1 is illegal, while 7.0E+1 is parsed
|
|
as (7.0E) + (+1), yielding the same result as 8.0E.
|
|
|
|
Various unicode characters (encoded with UTF-8) may also be used to
|
|
denote degrees, minutes, and seconds, e.g., the degree, prime, and
|
|
double prime symbols; in addition two single quotes can be used to
|
|
represent ".
|
|
|
|
The other GeographicLib utilities use the same rules for interpreting
|
|
geographic coordinates; in addition, azimuths and arc lengths are
|
|
interpreted the same way.
|
|
|
|
=head1 QUOTING
|
|
|
|
Unfortunately the characters ' and " have special meanings in many
|
|
shells and have to be entered with care. However note (1) that the
|
|
trailing designator is optional and that (2) you can use colons as a
|
|
separator character. Thus 10d20' can be entered as 10d20 or 10:20 and
|
|
10d20'30" can be entered as 10:20:30.
|
|
|
|
=over
|
|
|
|
=item Unix shells (sh, bash, tsch)
|
|
|
|
The characters ' and " can be quoted by preceding them with a \
|
|
(backslash); or you can quote a string containing ' with a pair of "s.
|
|
The two alternatives are illustrated by
|
|
|
|
echo 10d20\'30\" "20d30'40" | GeoConvert -d -p -1
|
|
=> 10d20'30"N 020d30'40"E
|
|
|
|
Quoting of command line arguments is similar
|
|
|
|
GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
|
|
=> 10d20'30"N 020d30'40"E
|
|
|
|
=item Windows command shell (cmd)
|
|
|
|
The ' character needs no quoting; the " character can either be quoted
|
|
by a ^ or can be represented by typing ' twice. (This quoting is
|
|
usually unnecessary because the trailing designator can be omitted.)
|
|
Thus
|
|
|
|
echo 10d20'30'' 20d30'40 | GeoConvert -d -p -1
|
|
=> 10d20'30"N 020d30'40"E
|
|
|
|
Use \ to quote the " character in a command line argument
|
|
|
|
GeoConvert -d -p -1 --input-string "10d20'30\" 20d30'40"
|
|
=> 10d20'30"N 020d30'40"E
|
|
|
|
=item Input from a file
|
|
|
|
No quoting need be done if the input from a file. Thus each line of the
|
|
file C<input.txt> should just contain the plain coordinates.
|
|
|
|
GeoConvert -d -p -1 < input.txt
|
|
|
|
=back
|
|
|
|
=head1 MGRS
|
|
|
|
MGRS coordinates represent a square patch of the earth, thus
|
|
C<38SMB4488> is in zone C<38n> with 444km E<lt>= I<easting> E<lt>
|
|
445km and 3688km E<lt>= I<northing> E<lt> 3689km. Consistent with
|
|
this representation, coordinates are I<truncated> (instead of
|
|
I<rounded>) to the requested precision. When an MGRS coordinate is
|
|
provided as input, B<GeoConvert> treats this as a representative point
|
|
within the square. By default, this representative point is the
|
|
I<center> of the square (C<38n 444500 3688500> in the example above).
|
|
(This leads to a stable conversion between MGRS and geographic
|
|
coordinates.) However, if the B<-n> option is given then the
|
|
south-west corner of the square is returned instead (C<38n 444000
|
|
3688000> in the example above).
|
|
|
|
=head1 ZONE
|
|
|
|
If the input is B<geographic>, B<GeoConvert> uses the standard rules of
|
|
selecting UTM vs UPS and for assigning the UTM zone (with the Norway and
|
|
Svalbard exceptions). If the input is B<UTM/UPS> or B<MGRS>, then the
|
|
choice between UTM and UPS and the UTM zone mirrors the input. The B<-z>
|
|
I<zone>, B<-s>, and B<-t> options allow these rules to be overridden
|
|
with I<zone> = 0 being used to indicate UPS. For example, the point
|
|
|
|
79.9S 6.1E
|
|
|
|
corresponds to possible MGRS coordinates
|
|
|
|
32CMS4324728161 (standard UTM zone = 32)
|
|
31CEM6066227959 (neighboring UTM zone = 31)
|
|
BBZ1945517770 (neighboring UPS zone)
|
|
|
|
then
|
|
|
|
echo 79.9S 6.1E | GeoConvert -p -3 -m => 32CMS4328
|
|
echo 31CEM6066227959 | GeoConvert -p -3 -m => 31CEM6027
|
|
echo 31CEM6066227959 | GeoConvert -p -3 -m -s => 32CMS4328
|
|
echo 31CEM6066227959 | GeoConvert -p -3 -m -z 0 => BBZ1917
|
|
|
|
Is I<zone> is specified with a hemisphere, then this is honored when
|
|
printing UTM coordinates:
|
|
|
|
echo -1 3 | GeoConvert -u => 31s 500000 9889470
|
|
echo -1 3 | GeoConvert -u -z 31 => 31s 500000 9889470
|
|
echo -1 3 | GeoConvert -u -z 31s => 31s 500000 9889470
|
|
echo -1 3 | GeoConvert -u -z 31n => 31n 500000 -110530
|
|
|
|
B<NOTE>: the letter in the zone specification for UTM is a hemisphere
|
|
designator I<n> or I<s> and I<not> an MGRS latitude band letter.
|
|
Convert the MGRS latitude band letter to a hemisphere as follows:
|
|
replace I<C> thru I<M> by I<s> (or I<south>); replace I<N> thru I<X> by
|
|
I<n> (or I<north>).
|
|
|
|
=head1 EXAMPLES
|
|
|
|
echo 38SMB4488 | GeoConvert => 33.33424 44.40363
|
|
echo 38SMB4488 | GeoConvert -: -p 1 => 33:20:03.25N 044:2413.06E
|
|
echo 38SMB4488 | GeoConvert -u => 38n 444500 3688500
|
|
echo E44d24 N33d20 | GeoConvert -m -p -3 => 38SMB4488
|
|
|
|
GeoConvert can be used to do simple arithmetic using degree, minutes,
|
|
and seconds. For example, sometimes data is tiled in 15 second squares
|
|
tagged by the DMS representation of the SW corner. The tags of the tile
|
|
at 38:59:45N 077:02:00W and its 8 neighbors are then given by
|
|
|
|
t=0:0:15
|
|
for y in -$t +0 +$t; do
|
|
for x in -$t +0 +$t; do
|
|
echo 38:59:45N$y 077:02:00W$x
|
|
done
|
|
done | GeoConvert -: -p -1 | tr -d ': '
|
|
=>
|
|
385930N0770215W
|
|
385930N0770200W
|
|
385930N0770145W
|
|
385945N0770215W
|
|
385945N0770200W
|
|
385945N0770145W
|
|
390000N0770215W
|
|
390000N0770200W
|
|
390000N0770145W
|
|
|
|
=head1 ERRORS
|
|
|
|
An illegal line of input will print an error message to standard output
|
|
beginning with C<ERROR:> and causes B<GeoConvert> to return an exit code
|
|
of 1. However, an error does not cause B<GeoConvert> to terminate;
|
|
following lines will be converted.
|
|
|
|
=head1 ABBREVIATIONS
|
|
|
|
=over
|
|
|
|
=item B<UTM>
|
|
|
|
Universal Transverse Mercator,
|
|
L<https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system>.
|
|
|
|
=item B<UPS>
|
|
|
|
Universal Polar Stereographic,
|
|
L<https://en.wikipedia.org/wiki/Universal_Polar_Stereographic>.
|
|
|
|
=item B<MGRS>
|
|
|
|
Military Grid Reference System,
|
|
L<https://en.wikipedia.org/wiki/Military_grid_reference_system>.
|
|
|
|
=item B<WGS84>
|
|
|
|
World Geodetic System 1984,
|
|
L<https://en.wikipedia.org/wiki/WGS84>.
|
|
|
|
=back
|
|
|
|
=head1 SEE ALSO
|
|
|
|
An online version of this utility is availbable at
|
|
L<https://geographiclib.sourceforge.io/cgi-bin/GeoConvert>.
|
|
|
|
The algorithms for the transverse Mercator projection are described in
|
|
C. F. F. Karney, I<Transverse Mercator with an accuracy of a few
|
|
nanometers>, J. Geodesy B<85>(8), 475-485 (Aug. 2011); DOI
|
|
L<https://doi.org/10.1007/s00190-011-0445-3>; preprint
|
|
L<https://arxiv.org/abs/1002.1417>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
B<GeoConvert> was written by Charles Karney.
|
|
|
|
=head1 HISTORY
|
|
|
|
B<GeoConvert> was added to GeographicLib,
|
|
L<https://geographiclib.sourceforge.io>, in 2009-01.
|