151 lines
5.0 KiB
Plaintext
151 lines
5.0 KiB
Plaintext
=head1 NAME
|
|
|
|
CartConvert -- convert geodetic coordinates to geocentric or local cartesian
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<CartConvert> [ B<-r> ] [ B<-l> I<lat0> I<lon0> I<h0> ]
|
|
[ B<-e> I<a> I<f> ] [ B<-w> ] [ B<-p> I<prec> ]
|
|
[ 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
|
|
|
|
Convert geodetic coordinates to either geocentric or local cartesian
|
|
coordinates. Geocentric coordinates have the origin at the center of
|
|
the earth, with the I<z> axis going thru the north pole, and the I<x>
|
|
axis thru I<latitude> = 0, I<longitude> = 0. By default, the
|
|
conversion is to geocentric coordinates. Specifying B<-l> I<lat0>
|
|
I<lon0> I<h0> causes a local coordinate system to be used with the
|
|
origin at I<latitude> = I<lat0>, I<longitude> = I<lon0>, I<height> =
|
|
I<h0>, I<z> normal to the ellipsoid and I<y> due north.
|
|
|
|
Geodetic coordinates are provided on standard input as a set of lines
|
|
containing (blank separated) I<latitude>, I<longitude> (decimal degrees
|
|
or degrees, minutes and seconds), and I<height> above the ellipsoid
|
|
(meters); for details on the allowed formats for latitude and longitude,
|
|
see the C<GEOGRAPHIC COORDINATES> section of GeoConvert(1). For each
|
|
set of geodetic coordinates, the corresponding cartesian coordinates
|
|
I<x>, I<y>, I<z> (meters) are printed on standard output.
|
|
|
|
=head1 OPTIONS
|
|
|
|
=over
|
|
|
|
=item B<-r>
|
|
|
|
perform the reverse projection. I<x>, I<y>, I<z> are given on
|
|
standard input and each line of standard output gives I<latitude>,
|
|
I<longitude>, I<height>. In general there are multiple solutions and
|
|
the result which minimizes the absolute value of I<height> is
|
|
returned, i.e., (I<latitude>, I<longitude>) corresponds to the closest
|
|
point on the ellipsoid.
|
|
|
|
=item B<-l> I<lat0> I<lon0> I<h0>
|
|
|
|
specifies conversions to and from a local cartesion coordinate systems
|
|
with origin I<lat0> I<lon0> I<h0>, instead of a geocentric coordinate
|
|
system. The B<-w> flag can be used to swap the default order of the 2
|
|
geographic coordinates, provided that it appears before B<-l>.
|
|
|
|
=item B<-e> I<a> I<f>
|
|
|
|
specify the ellipsoid via the equatorial radius, I<a> and
|
|
the flattening, I<f>. Setting I<f> = 0 results in a sphere. Specify
|
|
I<f> E<lt> 0 for a prolate ellipsoid. A simple fraction, e.g., 1/297,
|
|
is allowed for I<f>. By default, the WGS84 ellipsoid is used, I<a> =
|
|
6378137 m, I<f> = 1/298.257223563.
|
|
|
|
=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 6). I<prec> is the number
|
|
of digits after the decimal point for geocentric and local cartesion
|
|
coordinates and for the height (in meters). For latitudes and
|
|
longitudes (in degrees), the number of digits after the decimal point is
|
|
I<prec> + 5.
|
|
|
|
=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 EXAMPLES
|
|
|
|
echo 33.3 44.4 6000 | CartConvert
|
|
=> 3816209.60 3737108.55 3485109.57
|
|
echo 33.3 44.4 6000 | CartConvert -l 33 44 20
|
|
=> 37288.97 33374.29 5783.64
|
|
echo 30000 30000 0 | CartConvert -r
|
|
=> 6.483 45 -6335709.73
|
|
|
|
=head1 ERRORS
|
|
|
|
An illegal line of input will print an error message to standard output
|
|
beginning with C<ERROR:> and causes B<CartConvert> to return an exit
|
|
code of 1. However, an error does not cause B<CartConvert> to
|
|
terminate; following lines will be converted.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
The algorithm for converting geocentric to geodetic coordinates is given
|
|
in Appendix B of C. F. F. Karney, I<Geodesics on an ellipsoid of
|
|
revolution>, Feb. 2011; preprint L<https://arxiv.org/abs/1102.1215>.
|
|
|
|
=head1 AUTHOR
|
|
|
|
B<CartConvert> was written by Charles Karney.
|
|
|
|
=head1 HISTORY
|
|
|
|
B<CartConvert> was added to GeographicLib,
|
|
L<https://geographiclib.sourceforge.io>, in 2009-02. Prior to 2009-03 it was
|
|
called ECEFConvert.
|