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. If the polygon is degenerate, the inside point will be set to None.

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(wcs[, steps])	Create a SingleSphericalPolygon from image footprint - the intersection of the image shape given by wcs.array_shape and the wcs.bounding_box if available) - converted to a world coordinate system.
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.
overlap(other)	Returns the fraction of self that is overlapped by other.
to_lonlat()	Convert SingleSphericalPolygon footprint to longitude and latitude.
to_radec()	Convert SingleSphericalPolygon footprint to longitude and latitude.
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. Area of degenerate polygons is defined to be zero.

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, None

Returns True if the polygon contains the given point. Returns None if the polygon is degenerate.

contains_point(point)

Determines if this SingleSphericalPolygon contains a given point.

Parameters:

pointan (x, y, z) triple

The point to test.

Returns:

containsbool, None

Returns True if the polygon contains the given point. Returns None if the polygon is degenerate.

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, None

Returns True if the polygon contains the given point. Returns None if the polygon is degenerate.

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(wcs, steps: int = 1) → SingleSphericalPolygon

Create a SingleSphericalPolygon from image footprint - the intersection of the image shape given by wcs.array_shape and the wcs.bounding_box if available) - converted to a world coordinate system.

If the number of edges per side is set to 1, the polygon will be rectangular. Otherwise, the polygon will capture WCS distortion along the edges of the footprint.

This method requires astropy installed.

Parameters:

wcs: astropy.wcs.WCS | astropy.io.fits.Header | str

any WCS object that implements the common WCS API

steps: int, optional

The number of edges to create along each side of the polygon. (Default value = 1)

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. Returns None if the polygon is degenerate.

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, None

Returns True if this polygon intersects the other polygon. Returns None if either polygon is degenerate.

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. Returns None if the polygon is degenerate.

is_clockwise()

Return True if the points in this polygon are in clockwise order. Return None if the points are all on a great circle.

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

Returns:

lon, latlist of float

List of lon and lat in degrees corresponding to points.

to_radec()

Convert SingleSphericalPolygon footprint to longitude and latitude.

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

See also

SphericalPolygon.multi_union

Notes

For implementation details, see the graph module.