GeographicLib 2.3

Public Member Functions | Related Functions | List of all members
GeographicLib::PolygonAreaT< GeodType > Class Template Reference

Polygon areas. More...

`#include <GeographicLib/PolygonArea.hpp>`

## Public Member Functions
| PolygonAreaT (const GeodType &earth, bool polyline=false)
void | Clear ()
void | AddPoint (real lat, real lon)
void | AddEdge (real azi, real s)
unsigned | Compute (bool reverse, bool sign, real &perimeter, real &area) const
unsigned | TestPoint (real lat, real lon, bool reverse, bool sign, real &perimeter, real &area) const
unsigned | TestEdge (real azi, real s, bool reverse, bool sign, real &perimeter, real &area) const
Inspector functions
Math::real | EquatorialRadius () const
Math::real | Flattening () const
void | CurrentPoint (real &lat, real &lon) const
unsigned | NumberPoints () const
bool | Polyline () const

## Related Functions
(Note that these are not member functions.)
typedef PolygonAreaT< Geodesic > | PolygonArea
typedef PolygonAreaT< GeodesicExact > | PolygonAreaExact
typedef PolygonAreaT< Rhumb > | PolygonAreaRhumb

## Detailed Description

template<class GeodType = Geodesic>
class GeographicLib::PolygonAreaT< GeodType >

Polygon areas.

This computes the area of a polygon whose edges are geodesics using the method given in Section 6 of

- C. F. F. Karney, Algorithms for geodesics, J. Geodesy 87, 43–55 (2013); DOI: 10.1007/s00190-012-0578-z; addenda: geod-addenda.html.

Arbitrarily complex polygons are allowed. In the case self-intersecting of polygons the area is accumulated "algebraically", e.g., the areas of the 2 loops in a figure-8 polygon will partially cancel.

This class lets you add vertices and edges one at a time to the polygon. The sequence must start with a vertex and thereafter vertices and edges can be added in any order. Any vertex after the first creates a new edge which is the shortest geodesic from the previous vertex. In some cases there may be two or many such shortest geodesics and the area is then not uniquely defined. In this case, either add an intermediate vertex or add the edge as an edge (by defining its direction and length).

The area and perimeter are accumulated at two times the standard floating point precision to guard against the loss of accuracy with many-sided polygons. At any point you can ask for the perimeter and area so far. There's an option to treat the points as defining a polyline instead of a polygon; in that case, only the perimeter is computed.

This is a templated class to allow it to be used with Geodesic, GeodesicExact, and Rhumb. GeographicLib::PolygonArea, GeographicLib::PolygonAreaExact, and GeographicLib::PolygonAreaRhumb are typedefs for these cases.

For GeographicLib::PolygonArea (edges defined by Geodesic), an upper bound on the error is about 0.1 m2 per vertex. However this is a wildly pessimistic estimate in most cases. A more realistic estimate of the error is given by a test involving 107 approximately regular polygons on the WGS84 ellipsoid. The centers and the orientations of the polygons were uniformly distributed, the number of vertices was log-uniformly distributed in [3, 300], and the center to vertex distance log-uniformly distributed in [0.1 m, 9000 km].

Using double precision (the standard precision for GeographicLib), the maximum error in the perimeter was 200 nm, and the maximum error in the area was

        0.0013 m^2 for perimeter < 10 km
        0.0070 m^2 for perimeter < 100 km
        0.070 m^2 for perimeter < 1000 km
        0.11 m^2 for all perimeters

The errors are given in terms of the perimeter, because it is expected that the errors depend mainly on the number of edges and the edge lengths.

Using long doubles (GEOGRPAHICLIB_PRECISION = 3), the maximum error in the perimeter was 200 pm, and the maximum error in the area was

        0.7 mm^2 for perim < 10 km
        3.2 mm^2 for perimeter < 100 km
        21 mm^2 for perimeter < 1000 km
        45 mm^2 for all perimeters

Template Parameters

  GeodType | the geodesic class to use.

Example of use:

// Example of using the GeographicLib::PolygonArea class
#include <iostream>
#include <exception>
#include <GeographicLib/PolygonArea.hpp>
#include <GeographicLib/Geodesic.hpp>
#include <GeographicLib/Constants.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
Geodesic geod(Constants::WGS84_a(), Constants::WGS84_f());
// Alternatively: const Geodesic& geod = Geodesic::WGS84();
PolygonArea poly(geod);
poly.AddPoint( 52, 0); // London
poly.AddPoint( 41,-74); // New York
poly.AddPoint(-23,-43); // Rio de Janeiro
poly.AddPoint(-26, 28); // Johannesburg
double perimeter, area;
unsigned n = poly.Compute(false, true, perimeter, area);
cout << n << " " << perimeter << " " << area << "\n";
// This adds a test for a bug fix for AddEdge. (Implements the
// Planimeter29 test in geodtest.c.)
PolygonArea poly1(geod);
poly1.AddPoint(0,0);
poly1.AddEdge(90,1000);
poly1.AddEdge(0,1000);
poly1.AddEdge(-90,1000);
n = poly1.Compute(false, true, perimeter, area);
// The area should be 1e6. Prior to the fix it was 1e6 - A/2, where
// A = ellipsoid area.
cout << n << " " << perimeter << " " << area << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition: CartConvert.cpp:29
Constants.hpp
Header for GeographicLib::Constants class.
Geodesic.hpp
Header for GeographicLib::Geodesic class.
PolygonArea.hpp
Header for GeographicLib::PolygonAreaT class.
GeographicLib::Constants::WGS84_f
static T WGS84_f()
Definition: Constants.hpp:141
GeographicLib::Constants::WGS84_a
static T WGS84_a()
Definition: Constants.hpp:135
GeographicLib::PolygonAreaT::PolygonArea
PolygonAreaT< Geodesic > PolygonArea
Definition: PolygonArea.hpp:294
GeographicLib
Namespace for GeographicLib.
Definition: Accumulator.cpp:12
std
Definition: NearestNeighbor.hpp:812

Planimeter is a command-line utility providing access to the functionality of PolygonAreaT.

Definition at line 97 of file PolygonArea.hpp.

## Constructor & Destructor Documentation

## ◆ PolygonAreaT()

template<class GeodType = Geodesic>

GeographicLib::PolygonAreaT< GeodType >::PolygonAreaT | ( | const GeodType & | earth,
|  | bool | polyline = `false`
| ) |  |
| inline

Constructor for PolygonAreaT.

Parameters

  [in] | earth | the Geodesic object to use for geodesic calculations.
  [in] | polyline | if true that treat the points as defining a polyline instead of a polygon (default = false).

Definition at line 128 of file PolygonArea.hpp.

References GeographicLib::PolygonAreaT< GeodType >::Clear().

## Member Function Documentation

## ◆ Clear()

template<class GeodType = Geodesic>

void GeographicLib::PolygonAreaT< GeodType >::Clear | ( |  | ) |
| inline

Clear PolygonAreaT, allowing a new polygon to be started.

Definition at line 140 of file PolygonArea.hpp.

References GeographicLib::Math::NaN().

Referenced by GeographicLib::PolygonAreaT< GeodType >::PolygonAreaT().

## ◆ AddPoint()

template<class GeodType >

void GeographicLib::PolygonAreaT< GeodType >::AddPoint | ( | real | lat,
|  | real | lon
| ) |  |

Add a point to the polygon or polyline.

Parameters

  [in] | lat | the latitude of the point (degrees).
  [in] | lon | the longitude of the point (degrees).

lat should be in the range [−90°, 90°].

Definition at line 69 of file PolygonArea.cpp.

## ◆ AddEdge()

template<class GeodType >

void GeographicLib::PolygonAreaT< GeodType >::AddEdge | ( | real | azi,
|  | real | s
| ) |  |

Add an edge to the polygon or polyline.

Parameters

  [in] | azi | azimuth at current point (degrees).
  [in] | s | distance from current point to next point (meters).

This does nothing if no points have been added yet. Use PolygonAreaT::CurrentPoint to determine the position of the new vertex.

Definition at line 88 of file PolygonArea.cpp.

## ◆ Compute()

template<class GeodType >

unsigned GeographicLib::PolygonAreaT< GeodType >::Compute | ( | bool | reverse,
|  | bool | sign,
|  | real & | perimeter,
|  | real & | area
| ) |  | const

Return the results so far.

Parameters

  [in] | reverse | if true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
  [in] | sign | if true then return a signed result for the area if the polygon is traversed in the "wrong" direction instead of returning the area for the rest of the earth.
  [out] | perimeter | the perimeter of the polygon or length of the polyline (meters).
  [out] | area | the area of the polygon (meters2); only set if polyline is false in the constructor.

Returns
  the number of points.

More points can be added to the polygon after this call.

Definition at line 104 of file PolygonArea.cpp.

## ◆ TestPoint()

template<class GeodType >

unsigned GeographicLib::PolygonAreaT< GeodType >::TestPoint | ( | real | lat,
|  | real | lon,
|  | bool | reverse,
|  | bool | sign,
|  | real & | perimeter,
|  | real & | area
| ) |  | const

Return the results assuming a tentative final test point is added; however, the data for the test point is not saved. This lets you report a running result for the perimeter and area as the user moves the mouse cursor. Ordinary floating point arithmetic is used to accumulate the data for the test point; thus the area and perimeter returned are less accurate than if PolygonAreaT::AddPoint and PolygonAreaT::Compute are used.

Parameters

  [in] | lat | the latitude of the test point (degrees).
  [in] | lon | the longitude of the test point (degrees).
  [in] | reverse | if true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
  [in] | sign | if true then return a signed result for the area if the polygon is traversed in the "wrong" direction instead of returning the area for the rest of the earth.
  [out] | perimeter | the approximate perimeter of the polygon or length of the polyline (meters).
  [out] | area | the approximate area of the polygon (meters2); only set if polyline is false in the constructor.

Returns
  the number of points.

lat should be in the range [−90°, 90°].

Definition at line 130 of file PolygonArea.cpp.

## ◆ TestEdge()

template<class GeodType >

unsigned GeographicLib::PolygonAreaT< GeodType >::TestEdge | ( | real | azi,
|  | real | s,
|  | bool | reverse,
|  | bool | sign,
|  | real & | perimeter,
|  | real & | area
| ) |  | const

Return the results assuming a tentative final test point is added via an azimuth and distance; however, the data for the test point is not saved. This lets you report a running result for the perimeter and area as the user moves the mouse cursor. Ordinary floating point arithmetic is used to accumulate the data for the test point; thus the area and perimeter returned are less accurate than if PolygonAreaT::AddEdge and PolygonAreaT::Compute are used.

Parameters

  [in] | azi | azimuth at current point (degrees).
  [in] | s | distance from current point to final test point (meters).
  [in] | reverse | if true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
  [in] | sign | if true then return a signed result for the area if the polygon is traversed in the "wrong" direction instead of returning the area for the rest of the earth.
  [out] | perimeter | the approximate perimeter of the polygon or length of the polyline (meters).
  [out] | area | the approximate area of the polygon (meters2); only set if polyline is false in the constructor.

Returns
  the number of points.

Definition at line 166 of file PolygonArea.cpp.

References GeographicLib::Math::NaN().

## ◆ EquatorialRadius()

template<class GeodType = Geodesic>

Math::real GeographicLib::PolygonAreaT< GeodType >::EquatorialRadius | ( |  | ) | const
| inline

Returns
  a the equatorial radius of the ellipsoid (meters). This is the value inherited from the Geodesic object used in the constructor.

Definition at line 250 of file PolygonArea.hpp.

## ◆ Flattening()

template<class GeodType = Geodesic>

Math::real GeographicLib::PolygonAreaT< GeodType >::Flattening | ( |  | ) | const
| inline

Returns
  f the flattening of the ellipsoid. This is the value inherited from the Geodesic object used in the constructor.

Definition at line 256 of file PolygonArea.hpp.

## ◆ CurrentPoint()

template<class GeodType = Geodesic>

void GeographicLib::PolygonAreaT< GeodType >::CurrentPoint | ( | real & | lat,
|  | real & | lon
| ) |  | const
| inline

Report the previous vertex added to the polygon or polyline.

Parameters

  [out] | lat | the latitude of the point (degrees).
  [out] | lon | the longitude of the point (degrees).

If no points have been added, then NaNs are returned. Otherwise, lon will be in the range [−180°, 180°].

Definition at line 267 of file PolygonArea.hpp.

## ◆ NumberPoints()

template<class GeodType = Geodesic>

unsigned GeographicLib::PolygonAreaT< GeodType >::NumberPoints | ( |  | ) | const
| inline

Report the number of points currently in the polygon or polyline.

Returns
  the number of points.

If no points have been added, then 0 is returned.

Definition at line 277 of file PolygonArea.hpp.

## ◆ Polyline()

template<class GeodType = Geodesic>

bool GeographicLib::PolygonAreaT< GeodType >::Polyline | ( |  | ) | const
| inline

Report whether the current object is a polygon or a polyline.

Returns
  true if the object is a polyline.

Definition at line 284 of file PolygonArea.hpp.

## Friends And Related Function Documentation

## ◆ PolygonArea

template<class GeodType = Geodesic>

typedef PolygonAreaT<Geodesic> PolygonArea
| related

Polygon areas using Geodesic. This should be used if the flattening is small.

Definition at line 294 of file PolygonArea.hpp.

## ◆ PolygonAreaExact

template<class GeodType = Geodesic>

typedef PolygonAreaT<GeodesicExact> PolygonAreaExact
| related

Deprecated:
  Polygon areas using GeodesicExact. Instead use PolygonArea with a Geodesic object specified with exact = true.

Definition at line 302 of file PolygonArea.hpp.

## ◆ PolygonAreaRhumb

template<class GeodType = Geodesic>

typedef PolygonAreaT<Rhumb> PolygonAreaRhumb
| related

Polygon areas using Rhumb.

Definition at line 309 of file PolygonArea.hpp.

The documentation for this class was generated from the following files:

- PolygonArea.hpp
- PolygonArea.cpp