ADD: new track message, Entity class and Position class

libs/geographiclib/man/CartConvert.pod

@@ -0,0 +1,150 @@
+=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.