Polygon areas. More...

#include <PolygonArea.hpp>

Public Member Functions
void	AddEdge (real azi, real s)

void	AddPoint (real lat, real lon)

void	Clear ()

unsigned	Compute (bool reverse, bool sign, real &perimeter, real &area) const

	PolygonAreaT (const GeodType &earth, bool polyline=false)

unsigned	TestEdge (real azi, real s, bool reverse, bool sign, real &perimeter, real &area) const

unsigned	TestPoint (real lat, real lon, bool reverse, bool sign, real &perimeter, real &area) const

Inspector functions
Math::real	MajorRadius () const

Math::real	Flattening () const

void	CurrentPoint (real &lat, real &lon) const

Private Types
typedef Math::real	real

Static Private Member Functions
static int	transit (real lon1, real lon2)

static int	transitdirect (real lon1, real lon2)

Private Attributes
real	_area0

Accumulator	_areasum

int	_crossings

GeodType	_earth

real	_lat0

real	_lat1

real	_lon0

real	_lon1

unsigned	_mask

unsigned	_num

Accumulator	_perimetersum

bool	_polyline

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.

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.

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";
  }
  catch (const exception& e) {
    cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

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

Definition at line 65 of file PolygonArea.hpp.

Member Typedef Documentation

◆ real

template<class GeodType = Geodesic>

typedef Math::real GeographicLib::PolygonAreaT< GeodType >::real

private

Definition at line 67 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 120 of file PolygonArea.hpp.

Member Function Documentation

◆ 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 38 of file src/PolygonArea.cpp.

◆ 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 17 of file src/PolygonArea.cpp.

◆ Clear()

template<class GeodType = Geodesic>

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

inline

Clear PolygonAreaT, allowing a new polygon to be started.

Definition at line 132 of file PolygonArea.hpp.

◆ 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 (meters²); 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 55 of file src/PolygonArea.cpp.

◆ 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 259 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 248 of file PolygonArea.hpp.

◆ MajorRadius()

template<class GeodType = Geodesic>

Math::real GeographicLib::PolygonAreaT< GeodType >::MajorRadius ( ) 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 242 of file PolygonArea.hpp.

◆ 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 (meters²); only set if polyline is false in the constructor.

Returns: the number of points.

Definition at line 151 of file src/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 (meters²); 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 98 of file src/PolygonArea.cpp.

◆ transit()

template<class GeodType = Geodesic>

static int GeographicLib::PolygonAreaT< GeodType >::transit	(	real	lon1,
		real	lon2
	)

inlinestaticprivate

Definition at line 76 of file PolygonArea.hpp.

◆ transitdirect()

template<class GeodType = Geodesic>

static int GeographicLib::PolygonAreaT< GeodType >::transitdirect	(	real	lon1,
		real	lon2
	)

inlinestaticprivate

Definition at line 92 of file PolygonArea.hpp.

Friends And Related Function Documentation

◆ PolygonArea

template<class GeodType = Geodesic>

typedef PolygonAreaT<Geodesic> PolygonArea

Definition at line 270 of file PolygonArea.hpp.

◆ PolygonAreaExact

template<class GeodType = Geodesic>

typedef PolygonAreaT<GeodesicExact> PolygonAreaExact

Definition at line 279 of file PolygonArea.hpp.

◆ PolygonAreaRhumb

template<class GeodType = Geodesic>

typedef PolygonAreaT<Rhumb> PolygonAreaRhumb

Definition at line 286 of file PolygonArea.hpp.

Member Data Documentation

◆ _area0

template<class GeodType = Geodesic>

real GeographicLib::PolygonAreaT< GeodType >::_area0

private

Definition at line 69 of file PolygonArea.hpp.

◆ _areasum

template<class GeodType = Geodesic>

Accumulator GeographicLib::PolygonAreaT< GeodType >::_areasum

private

Definition at line 74 of file PolygonArea.hpp.

◆ _crossings

template<class GeodType = Geodesic>

int GeographicLib::PolygonAreaT< GeodType >::_crossings

private

Definition at line 73 of file PolygonArea.hpp.

◆ _earth

template<class GeodType = Geodesic>

GeodType GeographicLib::PolygonAreaT< GeodType >::_earth

private

Definition at line 68 of file PolygonArea.hpp.

◆ _lat0

template<class GeodType = Geodesic>

real GeographicLib::PolygonAreaT< GeodType >::_lat0

private

Definition at line 75 of file PolygonArea.hpp.

◆ _lat1

template<class GeodType = Geodesic>

real GeographicLib::PolygonAreaT< GeodType >::_lat1

private

Definition at line 75 of file PolygonArea.hpp.

◆ _lon0

template<class GeodType = Geodesic>

real GeographicLib::PolygonAreaT< GeodType >::_lon0

private

Definition at line 75 of file PolygonArea.hpp.

◆ _lon1

template<class GeodType = Geodesic>

real GeographicLib::PolygonAreaT< GeodType >::_lon1

private

Definition at line 75 of file PolygonArea.hpp.

◆ _mask

template<class GeodType = Geodesic>

unsigned GeographicLib::PolygonAreaT< GeodType >::_mask

private

Definition at line 71 of file PolygonArea.hpp.

◆ _num

template<class GeodType = Geodesic>

unsigned GeographicLib::PolygonAreaT< GeodType >::_num

private

Definition at line 72 of file PolygonArea.hpp.

◆ _perimetersum

template<class GeodType = Geodesic>

Accumulator GeographicLib::PolygonAreaT< GeodType >::_perimetersum

private

Definition at line 74 of file PolygonArea.hpp.

◆ _polyline

template<class GeodType = Geodesic>

bool GeographicLib::PolygonAreaT< GeodType >::_polyline

private

Definition at line 70 of file PolygonArea.hpp.

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

Public Member Functions

Private Types

Static Private Member Functions

Private Attributes

Related Functions

Detailed Description

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

Member Typedef Documentation

◆ real

Constructor & Destructor Documentation

◆ PolygonAreaT()

Member Function Documentation

◆ AddEdge()

◆ AddPoint()

◆ Clear()

◆ Compute()

◆ CurrentPoint()

◆ Flattening()

◆ MajorRadius()

◆ TestEdge()

◆ TestPoint()

◆ transit()

◆ transitdirect()

Friends And Related Function Documentation

◆ PolygonArea

◆ PolygonAreaExact

◆ PolygonAreaRhumb

Member Data Documentation

◆ _area0

◆ _areasum

◆ _crossings

◆ _earth

◆ _lat0

◆ _lat1

◆ _lon0

◆ _lon1

◆ _mask

◆ _num

◆ _perimetersum

◆ _polyline

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