int usage(int retval, bool brief) { if (brief) ( retval ? std::cerr : std::cout ) << "Usage:\n" " Planimeter [ -r ] [ -s ] [ -l ] [ -e a f ] [ -w ] [ -p prec ] [ -G | -E\n" " | -Q | -R ] [ --comment-delimiter commentdelim ] [ --version | -h |\n" " --help ] [ --input-file infile | --input-string instring ] [\n" " --line-separator linesep ] [ --output-file outfile ]\n" "\n" "For full documentation type:\n" " Planimeter --help\n" "or visit:\n" " https://geographiclib.sourceforge.io/1.50.1/Planimeter.1.html\n"; else ( retval ? std::cerr : std::cout ) << "Man page:\n" "NAME\n" " Planimeter -- compute the area of geodesic polygons\n" "\n" "SYNOPSIS\n" " Planimeter [ -r ] [ -s ] [ -l ] [ -e a f ] [ -w ] [ -p prec ] [ -G | -E\n" " | -Q | -R ] [ --comment-delimiter commentdelim ] [ --version | -h |\n" " --help ] [ --input-file infile | --input-string instring ] [\n" " --line-separator linesep ] [ --output-file outfile ]\n" "\n" "DESCRIPTION\n" " Measure the area of a geodesic polygon. Reads polygon vertices from\n" " standard input, one per line. Vertices may be given as latitude and\n" " longitude, UTM/UPS, or MGRS coordinates, interpreted in the same way as\n" " GeoConvert(1). (MGRS coordinates signify the center of the\n" " corresponding MGRS square.) The end of input, a blank line, or a line\n" " which can't be interpreted as a vertex signals the end of one polygon\n" " and the start of the next. For each polygon print a summary line with\n" " the number of points, the perimeter (in meters), and the area (in\n" " meters^2).\n" "\n" " The edges of the polygon are given by the shortest geodesic between\n" " consecutive vertices. In certain cases, there may be two or many such\n" " shortest geodesics, and in that case, the polygon is not uniquely\n" " specified by its vertices. This only happens with very long edges (for\n" " the WGS84 ellipsoid, any edge shorter than 19970 km is uniquely\n" " specified by its end points). In such cases, insert an additional\n" " vertex near the middle of the long edge to define the boundary of the\n" " polygon.\n" "\n" " By default, polygons traversed in a counter-clockwise direction return\n" " a positive area and those traversed in a clockwise direction return a\n" " negative area. This sign convention is reversed if the -r option is\n" " given.\n" "\n" " Of course, encircling an area in the clockwise direction is equivalent\n" " to encircling the rest of the ellipsoid in the counter-clockwise\n" " direction. The default interpretation used by Planimeter is the one\n" " that results in a smaller magnitude of area; i.e., the magnitude of the\n" " area is less than or equal to one half the total area of the ellipsoid.\n" " If the -s option is given, then the interpretation used is the one that\n" " results in a positive area; i.e., the area is positive and less than\n" " the total area of the ellipsoid.\n" "\n" " Arbitrarily complex polygons are allowed. In the case of self-\n" " intersecting polygons the area is accumulated \"algebraically\", e.g.,\n" " the areas of the 2 loops in a figure-8 polygon will partially cancel.\n" " Polygons may include one or both poles. There is no need to close the\n" " polygon.\n" "\n" "OPTIONS\n" " -r toggle whether counter-clockwise traversal of the polygon returns a\n" " positive (the default) or negative result.\n" "\n" " -s toggle whether to return a signed result (the default) or not.\n" "\n" " -l toggle whether the vertices represent a polygon (the default) or a\n" " polyline. For a polyline, the number of points and the length of\n" " the path joining them is returned; the path is not closed and the\n" " area is not reported.\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. If entering vertices as UTM/UPS or\n" " MGRS coordinates, use the default ellipsoid, since the conversion\n" " of these coordinates to latitude and longitude always uses the\n" " WGS84 parameters.\n" "\n" " -w toggle the longitude first flag (it starts off); if the flag is on,\n" " then when reading geographic coordinates, longitude precedes\n" " latitude (this can be overridden by a hemisphere designator, N, S,\n" " E, W).\n" "\n" " -p prec\n" " set the output precision to prec (default 6); the perimeter is\n" " given (in meters) with prec digits after the decimal point; the\n" " area is given (in meters^2) with (prec - 5) digits after the\n" " decimal point.\n" "\n" " -G use the series formulation for the geodesics. This is the default\n" " option and is recommended for terrestrial applications. This\n" " option, -G, and the following three options, -E, -Q, and -R, are\n" " mutually exclusive.\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. (But note that the\n" " implementation of areas in GeodesicExact uses a high order series\n" " and this is only accurate for modest flattenings.)\n" "\n" " -Q perform the calculation on the authalic sphere. The area\n" " calculation is accurate even if the flattening is large, provided\n" " the edges are sufficiently short. The perimeter calculation is not\n" " accurate.\n" "\n" " -R The lines joining the vertices are rhumb lines instead of\n" " geodesics.\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. For a given polygon, the last such string found\n" " will be appended to the output line (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" "EXAMPLES\n" " Example (the area of the 100km MGRS square 18SWK)\n" "\n" " Planimeter < 4 400139.53295860 10007388597.1913\n" "\n" " The following code takes the output from gdalinfo and reports the area\n" " covered by the data (assuming the edges of the image are geodesics).\n" "\n" " #! /bin/sh\n" " egrep '^((Upper|Lower) (Left|Right)|Center) ' |\n" " sed -e 's/d /d/g' -e \"s/' /'/g\" | tr -s '(),\\r\\t' ' ' | awk '{\n" " if ($1 $2 == \"UpperLeft\")\n" " ul = $6 \" \" $5;\n" " else if ($1 $2 == \"LowerLeft\")\n" " ll = $6 \" \" $5;\n" " else if ($1 $2 == \"UpperRight\")\n" " ur = $6 \" \" $5;\n" " else if ($1 $2 == \"LowerRight\")\n" " lr = $6 \" \" $5;\n" " else if ($1 == \"Center\") {\n" " printf \"%s\\n%s\\n%s\\n%s\\n\\n\", ul, ll, lr, ur;\n" " ul = ll = ur = lr = \"\";\n" " }\n" " }\n" " ' | Planimeter | cut -f3 -d' '\n" "\n" "SEE ALSO\n" " GeoConvert(1), GeodSolve(1).\n" "\n" " An online version of this utility is availbable at\n" " .\n" "\n" " The algorithm for the area of geodesic polygon is given in Section 6 of\n" " C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013);\n" " DOI ; addenda:\n" " .\n" "\n" "AUTHOR\n" " Planimeter was written by Charles Karney.\n" "\n" "HISTORY\n" " Planimeter was added to GeographicLib,\n" " , in version 1.4.\n" ; return retval; }