int usage(int retval, bool brief) { if (brief) ( retval ? std::cerr : std::cout ) << "Usage:\n" " GeodSolve [ -i | -L lat1 lon1 azi1 | -D lat1 lon1 azi1 s13 | -I lat1\n" " lon1 lat3 lon3 ] [ -a ] [ -e a f ] [ -u ] [ -F ] [ -d | -: ] [ -w ] [\n" " -b ] [ -f ] [ -p prec ] [ -E ] [ --comment-delimiter commentdelim ] [\n" " --version | -h | --help ] [ --input-file infile | --input-string\n" " instring ] [ --line-separator linesep ] [ --output-file outfile ]\n" "\n" "For full documentation type:\n" " GeodSolve --help\n" "or visit:\n" " https://geographiclib.sourceforge.io/1.50.1/GeodSolve.1.html\n"; else ( retval ? std::cerr : std::cout ) << "Man page:\n" "NAME\n" " GeodSolve -- perform geodesic calculations\n" "\n" "SYNOPSIS\n" " GeodSolve [ -i | -L lat1 lon1 azi1 | -D lat1 lon1 azi1 s13 | -I lat1\n" " lon1 lat3 lon3 ] [ -a ] [ -e a f ] [ -u ] [ -F ] [ -d | -: ] [ -w ] [\n" " -b ] [ -f ] [ -p prec ] [ -E ] [ --comment-delimiter commentdelim ] [\n" " --version | -h | --help ] [ --input-file infile | --input-string\n" " instring ] [ --line-separator linesep ] [ --output-file outfile ]\n" "\n" "DESCRIPTION\n" " The shortest path between two points on the ellipsoid at (lat1, lon1)\n" " and (lat2, lon2) is called the geodesic. Its length is s12 and the\n" " geodesic from point 1 to point 2 has forward azimuths azi1 and azi2 at\n" " the two end points.\n" "\n" " GeodSolve operates in one of three modes:\n" "\n" " 1. By default, GeodSolve accepts lines on the standard input\n" " containing lat1 lon1 azi1 s12 and prints lat2 lon2 azi2 on standard\n" " output. This is the direct geodesic calculation.\n" "\n" " 2. With the -i command line argument, GeodSolve performs the inverse\n" " geodesic calculation. It reads lines containing lat1 lon1 lat2\n" " lon2 and prints the corresponding values of azi1 azi2 s12.\n" "\n" " 3. Command line arguments -L lat1 lon1 azi1 specify a geodesic line.\n" " GeodSolve then accepts a sequence of s12 values (one per line) on\n" " standard input and prints lat2 lon2 azi2 for each. This generates\n" " a sequence of points on a single geodesic. Command line arguments\n" " -D and -I work similarly with the geodesic line defined in terms of\n" " a direct or inverse geodesic calculation, respectively.\n" "\n" "OPTIONS\n" " -i perform an inverse geodesic calculation (see 2 above).\n" "\n" " -L lat1 lon1 azi1\n" " line mode (see 3 above); generate a sequence of points along the\n" " geodesic specified by lat1 lon1 azi1. The -w flag can be used to\n" " swap the default order of the 2 geographic coordinates, provided\n" " that it appears before -L. (-l is an alternative, deprecated,\n" " spelling of this flag.)\n" "\n" " -D lat1 lon1 azi1 s13\n" " line mode (see 3 above); generate a sequence of points along the\n" " geodesic specified by lat1 lon1 azi1 s13. The -w flag can be used\n" " to swap the default order of the 2 geographic coordinates, provided\n" " that it appears before -D. Similarly, the -a flag can be used to\n" " change the interpretation of s13 to a13, provided that it appears\n" " before -D.\n" "\n" " -I lat1 lon1 lat3 lon3\n" " line mode (see 3 above); generate a sequence of points along the\n" " geodesic specified by lat1 lon1 lat3 lon3. The -w flag can be used\n" " to swap the default order of the 2 geographic coordinates, provided\n" " that it appears before -I.\n" "\n" " -a toggle the arc mode flag (it starts off); if this flag is on, then\n" " on input and output s12 is replaced by a12 the arc length (in\n" " degrees) on the auxiliary sphere. See \"AUXILIARY SPHERE\".\n" "\n" " -e a f\n" " specify the ellipsoid via the equatorial radius, a and the\n" " flattening, f. Setting f = 0 results in a sphere. Specify f < 0\n" " for a prolate ellipsoid. A simple fraction, e.g., 1/297, is\n" " allowed for f. By default, the WGS84 ellipsoid is used, a =\n" " 6378137 m, f = 1/298.257223563.\n" "\n" " -u unroll the longitude. Normally, on output longitudes are reduced\n" " to lie in [-180deg,180deg). However with this option, the returned\n" " longitude lon2 is \"unrolled\" so that lon2 - lon1 indicates how\n" " often and in what sense the geodesic has encircled the earth. Use\n" " the -f option, to get both longitudes printed.\n" "\n" " -F fractional mode. This only has any effect with the -D and -I\n" " options (and is otherwise ignored). The values read on standard\n" " input are interpreted as fractional distances to point 3, i.e., as\n" " s12/s13 instead of s12. If arc mode is in effect, then the values\n" " denote fractional arc length, i.e., a12/a13. The fractional\n" " distances can be entered as a simple fraction, e.g., 3/4.\n" "\n" " -d output angles as degrees, minutes, seconds instead of decimal\n" " degrees.\n" "\n" " -: like -d, except use : as a separator instead of the d, ', and \"\n" " delimiters.\n" "\n" " -w toggle the longitude first flag (it starts off); if the flag is on,\n" " then on input and output, longitude precedes latitude (except that,\n" " on input, this can be overridden by a hemisphere designator, N, S,\n" " E, W).\n" "\n" " -b report the back azimuth at point 2 instead of the forward azimuth.\n" "\n" " -f full output; each line of output consists of 12 quantities: lat1\n" " lon1 azi1 lat2 lon2 azi2 s12 a12 m12 M12 M21 S12. a12 is described\n" " in \"AUXILIARY SPHERE\". The four quantities m12, M12, M21, and S12\n" " are described in \"ADDITIONAL QUANTITIES\".\n" "\n" " -p prec\n" " set the output precision to prec (default 3); prec is the precision\n" " relative to 1 m. See \"PRECISION\".\n" "\n" " -E use \"exact\" algorithms (based on elliptic integrals) for the\n" " geodesic calculations. These are more accurate than the (default)\n" " series expansions for |f| > 0.02.\n" "\n" " --comment-delimiter commentdelim\n" " set the comment delimiter to commentdelim (e.g., \"#\" or \"//\"). If\n" " set, the input lines will be scanned for this delimiter and, if\n" " found, the delimiter and the rest of the line will be removed prior\n" " to processing and subsequently appended to the output line\n" " (separated by a space).\n" "\n" " --version\n" " print version and exit.\n" "\n" " -h print usage and exit.\n" "\n" " --help\n" " print full documentation and exit.\n" "\n" " --input-file infile\n" " read input from the file infile instead of from standard input; a\n" " file name of \"-\" stands for standard input.\n" "\n" " --input-string instring\n" " read input from the string instring instead of from standard input.\n" " All occurrences of the line separator character (default is a\n" " semicolon) in instring are converted to newlines before the reading\n" " begins.\n" "\n" " --line-separator linesep\n" " set the line separator character to linesep. By default this is a\n" " semicolon.\n" "\n" " --output-file outfile\n" " write output to the file outfile instead of to standard output; a\n" " file name of \"-\" stands for standard output.\n" "\n" "INPUT\n" " GeodSolve measures all angles in degrees and all lengths (s12) in\n" " meters, and all areas (S12) in meters^2. On input angles (latitude,\n" " longitude, azimuth, arc length) can be as decimal degrees or degrees,\n" " minutes, seconds. For example, \"40d30\", \"40d30'\", \"40:30\", \"40.5d\",\n" " and 40.5 are all equivalent. By default, latitude precedes longitude\n" " for each point (the -w flag switches this convention); however on input\n" " either may be given first by appending (or prepending) N or S to the\n" " latitude and E or W to the longitude. Azimuths are measured clockwise\n" " from north; however this may be overridden with E or W.\n" "\n" " For details on the allowed formats for angles, see the \"GEOGRAPHIC\n" " COORDINATES\" section of GeoConvert(1).\n" "\n" "AUXILIARY SPHERE\n" " Geodesics on the ellipsoid can be transferred to the auxiliary sphere\n" " on which the distance is measured in terms of the arc length a12\n" " (measured in degrees) instead of s12. In terms of a12, 180 degrees is\n" " the distance from one equator crossing to the next or from the minimum\n" " latitude to the maximum latitude. Geodesics with a12 > 180 degrees do\n" " not correspond to shortest paths. With the -a flag, s12 (on both input\n" " and output) is replaced by a12. The -a flag does not affect the full\n" " output given by the -f flag (which always includes both s12 and a12).\n" "\n" "ADDITIONAL QUANTITIES\n" " The -f flag reports four additional quantities.\n" "\n" " The reduced length of the geodesic, m12, is defined such that if the\n" " initial azimuth is perturbed by dazi1 (radians) then the second point\n" " is displaced by m12 dazi1 in the direction perpendicular to the\n" " geodesic. m12 is given in meters. On a curved surface the reduced\n" " length obeys a symmetry relation, m12 + m21 = 0. On a flat surface, we\n" " have m12 = s12.\n" "\n" " M12 and M21 are geodesic scales. If two geodesics are parallel at\n" " point 1 and separated by a small distance dt, then they are separated\n" " by a distance M12 dt at point 2. M21 is defined similarly (with the\n" " geodesics being parallel to one another at point 2). M12 and M21 are\n" " dimensionless quantities. On a flat surface, we have M12 = M21 = 1.\n" "\n" " If points 1, 2, and 3 lie on a single geodesic, then the following\n" " addition rules hold:\n" "\n" " s13 = s12 + s23,\n" " a13 = a12 + a23,\n" " S13 = S12 + S23,\n" " m13 = m12 M23 + m23 M21,\n" " M13 = M12 M23 - (1 - M12 M21) m23 / m12,\n" " M31 = M32 M21 - (1 - M23 M32) m12 / m23.\n" "\n" " Finally, S12 is the area between the geodesic from point 1 to point 2\n" " and the equator; i.e., it is the area, measured counter-clockwise, of\n" " the geodesic quadrilateral with corners (lat1,lon1), (0,lon1),\n" " (0,lon2), and (lat2,lon2). It is given in meters^2.\n" "\n" "PRECISION\n" " prec gives precision of the output with prec = 0 giving 1 m precision,\n" " prec = 3 giving 1 mm precision, etc. prec is the number of digits\n" " after the decimal point for lengths. For decimal degrees, the number\n" " of digits after the decimal point is prec + 5. For DMS (degree,\n" " minute, seconds) output, the number of digits after the decimal point\n" " in the seconds component is prec + 1. The minimum value of prec is 0\n" " and the maximum is 10.\n" "\n" "ERRORS\n" " An illegal line of input will print an error message to standard output\n" " beginning with \"ERROR:\" and causes GeodSolve to return an exit code of\n" " 1. However, an error does not cause GeodSolve to terminate; following\n" " lines will be converted.\n" "\n" "ACCURACY\n" " Using the (default) series solution, GeodSolve is accurate to about 15\n" " nm (15 nanometers) for the WGS84 ellipsoid. The approximate maximum\n" " error (expressed as a distance) for an ellipsoid with the same\n" " equatorial radius as the WGS84 ellipsoid and different values of the\n" " flattening is\n" "\n" " |f| error\n" " 0.01 25 nm\n" " 0.02 30 nm\n" " 0.05 10 um\n" " 0.1 1.5 mm\n" " 0.2 300 mm\n" "\n" " If -E is specified, GeodSolve is accurate to about 40 nm (40\n" " nanometers) for the WGS84 ellipsoid. The approximate maximum error\n" " (expressed as a distance) for an ellipsoid with a quarter meridian of\n" " 10000 km and different values of the a/b = 1 - f is\n" "\n" " 1-f error (nm)\n" " 1/128 387\n" " 1/64 345\n" " 1/32 269\n" " 1/16 210\n" " 1/8 115\n" " 1/4 69\n" " 1/2 36\n" " 1 15\n" " 2 25\n" " 4 96\n" " 8 318\n" " 16 985\n" " 32 2352\n" " 64 6008\n" " 128 19024\n" "\n" "MULTIPLE SOLUTIONS\n" " The shortest distance returned for the inverse problem is (obviously)\n" " uniquely defined. However, in a few special cases there are multiple\n" " azimuths which yield the same shortest distance. Here is a catalog of\n" " those cases:\n" "\n" " lat1 = -lat2 (with neither point at a pole)\n" " If azi1 = azi2, the geodesic is unique. Otherwise there are two\n" " geodesics and the second one is obtained by setting [azi1,azi2] =\n" " [azi2,azi1], [M12,M21] = [M21,M12], S12 = -S12. (This occurs when\n" " the longitude difference is near +/-180 for oblate ellipsoids.)\n" "\n" " lon2 = lon1 +/- 180 (with neither point at a pole)\n" " If azi1 = 0 or +/-180, the geodesic is unique. Otherwise there are\n" " two geodesics and the second one is obtained by setting [azi1,azi2]\n" " = [-azi1,-azi2], S12 = -S12. (This occurs when lat2 is near -lat1\n" " for prolate ellipsoids.)\n" "\n" " Points 1 and 2 at opposite poles\n" " There are infinitely many geodesics which can be generated by\n" " setting [azi1,azi2] = [azi1,azi2] + [d,-d], for arbitrary d. (For\n" " spheres, this prescription applies when points 1 and 2 are\n" " antipodal.)\n" "\n" " s12 = 0 (coincident points)\n" " There are infinitely many geodesics which can be generated by\n" " setting [azi1,azi2] = [azi1,azi2] + [d,d], for arbitrary d.\n" "\n" "EXAMPLES\n" " Route from JFK Airport to Singapore Changi Airport:\n" "\n" " echo 40:38:23N 073:46:44W 01:21:33N 103:59:22E |\n" " GeodSolve -i -: -p 0\n" "\n" " 003:18:29.9 177:29:09.2 15347628\n" "\n" " Equally spaced waypoints on the route:\n" "\n" " for ((i = 0; i <= 10; ++i)); do echo $i/10; done |\n" " GeodSolve -I 40:38:23N 073:46:44W 01:21:33N 103:59:22E -F -: -p 0\n" "\n" " 40:38:23.0N 073:46:44.0W 003:18:29.9\n" " 54:24:51.3N 072:25:39.6W 004:18:44.1\n" " 68:07:37.7N 069:40:42.9W 006:44:25.4\n" " 81:38:00.4N 058:37:53.9W 017:28:52.7\n" " 83:43:26.0N 080:37:16.9E 156:26:00.4\n" " 70:20:29.2N 097:01:29.4E 172:31:56.4\n" " 56:38:36.0N 100:14:47.6E 175:26:10.5\n" " 42:52:37.1N 101:43:37.2E 176:34:28.6\n" " 29:03:57.0N 102:39:34.8E 177:07:35.2\n" " 15:13:18.6N 103:22:08.0E 177:23:44.7\n" " 01:21:33.0N 103:59:22.0E 177:29:09.2\n" "\n" "SEE ALSO\n" " GeoConvert(1).\n" "\n" " An online version of this utility is availbable at\n" " .\n" "\n" " The algorithms are described in C. F. F. Karney, Algorithms for\n" " geodesics, J. Geodesy 87, 43-55 (2013); DOI:\n" " ; addenda:\n" " .\n" "\n" " The Wikipedia page, Geodesics on an ellipsoid,\n" " .\n" "\n" "AUTHOR\n" " GeodSolve was written by Charles Karney.\n" "\n" "HISTORY\n" " GeodSolve was added to GeographicLib,\n" " , in 2009-03. Prior to version\n" " 1.30, it was called Geod. (The name was changed to avoid a conflict\n" " with the geod utility in proj.4.)\n" ; return retval; }