GeoTessCPP  2.2
Software to facilitate storage and retrieval of 3D information about the Earth.
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Static Protected Attributes | List of all members
geotess::GeoTessPolygon Class Reference

An ordered list of points on the surface of a unit sphere that define a closed polygon. More...

#include <GeoTessPolygon.h>

Inheritance diagram for geotess::GeoTessPolygon:
geotess::GeoTessPolygon3D

Public Member Functions

 GeoTessPolygon ()
 
 GeoTessPolygon (vector< double * > &points)
 Constructor that accepts a list of unit vectors that define the polygon. More...
 
 GeoTessPolygon (const double *center, double radius, int nEdges)
 Constructor that builds a circular polygon of a specified horizontal radius centered on position center. More...
 
 GeoTessPolygon (string filename)
 Constructor that reads a Polygon from a file. More...
 
virtual ~GeoTessPolygon ()
 
void addReference ()
 Add reference count;. More...
 
virtual string class_name ()
 Returns the class name. More...
 
bool contains (const double *x)
 return true if point x is located inside the polygon More...
 
bool containsAll (const vector< double * > &positions)
 Returns true if this Polygon contains all of the supplied unit vectors. More...
 
bool containsAny (const vector< double * > &points)
 Returns true if this Polygon contains any of the supplied unit vectors. More...
 
double getArea ()
 Retrieve the area of this polygon. More...
 
double getAreaLarge ()
 Retrieve the area of this polygon. More...
 
double getAreaSmall ()
 Retrieve the area of this polygon. More...
 
const double * getPoint (int index)
 Retrieve a reference to one point on the polygon boundary. More...
 
void getPoints (vector< double * > &points, const bool &repeatFirstPoint)
 Retrieve a deep copy of the points on the polygon. More...
 
void getPoints (vector< double * > &points, const bool &repeatFirstPoint, const double &maxSpacing)
 Retrieve a deep copy of the points on the polygon. More...
 
int getRefCount ()
 
const double *const getReferencePoint ()
 Retrieve a reference to the referencePoint. More...
 
const void getReferencePoint (double *u)
 Retrieve a copy to the referencePoint. More...
 
bool getReferencePointIn ()
 Retrieve the value of referenceIn which indicates whether or not the referencePoint is inside or outside the Polygon. More...
 
void invert ()
 Invert the current polygon. More...
 
bool isNotReferenced ()
 Returns true if reference count is zero. More...
 
bool onBoundary (GeoTessGreatCircle &gcRef)
 Return true if evaluation point is very close to being on the boundary of the polygon. More...
 
bool onBoundary (const double *x)
 Return true if evaluation point is very close to being on the boundary of the polygon. More...
 
void removeReference ()
 Remove reference count;. More...
 
void setReferencePoint (const double *refPoint, const bool &inside)
 Specify the reference point for this polygon and whether or not the specified point is inside or outside the polygon. More...
 
void setReferencePoint (double lat, double lon, bool inside)
 Specify the reference point for this polygon and whether or not the specified point is inside or outside the polygon. More...
 
int size ()
 Returns the number of edges that define the polygon. More...
 
string str (const bool &repeatFirstPoint, const bool &latFirst, const double &minLongitude=-180)
 Returns a String containing all the points that define the polygon with one lon, lat pair per record. More...
 
virtual void write (const string &outputFileName)
 

Static Public Member Functions

static double getTolerance ()
 Retrieve the tolerance value in radians used when comparing locations of two points. More...
 

Public Attributes

void * attachment
 Some unspecified information that applications can attach to this polygon. More...
 

Protected Member Functions

int edgeCrossings (GeoTessGreatCircle &gcRef)
 
void setup (vector< double * > &points)
 

Protected Attributes

vector< GeoTessGreatCircle * > edges
 A GreatCircle object for each edge of the polygon. More...
 
bool global
 If global is true this polygon encompasses the entire Earth and method contains() will always return the value of referenceIn. More...
 
bool lonFirst
 When reading/writing lat,lon data, should order be lat,lon or lon,lat. More...
 
int refCount
 Reference count. More...
 
bool referenceIn
 true if the referencePoint is inside the polygon. More...
 
double * referencePoint
 A point on the surface of the unit sphere that is used as a reference point. More...
 

Static Protected Attributes

static double TOLERANCE
 Tolerance value in radians used when comparing locations of two points. More...
 

Detailed Description

An ordered list of points on the surface of a unit sphere that define a closed polygon.

An ordered list of points on the surface of a unit sphere that define a closed polygon. Polygons have the ability to test whether or not an arbitrary test point on the sphere is inside or outside the polygon.

Besides the set of points that define the boundary of the polgon, a Polygon object has a single private instance of a reference point which is known to be either 'inside' or 'outside' the polygon. By default, the reference point is computed from the supplied boundary points in the following manner:

This method will work fine provided that polygons are 'smaller' than approximately a hemisphere. It is possible to override this behavior. The first method is to call the invert() method which simply reverses the value of whether the reference point is 'inside' or 'outside' the polygon. There are also methods that allow applications to specify both the position of the reference point and whether it is 'inside' or 'outside' the polygon.

A test point that is located very close to a polygon boundary point is deemed to be 'inside' the polygon. This means that if two adjacent, non-overlapping polygons share a boundary point, a test point near that boundary point will be deemed to be 'inside' both polygons. In this context two points are 'very close' if they are separated by less than 1e-7 radians or 5.7e-6 degrees. For a sphere with the radius of the Earth (6371 km), this corresponds to a linear distance of about 60 cm.

Polygon implements reference counting. This means that when some other object obtains a reference to a Polygon object, it should increment the polygon's reference count. When it is done with the polygon it should decrement the polygon's reference count and delete the polygon if the reference count is equal to zero.

Author
sballar

Constructor & Destructor Documentation

virtual geotess::GeoTessPolygon::~GeoTessPolygon ( )
virtual
geotess::GeoTessPolygon::GeoTessPolygon ( )
geotess::GeoTessPolygon::GeoTessPolygon ( vector< double * > &  points)

Constructor that accepts a list of unit vectors that define the polygon.

The polygon will be closed, i.e., if the first point and last point are not coincident then an edge will be created between them.

Polygon assumes ownership of the supplied points and will delete their memory when it is done with them. Callers should not use the points in the supplied vector after the call to this constructor.

Parameters
pointsCollection
Exceptions
PolygonException
geotess::GeoTessPolygon::GeoTessPolygon ( const double *  center,
double  radius,
int  nEdges 
)

Constructor that builds a circular polygon of a specified horizontal radius centered on position center.

Polygon does not assume ownership of the supplied unit vector.

Parameters
centerunit vector of the position of the center of the polygon.
radiusdouble angular radius of the polygon, in radians.
nEdgesnumber of points that define the border of the polygon.
Exceptions
PolygonException
geotess::GeoTessPolygon::GeoTessPolygon ( string  filename)

Constructor that reads a Polygon from a file.

If the supplied filename is 'global' or 'GLOBAL' then the polygon.contains(unit_vector) will always return true.

throws a GeoTessException if specified file is a kml or kmz file. GeoTessExplorer can translate kml/kmz files to a compatible ascii format.

Member Function Documentation

void geotess::GeoTessPolygon::addReference ( )
inline

Add reference count;.

virtual string geotess::GeoTessPolygon::class_name ( )
inlinevirtual

Returns the class name.

Reimplemented in geotess::GeoTessPolygon3D.

bool geotess::GeoTessPolygon::contains ( const double *  x)
inline

return true if point x is located inside the polygon

Parameters
xunit vector of position to be evaluated
Returns
true if point x is located inside the polygon
bool geotess::GeoTessPolygon::containsAll ( const vector< double * > &  positions)
inline

Returns true if this Polygon contains all of the supplied unit vectors.

Parameters
positionsunit vectors of positions to be evaluated
Returns
true if this Polygon contains all of the supplied unit vectors
bool geotess::GeoTessPolygon::containsAny ( const vector< double * > &  points)
inline

Returns true if this Polygon contains any of the supplied unit vectors.

Parameters
pointsarray of unit vectors
Returns
true if this Polygon contains any of the supplied unit vectors
Exceptions
PolygonException
int geotess::GeoTessPolygon::edgeCrossings ( GeoTessGreatCircle gcRef)
protected
double geotess::GeoTessPolygon::getArea ( )
inline

Retrieve the area of this polygon.

This is the unitless area (radians squared). It must be multiplied by R^2 where R is the radius of the sphere.

The area is computed assuming that the points on the polygon are listed in clockwise order when viewed from outside the unit sphere. If the compliment of this area is desired, simply subtract the reported area from the surface area of the entire sphere (4*PI).

Returns
double geotess::GeoTessPolygon::getAreaLarge ( )
inline

Retrieve the area of this polygon.

This is the unitless area (radians squared). It must be multiplied by R^2 where R is the radius of the sphere.

The area is computed assuming that the polygon area is greater than half the area of the entire sphere.

Returns
double geotess::GeoTessPolygon::getAreaSmall ( )
inline

Retrieve the area of this polygon.

This is the unitless area (radians squared). It must be multiplied by R^2 where R is the radius of the sphere.

The area is computed assuming that the polygon area is less than half the area of the entire sphere.

Returns
const double* geotess::GeoTessPolygon::getPoint ( int  index)
inline

Retrieve a reference to one point on the polygon boundary.

Caller should not delete this array.

Returns
a reference to a point on the polygon
void geotess::GeoTessPolygon::getPoints ( vector< double * > &  points,
const bool &  repeatFirstPoint 
)
inline

Retrieve a deep copy of the points on the polygon.

vector of points is not cleared by this method.

It is the caller's responsibility to delete the points retrieved with this method.

Parameters
pointsa vector of unit vectors in which to store the points of this polygon.
repeatFirstPointif true, last point will be equal to the first point.
void geotess::GeoTessPolygon::getPoints ( vector< double * > &  points,
const bool &  repeatFirstPoint,
const double &  maxSpacing 
)
inline

Retrieve a deep copy of the points on the polygon.

It is the caller's responsibility to delete the points retrieved with this method.

Parameters
pointsa vector of unit vectors in which to store the points of this polygon.
repeatFirstPointif true, last point will be equal to the first point.
maxSpacingmaximum spacing between points in radians. Extra points will be inserted as necessary so as to ensure that this is the case.
Returns
a deep copy of the points on the polygon.
int geotess::GeoTessPolygon::getRefCount ( )
inline
const double* const geotess::GeoTessPolygon::getReferencePoint ( )
inline

Retrieve a reference to the referencePoint.

Caller should not delete this array

Returns
const void geotess::GeoTessPolygon::getReferencePoint ( double *  u)
inline

Retrieve a copy to the referencePoint.

Parameters
u3-element array that will be populated with the unit vector of the referece point.
bool geotess::GeoTessPolygon::getReferencePointIn ( )
inline

Retrieve the value of referenceIn which indicates whether or not the referencePoint is inside or outside the Polygon.

static double geotess::GeoTessPolygon::getTolerance ( )
inlinestatic

Retrieve the tolerance value in radians used when comparing locations of two points.

void geotess::GeoTessPolygon::invert ( )
inline

Invert the current polygon.

What used to be in will be out and what used to be out will be in.

bool geotess::GeoTessPolygon::isNotReferenced ( )
inline

Returns true if reference count is zero.

bool geotess::GeoTessPolygon::onBoundary ( GeoTessGreatCircle gcRef)
inline

Return true if evaluation point is very close to being on the boundary of the polygon.

Parameters
gcRefthe great circle from the reference point to the evaluation point.
Returns
true if evaluation point is very close to being on the boundary of the polygon.
bool geotess::GeoTessPolygon::onBoundary ( const double *  x)
inline

Return true if evaluation point is very close to being on the boundary of the polygon.

Parameters
xthe evaluation point.
Returns
true if x is very close to being on the boundary of the polygon.
Exceptions
PolygonException
void geotess::GeoTessPolygon::removeReference ( )
inline

Remove reference count;.

void geotess::GeoTessPolygon::setReferencePoint ( const double *  refPoint,
const bool &  inside 
)
inline

Specify the reference point for this polygon and whether or not the specified point is inside or outside the polygon.

Polygon copies the supplied refPoint array to internal variable. No reference to the supplied array is stored.

Parameters
refPointa unit vector of a position known to be either inside or outside the polygon
insidetrue if the supplied reference point is known to be inside the polygon, false if known to be outside.
void geotess::GeoTessPolygon::setReferencePoint ( double  lat,
double  lon,
bool  inside 
)
inline

Specify the reference point for this polygon and whether or not the specified point is inside or outside the polygon.

Parameters
latgeographic latitude of reference point in degrees
lonlongitude of reference point in degrees
insidetrue if the supplied reference point is known to be inside the polygon, false if known to be outside.
void geotess::GeoTessPolygon::setup ( vector< double * > &  points)
protected
Parameters
pointsa list of unit vectors
int geotess::GeoTessPolygon::size ( )
inline

Returns the number of edges that define the polygon.

Equals the number of unique GeoVectors that define the polygon.

Returns
the number of edges that define the polygon. Equals the number of unique GeoVectors that define the polygon.
string geotess::GeoTessPolygon::str ( const bool &  repeatFirstPoint,
const bool &  latFirst,
const double &  minLongitude = -180 
)

Returns a String containing all the points that define the polygon with one lon, lat pair per record.

lats and lons are in degrees.

If latFirst is true, points are listed as lat, lon. If false, order is lon, lat.

Longitudes will be adjusted so that they fall in the range minLongitude to (minLongitude+360).

Parameters
repeatFirstPoint
Returns
String
Parameters
latFirstboolean
minLongitudedouble
virtual void geotess::GeoTessPolygon::write ( const string &  outputFileName)
virtual

Reimplemented in geotess::GeoTessPolygon3D.

Member Data Documentation

void* geotess::GeoTessPolygon::attachment

Some unspecified information that applications can attach to this polygon.

This information is not processed in anyway by Polygon.

vector<GeoTessGreatCircle*> geotess::GeoTessPolygon::edges
protected

A GreatCircle object for each edge of the polygon.

bool geotess::GeoTessPolygon::global
protected

If global is true this polygon encompasses the entire Earth and method contains() will always return the value of referenceIn.

bool geotess::GeoTessPolygon::lonFirst
protected

When reading/writing lat,lon data, should order be lat,lon or lon,lat.

int geotess::GeoTessPolygon::refCount
protected

Reference count.

bool geotess::GeoTessPolygon::referenceIn
protected

true if the referencePoint is inside the polygon.

double* geotess::GeoTessPolygon::referencePoint
protected

A point on the surface of the unit sphere that is used as a reference point.

The status of this point relative to the polygon is known, i.e., it is known if this point is inside or outside the polygon.

double geotess::GeoTessPolygon::TOLERANCE
staticprotected

Tolerance value in radians used when comparing locations of two points.


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