SphericalPolygon

class spherical_geometry.polygon.SphericalPolygon(init, inside=None)

Bases: SingleSphericalPolygon

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.

This class contains a list of disjoint closed polygons.

Parameters:

initobject

May be either:

• A list of disjoint SphericalPolygon objects.

• An Nx3 array of (x, y, z) triples in Cartesian 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 or two points.

insideAn (x, y, z) triple, optional

If init is an array of points, this point must be inside the polygon. If it is not provided, one will be created.

Attributes Summary

degenerate	Return True if the polygon is degenerate (i.e., has no points, or is otherwise invalid).
inside	Iterate over the inside point of each of the polygons.
points	The points defining the polygons.
polygons	Get a sequence of all of the subpolygons.

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 SphericalPolygon contains a given
contains_point(point)	Determines if this SphericalPolygon contains a given point.
contains_radec(lon, lat[, degrees])	Determines if this SphericalPolygon contains a given
convex_hull(points)	Create a new SphericalPolygon from the convex hull of a list of points.
copy()
draw(m, **plot_args)	Draws the polygon in a matplotlib.Basemap axes.
from_cone(lon, lat, radius[, degrees, steps])	Create a new SphericalPolygon from a cone (otherwise known as a "small circle") defined using (lon, lat, radius).
from_lonlat(lon, lat[, center, degrees])	Create a new SphericalPolygon from a list of (longitude, latitude) points.
from_radec(lon, lat[, center, degrees])	Create a new SphericalPolygon from a list of (longitude, latitude) points.
from_wcs(wcs[, steps])	Create a SphericalPolygon from the footprint of 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 SphericalPolygon intersects or contains the given arc.
intersects_poly(other)	Determines if this SphericalPolygon intersects another SphericalPolygon.
invert_polygon()	Construct a polygon which is the inverse (complement) of the original polygon
is_clockwise()	Return True if all subpolygons are clockwise, False if all are counter-clockwise, and None if some are clockwise and some are counter-clockwise or are degenerate.
multi_intersection(polygons)	Return a new SphericalPolygon that is the intersection of all of the polygons in polygons.
multi_union(polygons)	Return a new SphericalPolygon that is the union of all of the polygons in polygons.
self_intersect(points)	Return true if the path defined by a list of points intersects itself
to_lonlat()	Convert the SphericalPolygon footprint to longitude and latitude coordinates.
to_radec()	Convert the SphericalPolygon footprint to longitude and latitude coordinates.
union(other)	Return a new SphericalPolygon that is the union of self and other.

Attributes Documentation

degenerate

Return True if the polygon is degenerate (i.e., has no points, or is otherwise invalid).

inside

Iterate over the inside point of each of the polygons.

points

The points defining the polygons. It is an iterator over disjoint closed polygons, where each element is an Nx3 array of (x, y, z) vectors. Each polygon is explicitly closed, i.e., the first and last points are the same.

polygons

Get a sequence of all of the subpolygons. Each subpolygon may itself have subpolygons.

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\]

contains_arc(a, b)

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

contains_lonlat(lon, lat, degrees=True)

Determines if this SphericalPolygon 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 SphericalPolygon 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 SphericalPolygon 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 SphericalPolygon from the convex hull of a list of points.

Parameters:

points: A list of points on the unit sphere

Returns:

polygonSphericalPolygon 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 SphericalPolygon 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:

polygonSphericalPolygon object

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

Create a new SphericalPolygon 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:

polygonSphericalPolygon object

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

Create a new SphericalPolygon 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:

polygonSphericalPolygon object

classmethod from_wcs(wcs, steps: int = 1) → SphericalPolygon

Create a SphericalPolygon from the footprint of 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:

polygonSphericalPolygon object

intersection(other)

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

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

Parameters:

otherSphericalPolygon

Returns:

polygonSphericalPolygon object

Notes

For implementation details, see the graph module.

intersects_arc(a, b)

Determines if this SphericalPolygon intersects or contains the given arc. Returns None if the polygon is degenerate.

intersects_poly(other)

Determines if this SphericalPolygon intersects another SphericalPolygon.

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

Parameters:

otherSphericalPolygon

Returns:

intersectsbool, None

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

invert_polygon()

Construct a polygon which is the inverse (complement) of the original polygon

is_clockwise()

Return True if all subpolygons are clockwise, False if all are counter-clockwise, and None if some are clockwise and some are counter-clockwise or are degenerate.

classmethod multi_intersection(polygons)

Return a new SphericalPolygon that is the intersection of all of the polygons in polygons.

Parameters:

polygonssequence of SphericalPolygon

Returns:

polygonSphericalPolygon object

classmethod multi_union(polygons)

Return a new SphericalPolygon that is the union of all of the polygons in polygons. Currently this implementation exhibits exponential time behavior and becomes practically unusable when dealing with on the order of 40 or more polygons.

Also, current implementation struggles when some of the input polygons are nearly identical. As a workaround, this method pre-filters input polygons and excludes those nearly the same as some other input polygon. Two poligons treated as the same polygon if their vertices (x, y, and z cordinates on a unit sphere) differ by less than 5e-9. This is equivalent to polygon vertices being separated by less than 0.0015 arcsec on the sky or by less than 2 mm on Earth (at average Earth radius).

Parameters:

polygonssequence of SphericalPolygon

Returns:

polygonSphericalPolygon object

See also

union

static self_intersect(points)

Return true if the path defined by a list of points intersects itself

to_lonlat()

Convert the SphericalPolygon footprint to longitude and latitude coordinates.

Returns:

polyonsiterator

Each element in the iterator is a tuple of the form (lon, lat), where each is an array of points.

to_radec()

Convert the SphericalPolygon footprint to longitude and latitude coordinates.

Returns:

polyonsiterator

Each element in the iterator is a tuple of the form (lon, lat), where each is an array of points.

union(other)

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

Parameters:

otherSphericalPolygon

Returns:

polygonSphericalPolygon object

See also

multi_union

Notes

For implementation details, see the graph module.