GeographicLib  1.35
Public Member Functions | List of all members
GeographicLib::PolygonArea Class Reference

Polygon areas. More...

#include <GeographicLib/PolygonArea.hpp>

Public Member Functions

 PolygonArea (const Geodesic &earth, bool polyline=false) throw ()
 
void Clear () throw ()
 
void AddPoint (real lat, real lon) throw ()
 
void AddEdge (real azi, real s) throw ()
 
unsigned Compute (bool reverse, bool sign, real &perimeter, real &area) const throw ()
 
unsigned TestPoint (real lat, real lon, bool reverse, bool sign, real &perimeter, real &area) const throw ()
 
unsigned TestEdge (real azi, real s, bool reverse, bool sign, real &perimeter, real &area) const throw ()
 
Inspector functions
Math::real MajorRadius () const throw ()
 
Math::real Flattening () const throw ()
 
void CurrentPoint (real &lat, real &lon) const throw ()
 

Detailed Description

Polygon areas.

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

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 in 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.

Example of use:

// Example of using the GeographicLib::PolygonArea class
#include <iostream>
#include <exception>
using namespace std;
using namespace GeographicLib;
int main() {
try {
// 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;
}
return 0;
}

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

Definition at line 55 of file PolygonArea.hpp.

Constructor & Destructor Documentation

GeographicLib::PolygonArea::PolygonArea ( const Geodesic earth,
bool  polyline = false 
)
throw (
)
inline

Constructor for PolygonArea.

Parameters
[in]earththe Geodesic object to use for geodesic calculations. By default this uses the WGS84 ellipsoid.
[in]polylineif true that treat the points as defining a polyline instead of a polygon (default = false).

Definition at line 88 of file PolygonArea.hpp.

Member Function Documentation

void GeographicLib::PolygonArea::Clear ( )
throw (
)
inline

Clear PolygonArea, allowing a new polygon to be started.

Definition at line 99 of file PolygonArea.hpp.

Referenced by main().

void GeographicLib::PolygonArea::AddPoint ( real  lat,
real  lon 
)
throw (
)

Add a point to the polygon or polyline.

Parameters
[in]latthe latitude of the point (degrees).
[in]lonthe longitude of the point (degrees).

lat should be in the range [−90°, 90°] and lon should be in the range [−540°, 540°).

Definition at line 16 of file PolygonArea.cpp.

References GeographicLib::Math::AngNormalize().

Referenced by main().

void GeographicLib::PolygonArea::AddEdge ( real  azi,
real  s 
)
throw (
)

Add an edge to the polygon or polyline.

Parameters
[in]aziazimuth at current point (degrees).
[in]sdistance from current point to next point (meters).

azi should be in the range [−540°, 540°). This does nothing if no points have been added yet. Use PolygonArea::CurrentPoint to determine the position of the new vertex.

Definition at line 34 of file PolygonArea.cpp.

unsigned GeographicLib::PolygonArea::Compute ( bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const
throw (
)

Return the results so far.

Parameters
[in]reverseif true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif 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]perimeterthe perimeter of the polygon or length of the polyline (meters).
[out]areathe area of the polygon (meters2); only set if polyline is false in the constructor.
Returns
the number of points.

Definition at line 49 of file PolygonArea.cpp.

Referenced by main().

unsigned GeographicLib::PolygonArea::TestPoint ( real  lat,
real  lon,
bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const
throw (
)

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 PolygonArea::AddPoint and PolygonArea::Compute are used.

Parameters
[in]latthe latitude of the test point (degrees).
[in]lonthe longitude of the test point (degrees).
[in]reverseif true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif 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]perimeterthe approximate perimeter of the polygon or length of the polyline (meters).
[out]areathe 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°] and lon should be in the range [−540°, 540°).

Definition at line 90 of file PolygonArea.cpp.

unsigned GeographicLib::PolygonArea::TestEdge ( real  azi,
real  s,
bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const
throw (
)

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 PolygonArea::AddEdge and PolygonArea::Compute are used.

Parameters
[in]aziazimuth at current point (degrees).
[in]sdistance from current point to final test point (meters).
[in]reverseif true then clockwise (instead of counter-clockwise) traversal counts as a positive area.
[in]signif 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]perimeterthe approximate perimeter of the polygon or length of the polyline (meters).
[out]areathe approximate area of the polygon (meters2); only set if polyline is false in the constructor.
Returns
the number of points.

azi should be in the range [−540°, 540°).

Definition at line 140 of file PolygonArea.cpp.

Math::real GeographicLib::PolygonArea::MajorRadius ( ) const
throw (
)
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 223 of file PolygonArea.hpp.

Math::real GeographicLib::PolygonArea::Flattening ( ) const
throw (
)
inline
Returns
f the flattening of the ellipsoid. This is the value inherited from the Geodesic object used in the constructor.

Definition at line 229 of file PolygonArea.hpp.

void GeographicLib::PolygonArea::CurrentPoint ( real &  lat,
real &  lon 
) const
throw (
)
inline

Report the previous vertex added to the polygon or polyline.

Parameters
[out]latthe latitude of the point (degrees).
[out]lonthe 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 240 of file PolygonArea.hpp.


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