SingleSphericalPolygon

class spherical_geometry.polygon.SingleSphericalPolygon(points, inside=None)

Bases: object

Polygons are represented by both a set of points (in Cartesian (x, y, z) normalized on the unit sphere), and an inside point. The inside point is necessary, because both the inside and outside of the polygon are finite areas on the great sphere, and therefore we need a way of specifying which is which.

Parameters:

pointsAn Nx3 array of (x, y, z) triples in vector space

These points define the boundary of the polygon.

It may contain zero points, in which it defines the null polygon. It may not contain one, two or three points. Four points are needed to define a triangle, since the polygon must be closed.

insideAn (x, y, z) triple, optional

This point must be inside the polygon. If not provided, an interior point will be calculated

Attributes Summary

inside	Get the inside point of the polygon.
points	The points defining the polygon.

Methods Summary

area()	Returns the area of the polygon on the unit sphere, in steradians.
contains_arc(a, b)	Returns True if the polygon fully encloses the arc given by a and b.
contains_lonlat(lon, lat[, degrees])	Determines if this SingleSphericalPolygon contains a given
contains_point(point)	Determines if this SingleSphericalPolygon contains a given point.
contains_radec(lon, lat[, degrees])	Determines if this SingleSphericalPolygon contains a given
convex_hull(points)	Create a new SingleSphericalPolygon from the convex hull of a list of points using the Graham Scan algorithm
copy()
draw(m, **plot_args)	Draws the polygon in a matplotlib.Basemap axes.
from_cone(lon, lat, radius[, degrees, steps])	Create a new SingleSphericalPolygon from a cone (otherwise known as a "small circle") defined using (lon, lat, radius).
from_lonlat(lon, lat[, center, degrees])	Create a new SingleSphericalPolygon from a list of (longitude, latitude) points.
from_radec(lon, lat[, center, degrees])	Create a new SingleSphericalPolygon from a list of (longitude, latitude) points.
from_wcs(fitspath[, steps, crval])	Create a new SingleSphericalPolygon from the footprint of a FITS WCS specification.
intersection(other)	Return a new SphericalPolygon that is the intersection of self and other.
intersects_arc(a, b)	Determines if this SingleSphericalPolygon intersects or contains the given arc.
intersects_poly(other)	Determines if this SingleSphericalPolygon intersects another SingleSphericalPolygon.
invert_polygon()	Compute the inverse (complement) of a single polygon
is_clockwise()	Return True if the points in this polygon are in clockwise order.
iter_polygons_flat()	Iterate over all base polygons that make up this multi-polygon set.
overlap(other)	Returns the fraction of self that is overlapped by other.
to_lonlat()	Convert SingleSphericalPolygon footprint to longitude and latitutde.
to_radec()	Convert SingleSphericalPolygon footprint to longitude and latitutde.
union(other)	Return a new SphericalPolygon that is the union of self and other.

Attributes Documentation

inside

Get the inside point of the polygon.

points

The points defining the polygon. It is an Nx3 array of (x, y, z) vectors. The polygon will be explicitly closed, i.e., the first and last points are the same.

Methods Documentation

area()

Returns the area of the polygon on the unit sphere, in steradians.

The area is computed using a generalization of Girard’s Theorem.

if \(\theta\) is the sum of the internal angles of the polygon, and n is the number of vertices, the area is:

\[S = \theta - (n - 2) \pi\]

The area can be negative if the points on the polygon are ordered counter-clockwise. Take the absolute value if that is not desired.

contains_arc(a, b)

Returns True if the polygon fully encloses the arc given by a and b.

contains_lonlat(lon, lat, degrees=True)

Determines if this SingleSphericalPolygon contains a given longitude and latitude.

Parameters:

lon, lat: Longitude and latitude. Must be scalars.

degrees : bool, optional

If `True`, (default) *lon* and *lat* are in decimal degrees,

otherwise in radians.

Returns:

containsbool

Returns True if the polygon contains the given point.

contains_point(point)

Determines if this SingleSphericalPolygon contains a given point.

Parameters:

pointan (x, y, z) triple

The point to test.

Returns:

containsbool

Returns True if the polygon contains the given point.

contains_radec(lon, lat, degrees=True)

Determines if this SingleSphericalPolygon contains a given longitude and latitude.

Parameters:

lon, lat: Longitude and latitude. Must be scalars.

degrees : bool, optional

If `True`, (default) *lon* and *lat* are in decimal degrees,

otherwise in radians.

Returns:

containsbool

Returns True if the polygon contains the given point.

classmethod convex_hull(points)

Create a new SingleSphericalPolygon from the convex hull of a list of points using the Graham Scan algorithm

Parameters:

points: A list of points on the unit sphere

Returns:

polygonSingleSphericalPolygon object

copy()

draw(m, **plot_args)

Draws the polygon in a matplotlib.Basemap axes.

Parameters:

mBasemap axes object

**plot_argsAny plot arguments to pass to basemap

classmethod from_cone(lon, lat, radius, degrees=True, steps=16)

Create a new SingleSphericalPolygon from a cone (otherwise known as a “small circle”) defined using (lon, lat, radius).

The cone is not represented as an ideal circle on the sphere, but as a series of great circle arcs. The resolution of this conversion can be controlled using the steps parameter.

Parameters:

lon, latfloat scalars

This defines the center of the cone

radiusfloat scalar

The radius of the cone

degreesbool, optional

If True, (default) lon, lat and radius are in decimal degrees, otherwise in radians.

stepsint, optional

The number of steps to use when converting the small circle to a polygon.

Returns:

polygonSingleSphericalPolygon object

classmethod from_lonlat(lon, lat, center=None, degrees=True)

Create a new SingleSphericalPolygon from a list of (longitude, latitude) points.

Parameters:

lon, lat1-D arrays of the same length

The vertices of the polygon in longitude and latitude.

center(lon, lat) pair, optional

A point inside of the polygon to define its inside.

degreesbool, optional

If True, (default) lon and lat are in decimal degrees, otherwise in radians.

Returns:

polygonSingleSphericalPolygon object

classmethod from_radec(lon, lat, center=None, degrees=True)

Create a new SingleSphericalPolygon from a list of (longitude, latitude) points.

Parameters:

lon, lat1-D arrays of the same length

The vertices of the polygon in longitude and latitude.

center(lon, lat) pair, optional

A point inside of the polygon to define its inside.

degreesbool, optional

If True, (default) lon and lat are in decimal degrees, otherwise in radians.

Returns:

polygonSingleSphericalPolygon object

classmethod from_wcs(fitspath, steps=1, crval=None)

Create a new SingleSphericalPolygon from the footprint of a FITS WCS specification.

This method requires having astropy installed.

Parameters:

fitspathpath to a FITS file, astropy.io.fits.Header, or astropy.wcs.WCS

Refers to a FITS header containing a WCS specification.

stepsint, optional

The number of steps along each edge to convert into polygon edges.

Returns:

polygonSingleSphericalPolygon object

intersection(other)

Return a new SphericalPolygon that is the intersection of self and other.

If the intersection is empty, a SphericalPolygon with zero subpolyons will be returned.

Parameters:

otherSingleSphericalPolygon

Returns:

polygonSphericalPolygon object

See also

SphericalPolygon.multi_union

Notes

For implementation details, see the graph module.

intersects_arc(a, b)

Determines if this SingleSphericalPolygon intersects or contains the given arc.

intersects_poly(other)

Determines if this SingleSphericalPolygon intersects another SingleSphericalPolygon.

This method is much faster than actually computing the intersection region between two polygons.

Parameters:

otherSingleSphericalPolygon

Returns:

intersectsbool

Returns True if this polygon intersects the other polygon.

Notes

The algorithm proceeds as follows:

1. Determine if any single point of one polygon is contained within the other.

2. Deal with the case where only the edges overlap as in:

   :       o---------o
   :  o----+---------+----o
   :  |    |         |    |
   :  o----+---------+----o
   :       o---------o
   

   In this case, an edge from one polygon must cross an edge from the other polygon.

invert_polygon()

Compute the inverse (complement) of a single polygon

is_clockwise()

Return True if the points in this polygon are in clockwise order.

The normal vector to the two arcs containing a vertes points outward from the sphere if the angle is clockwise and inward if the angle is counter-clockwise. The sign of the inner product of the normal vector with the vertex tells you this. The polygon is ordered clockwise if the vertices are predominantly clockwise and counter-clockwise if the reverse.

iter_polygons_flat()

Iterate over all base polygons that make up this multi-polygon set.

overlap(other)

Returns the fraction of self that is overlapped by other.

Let self be a and other be b, then the overlap is defined as:

\[\frac{S_{a \cap b}}{S_a}\]

Parameters:

otherSingleSphericalPolygon

Returns:

fracfloat

The fraction of self that is overlapped by other.

to_lonlat()

Convert SingleSphericalPolygon footprint to longitude and latitutde.

Returns:

lon, latlist of float

List of lon and lat in degrees corresponding to points.

to_radec()

Convert SingleSphericalPolygon footprint to longitude and latitutde.

Returns:

lon, latlist of float

List of lon and lat in degrees corresponding to points.

union(other)

Return a new SphericalPolygon that is the union of self and other.

Parameters:

otherSingleSphericalPolygon

Returns:

polygonSphericalPolygon object

See also

SphericalPolygon.multi_union

Notes

For implementation details, see the graph module.