1PLANIMETER(1)               GeographicLib Utilities              PLANIMETER(1)
2
3
4

NAME

6       Planimeter -- compute the area of geodesic polygons
7

SYNOPSIS

9       Planimeter [ -r ] [ -s ] [ -l ] [ -e a f ] [ -w ] [ -p prec ] [ -G | -E
10       | -Q | -R ] [ --comment-delimiter commentdelim ] [ --version | -h |
11       --help ] [ --input-file infile | --input-string instring ] [
12       --line-separator linesep ] [ --output-file outfile ]
13

DESCRIPTION

15       Measure the area of a geodesic polygon.  Reads polygon vertices from
16       standard input, one per line.  Vertices may be given as latitude and
17       longitude, UTM/UPS, or MGRS coordinates, interpreted in the same way as
18       GeoConvert(1).  (MGRS coordinates signify the center of the
19       corresponding MGRS square.)  The end of input, a blank line, or a line
20       which can't be interpreted as a vertex signals the end of one polygon
21       and the start of the next.  For each polygon print a summary line with
22       the number of points, the perimeter (in meters), and the area (in
23       meters^2).
24
25       The edges of the polygon are given by the shortest geodesic between
26       consecutive vertices.  In certain cases, there may be two or many such
27       shortest geodesics, and in that case, the polygon is not uniquely
28       specified by its vertices.  This only happens with very long edges (for
29       the WGS84 ellipsoid, any edge shorter than 19970 km is uniquely
30       specified by its end points).  In such cases, insert an additional
31       vertex near the middle of the long edge to define the boundary of the
32       polygon.
33
34       By default, polygons traversed in a counter-clockwise direction return
35       a positive area and those traversed in a clockwise direction return a
36       negative area.  This sign convention is reversed if the -r option is
37       given.
38
39       Of course, encircling an area in the clockwise direction is equivalent
40       to encircling the rest of the ellipsoid in the counter-clockwise
41       direction.  The default interpretation used by Planimeter is the one
42       that results in a smaller magnitude of area; i.e., the magnitude of the
43       area is less than or equal to one half the total area of the ellipsoid.
44       If the -s option is given, then the interpretation used is the one that
45       results in a positive area; i.e., the area is positive and less than
46       the total area of the ellipsoid.
47
48       Arbitrarily complex polygons are allowed.  In the case of self-
49       intersecting polygons the area is accumulated "algebraically", e.g.,
50       the areas of the 2 loops in a figure-8 polygon will partially cancel.
51       Polygons may include one or both poles.  There is no need to close the
52       polygon.
53

OPTIONS

55       -r  toggle whether counter-clockwise traversal of the polygon returns a
56           positive (the default) or negative result.
57
58       -s  toggle whether to return a signed result (the default) or not.
59
60       -l  toggle whether the vertices represent a polygon (the default) or a
61           polyline.  For a polyline, the number of points and the length of
62           the path joining them is returned; the path is not closed and the
63           area is not reported.
64
65       -e a f
66           specify the ellipsoid via the equatorial radius, a and the
67           flattening, f.  Setting f = 0 results in a sphere.  Specify f < 0
68           for a prolate ellipsoid.  A simple fraction, e.g., 1/297, is
69           allowed for f.  By default, the WGS84 ellipsoid is used, a =
70           6378137 m, f = 1/298.257223563.  If entering vertices as UTM/UPS or
71           MGRS coordinates, use the default ellipsoid, since the conversion
72           of these coordinates to latitude and longitude always uses the
73           WGS84 parameters.
74
75       -w  toggle the longitude first flag (it starts off); if the flag is on,
76           then when reading geographic coordinates, longitude precedes
77           latitude (this can be overridden by a hemisphere designator, N, S,
78           E, W).
79
80       -p prec
81           set the output precision to prec (default 6); the perimeter is
82           given (in meters) with prec digits after the decimal point; the
83           area is given (in meters^2) with (prec - 5) digits after the
84           decimal point.
85
86       -G  use the series formulation for the geodesics.  This is the default
87           option and is recommended for terrestrial applications.  This
88           option, -G, and the following three options, -E, -Q, and -R, are
89           mutually exclusive.
90
91       -E  use "exact" algorithms (based on elliptic integrals) for the
92           geodesic calculations.  These are more accurate than the (default)
93           series expansions for |f| > 0.02.  (But note that the
94           implementation of areas in GeodesicExact uses a high order series
95           and this is only accurate for modest flattenings.)
96
97       -Q  perform the calculation on the authalic sphere.  The area
98           calculation is accurate even if the flattening is large, provided
99           the edges are sufficiently short.  The perimeter calculation is not
100           accurate.
101
102       -R  The lines joining the vertices are rhumb lines instead of
103           geodesics.
104
105       --comment-delimiter commentdelim
106           set the comment delimiter to commentdelim (e.g., "#" or "//").  If
107           set, the input lines will be scanned for this delimiter and, if
108           found, the delimiter and the rest of the line will be removed prior
109           to processing.  For a given polygon, the last such string found
110           will be appended to the output line (separated by a space).
111
112       --version
113           print version and exit.
114
115       -h  print usage and exit.
116
117       --help
118           print full documentation and exit.
119
120       --input-file infile
121           read input from the file infile instead of from standard input; a
122           file name of "-" stands for standard input.
123
124       --input-string instring
125           read input from the string instring instead of from standard input.
126           All occurrences of the line separator character (default is a
127           semicolon) in instring are converted to newlines before the reading
128           begins.
129
130       --line-separator linesep
131           set the line separator character to linesep.  By default this is a
132           semicolon.
133
134       --output-file outfile
135           write output to the file outfile instead of to standard output; a
136           file name of "-" stands for standard output.
137

EXAMPLES

139       Example (the area of the 100km MGRS square 18SWK)
140
141          Planimeter <<EOF
142          18n 500000 4400000
143          18n 600000 4400000
144          18n 600000 4500000
145          18n 500000 4500000
146          EOF
147          => 4 400139.53295860 10007388597.1913
148
149       The following code takes the output from gdalinfo and reports the area
150       covered by the data (assuming the edges of the image are geodesics).
151
152          #! /bin/sh
153          egrep '^((Upper|Lower) (Left|Right)|Center) ' |
154          sed -e 's/d /d/g' -e "s/' /'/g" | tr -s '(),\r\t' ' ' | awk '{
155              if ($1 $2 == "UpperLeft")
156                  ul = $6 " " $5;
157              else if ($1 $2 == "LowerLeft")
158                  ll = $6 " " $5;
159              else if ($1 $2 == "UpperRight")
160                  ur = $6 " " $5;
161              else if ($1 $2 == "LowerRight")
162                  lr = $6 " " $5;
163              else if ($1 == "Center") {
164                  printf "%s\n%s\n%s\n%s\n\n", ul, ll, lr, ur;
165                  ul = ll = ur = lr = "";
166              }
167          }
168          ' | Planimeter | cut -f3 -d' '
169

ACCURACY

171       Using the -G option (the default), the accuracy was estimated by
172       computing the error in the area for 10^7 approximately regular polygons
173       on the WGS84 ellipsoid.  The centers and the orientations of the
174       polygons were uniformly distributed, the number of vertices was log-
175       uniformly distributed in [3, 300], and the center to vertex distance
176       log-uniformly distributed in [0.1 m, 9000 km].
177
178       The maximum error in the perimeter was 200 nm, and the maximum error in
179       the area was
180
181          0.0013 m^2 for perimeter < 10 km
182          0.0070 m^2 for perimeter < 100 km
183          0.070 m^2 for perimeter < 1000 km
184          0.11 m^2 for all perimeters
185

SEE ALSO

187       GeoConvert(1), GeodSolve(1).
188
189       An online version of this utility is availbable at
190       <https://geographiclib.sourceforge.io/cgi-bin/Planimeter>.
191
192       The algorithm for the area of geodesic polygon is given in Section 6 of
193       C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43-55 (2013);
194       DOI <https://doi.org/10.1007/s00190-012-0578-z>; addenda:
195       <https://geographiclib.sourceforge.io/geod-addenda.html>.
196

AUTHOR

198       Planimeter was written by Charles Karney.
199

HISTORY

201       Planimeter was added to GeographicLib,
202       <https://geographiclib.sourceforge.io>, in version 1.4.
203
204
205
206GeographicLib 1.52                2022-02-24                     PLANIMETER(1)
Impressum