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:

Public Member Functions
virtual	~GeoTessPolygon ()

	GeoTessPolygon ()

	GeoTessPolygon (vector< double * > &points)

	GeoTessPolygon (const double *center, double radius, int nEdges)

	GeoTessPolygon (string filename)

virtual string	class_name ()

void	addReference ()

void	removeReference ()

bool	isNotReferenced ()

int	getRefCount ()

int	size ()

const double *const	getReferencePoint ()

const void	getReferencePoint (double *u)

bool	getReferencePointIn ()

void	invert ()

void	setReferencePoint (const double *refPoint, const bool &inside)

void	setReferencePoint (double lat, double lon, bool inside)

bool	containsAny (const vector< double * > &points)

bool	containsAll (const vector< double * > &positions)

bool	contains (const double *x)

bool	onBoundary (GeoTessGreatCircle &gcRef)

bool	onBoundary (const double *x)

void	getPoints (vector< double * > &points, const bool &repeatFirstPoint)

void	getPoints (vector< double * > &points, const bool &repeatFirstPoint, const double &maxSpacing)

const double *	getPoint (int index)

double	getArea ()

double	getAreaSmall ()

double	getAreaLarge ()

string	str (const bool &repeatFirstPoint, const bool &latFirst, const double &minLongitude=-180)

virtual void	write (const string &outputFileName)

Static Public Member Functions
static double	getTolerance ()

Public Attributes
void *	attachment

Protected Member Functions
void	setup (vector< double * > &points)

int	edgeCrossings (GeoTessGreatCircle &gcRef)

Protected Attributes
vector< GeoTessGreatCircle * >	edges

double *	referencePoint

bool	referenceIn

bool	global

bool	lonFirst

int	refCount

Static Protected Attributes
static double	TOLERANCE

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:

Compute the normalized vector mean of all the points that define the polygon and call it center.
set the referencePoint to the anti-pode of center.
set referencePointIn to false
test center to see if it is inside or outside the polygon and set the value of referencePointIn to this value.
change the value of referencePoint to center

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

Definition at line 111 of file GeoTessPolygon.h.

Constructor & Destructor Documentation

◆ ~GeoTessPolygon()

virtual geotess::GeoTessPolygon::~GeoTessPolygon ( )

virtual

◆ GeoTessPolygon() [1/4]

geotess::GeoTessPolygon::GeoTessPolygon ( )

◆ GeoTessPolygon() [2/4]

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

points Collection

Exceptions

PolygonException

◆ GeoTessPolygon() [3/4]

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

center	unit vector of the position of the center of the polygon.
radius	double angular radius of the polygon, in radians.
nEdges	number of points that define the border of the polygon.

Exceptions

PolygonException

◆ GeoTessPolygon() [4/4]

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

◆ addReference()

void geotess::GeoTessPolygon::addReference ( )

inline

Add reference count;

Definition at line 218 of file GeoTessPolygon.h.

◆ class_name()

virtual string geotess::GeoTessPolygon::class_name ( )

inlinevirtual

Returns the class name.

Reimplemented in geotess::GeoTessPolygon3D.

Definition at line 213 of file GeoTessPolygon.h.

◆ contains()

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

inline

return true if point x is located inside the polygon

Parameters

x	unit vector of position to be evaluated

Returns: true if point x is located inside the polygon

Definition at line 380 of file GeoTessPolygon.h.

◆ containsAll()

bool geotess::GeoTessPolygon::containsAll ( const vector< double * > & positions )

inline

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

Parameters

positions unit vectors of positions to be evaluated

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

Definition at line 366 of file GeoTessPolygon.h.

◆ containsAny()

bool geotess::GeoTessPolygon::containsAny ( const vector< double * > & points )

inline

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

Parameters

points array of unit vectors

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

Exceptions

PolygonException

Definition at line 352 of file GeoTessPolygon.h.

◆ edgeCrossings()

int geotess::GeoTessPolygon::edgeCrossings ( GeoTessGreatCircle & gcRef )

protected

◆ getArea()

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

Definition at line 529 of file GeoTessPolygon.h.

◆ getAreaLarge()

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

Definition at line 576 of file GeoTessPolygon.h.

◆ getAreaSmall()

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

Definition at line 561 of file GeoTessPolygon.h.

◆ getPoint()

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

Definition at line 512 of file GeoTessPolygon.h.

◆ getPoints() [1/2]

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

points	a vector of unit vectors in which to store the points of this polygon.
repeatFirstPoint	if true, last point will be equal to the first point.

Definition at line 443 of file GeoTessPolygon.h.

◆ getPoints() [2/2]

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

points	a vector of unit vectors in which to store the points of this polygon.
repeatFirstPoint	if true, last point will be equal to the first point.
maxSpacing	maximum 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.

Definition at line 481 of file GeoTessPolygon.h.

◆ getRefCount()

int geotess::GeoTessPolygon::getRefCount ( )

inline

Definition at line 241 of file GeoTessPolygon.h.

◆ getReferencePoint() [1/2]

const double* const geotess::GeoTessPolygon::getReferencePoint ( )

inline

Retrieve a reference to the referencePoint.

Caller should not delete this array

Returns

Definition at line 269 of file GeoTessPolygon.h.

◆ getReferencePoint() [2/2]

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

inline

Retrieve a copy to the referencePoint.

Parameters

u	3-element array that will be populated with the unit vector of the referece point.

Definition at line 280 of file GeoTessPolygon.h.

◆ getReferencePointIn()

bool geotess::GeoTessPolygon::getReferencePointIn ( )

inline

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

Definition at line 291 of file GeoTessPolygon.h.

◆ getTolerance()

static double geotess::GeoTessPolygon::getTolerance ( )

inlinestatic

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

Definition at line 258 of file GeoTessPolygon.h.

◆ invert()

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.

Definition at line 300 of file GeoTessPolygon.h.

◆ isNotReferenced()

bool geotess::GeoTessPolygon::isNotReferenced ( )

inline

Returns true if reference count is zero.

Definition at line 239 of file GeoTessPolygon.h.

◆ onBoundary() [1/2]

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

x	the evaluation point.

Returns: true if x is very close to being on the boundary of the polygon.

Exceptions

PolygonException

Definition at line 423 of file GeoTessPolygon.h.

◆ onBoundary() [2/2]

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

inline

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

Parameters

gcRef the 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.

Definition at line 397 of file GeoTessPolygon.h.

◆ removeReference()

void geotess::GeoTessPolygon::removeReference ( )

inline

Remove reference count;

Definition at line 223 of file GeoTessPolygon.h.

◆ setReferencePoint() [1/2]

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

refPoint	a unit vector of a position known to be either inside or outside the polygon
inside	true if the supplied reference point is known to be inside the polygon, false if known to be outside.

Definition at line 317 of file GeoTessPolygon.h.

◆ setReferencePoint() [2/2]

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

lat	geographic latitude of reference point in degrees
lon	longitude of reference point in degrees
inside	true if the supplied reference point is known to be inside the polygon, false if known to be outside.

Definition at line 337 of file GeoTessPolygon.h.

◆ setup()

void geotess::GeoTessPolygon::setup ( vector< double * > & points )

protected

Parameters

points a list of unit vectors

◆ size()

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.

Definition at line 250 of file GeoTessPolygon.h.

◆ str()

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

latFirst	boolean
minLongitude	double

◆ write()

virtual void geotess::GeoTessPolygon::write ( const string & outputFileName )

virtual

Reimplemented in geotess::GeoTessPolygon3D.

Member Data Documentation

◆ attachment

void* geotess::GeoTessPolygon::attachment

Some unspecified information that applications can attach to this polygon. This information is not processed in anyway by Polygon.

Definition at line 169 of file GeoTessPolygon.h.

◆ edges

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

protected

A GreatCircle object for each edge of the polygon.

Definition at line 118 of file GeoTessPolygon.h.

◆ global

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.

Definition at line 142 of file GeoTessPolygon.h.

◆ lonFirst

bool geotess::GeoTessPolygon::lonFirst

protected

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

Definition at line 147 of file GeoTessPolygon.h.

◆ refCount

int geotess::GeoTessPolygon::refCount

protected

Reference count.

Definition at line 159 of file GeoTessPolygon.h.

◆ referenceIn

bool geotess::GeoTessPolygon::referenceIn

protected

true if the referencePoint is inside the polygon.

Definition at line 131 of file GeoTessPolygon.h.

◆ referencePoint

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.

Definition at line 126 of file GeoTessPolygon.h.

◆ TOLERANCE

double geotess::GeoTessPolygon::TOLERANCE

staticprotected

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

Definition at line 136 of file GeoTessPolygon.h.

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

rstt/GeoTessCPP/include/GeoTessPolygon.h

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~GeoTessPolygon()

◆ GeoTessPolygon() [1/4]

◆ GeoTessPolygon() [2/4]

◆ GeoTessPolygon() [3/4]

◆ GeoTessPolygon() [4/4]

Member Function Documentation

◆ addReference()

◆ class_name()

◆ contains()

◆ containsAll()

◆ containsAny()

◆ edgeCrossings()

◆ getArea()

◆ getAreaLarge()

◆ getAreaSmall()

◆ getPoint()

◆ getPoints() [1/2]

◆ getPoints() [2/2]

◆ getRefCount()

◆ getReferencePoint() [1/2]

◆ getReferencePoint() [2/2]

◆ getReferencePointIn()

◆ getTolerance()

◆ invert()

◆ isNotReferenced()

◆ onBoundary() [1/2]

◆ onBoundary() [2/2]

◆ removeReference()

◆ setReferencePoint() [1/2]

◆ setReferencePoint() [2/2]

◆ setup()

◆ size()

◆ str()

◆ write()

Member Data Documentation

◆ attachment

◆ edges

◆ global

◆ lonFirst

◆ refCount

◆ referenceIn

◆ referencePoint

◆ TOLERANCE