GeographicLib::PolygonAreaT< GeodType > Class Template Reference

Polygon areas. More...

#include <GeographicLib/PolygonArea.hpp>

List of all members.

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 MajorRadius () const
Math::real Flattening () const
void CurrentPoint (real &lat, real &lon) const

Related Functions

(Note that these are not member functions.)



typedef PolygonAreaT< GeodesicPolygonArea
typedef PolygonAreaT
< GeodesicExact
PolygonAreaExact

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

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.

This is a templated class to allow it to be used with either Geodesic and GeodesicExact. GeographicLib::PolygonArea and GeographicLib::PolygonAreaExact are typedefs for these two 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;
  }
  return 0;
}

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

Definition at line 62 of file PolygonArea.hpp.


Constructor & Destructor Documentation

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 94 of file PolygonArea.hpp.

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


Member Function Documentation

template<class GeodType = Geodesic>
void GeographicLib::PolygonAreaT< GeodType >::Clear (  )  [inline]

Clear PolygonAreaT, allowing a new polygon to be started.

Definition at line 105 of file PolygonArea.hpp.

References GeographicLib::Math::NaN().

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

template<class GeodType >
void GeographicLib::PolygonAreaT< GeodType >::AddPoint ( real  lat,
real  lon 
) [inline]

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] and lon should be in the range [540, 540).

Definition at line 17 of file PolygonArea.cpp.

References GeographicLib::Math::AngNormalize().

template<class GeodType >
void GeographicLib::PolygonAreaT< GeodType >::AddEdge ( real  azi,
real  s 
) [inline]

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

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

Definition at line 36 of file PolygonArea.cpp.

template<class GeodType >
unsigned GeographicLib::PolygonAreaT< GeodType >::Compute ( bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const [inline]

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.

Definition at line 52 of file PolygonArea.cpp.

template<class GeodType >
unsigned GeographicLib::PolygonAreaT< GeodType >::TestPoint ( real  lat,
real  lon,
bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const [inline]

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] and lon should be in the range [540, 540).

Definition at line 94 of file PolygonArea.cpp.

template<class GeodType >
unsigned GeographicLib::PolygonAreaT< GeodType >::TestEdge ( real  azi,
real  s,
bool  reverse,
bool  sign,
real &  perimeter,
real &  area 
) const [inline]

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.

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

Definition at line 147 of file PolygonArea.cpp.

References GeographicLib::Math::NaN().

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 229 of file PolygonArea.hpp.

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 235 of file PolygonArea.hpp.

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 246 of file PolygonArea.hpp.


Friends And Related Function Documentation

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 257 of file PolygonArea.hpp.

template<class GeodType = Geodesic>
typedef PolygonAreaT<GeodesicExact> PolygonAreaExact [related]

Polygon areas using GeodesicExact. (But note that the implementation of areas in GeodesicExact uses a high order series and this is only accurate for modest flattenings.)

Definition at line 266 of file PolygonArea.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 6 Oct 2014 for GeographicLib by  doxygen 1.6.1