SphericalPolygon¶

class
spherical_geometry.polygon.
SphericalPolygon
(init, inside=None)[source]¶ 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.
This class contains a list of disjoint closed polygons.
Parameters: init : object
 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 must be “closed”, i.e., the last point is the same as the first.
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.
inside : An (x, y, z) triple, optional
If init is an array of points, this point must be inside the polygon. If not provided, the mean of the points will be used.
Attributes Summary
inside
Iterate over the inside point of each of the polygons. points
The points defining the polygons. 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_point
(point)Determines if this SphericalPolygon
contains a given point.copy
()draw
(m, **plot_args)Draws the polygon in a matplotlib.Basemap axes. from_cone
(ra, dec, radius[, degrees, steps])Create a new SphericalPolygon
from a cone (otherwise known as a “small circle”) defined using (ra, dec, radius).from_radec
(ra, dec[, center, degrees])Create a new SphericalPolygon
from a list of (ra, dec) points.from_wcs
(fitspath[, steps, crval])Create a new SphericalPolygon
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 SphericalPolygon
intersects or contains the given arc.intersects_poly
(other)Determines if this SphericalPolygon
intersects anotherSphericalPolygon
.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.overlap
(other)Returns the fraction of self that is overlapped by other. SphericalPolygon.same_points_as
to_radec
()Convert the SphericalPolygon
footprint to RA and DEC coordinates.union
(other)Return a new SphericalPolygon
that is the union of self and other.Attributes Documentation

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.
Methods Documentation

area
()[source]¶ Returns the area of the polygon on the unit sphere in steradians.
The area is computed using a generalization of Girard’s Theorem.
if is the sum of the internal angles of the polygon, and n is the number of vertices, the area is:

contains_point
(point)[source]¶ Determines if this
SphericalPolygon
contains a given point.Parameters: point : an (x, y, z) triple
The point to test.
Returns: contains : bool
Returns
True
if the polygon contains the given point.

copy
()¶

draw
(m, **plot_args)[source]¶ Draws the polygon in a matplotlib.Basemap axes.
Parameters: m : Basemap axes object
**plot_args : Any plot arguments to pass to basemap

classmethod
from_cone
(ra, dec, radius, degrees=True, steps=16.0)[source]¶ Create a new
SphericalPolygon
from a cone (otherwise known as a “small circle”) defined using (ra, dec, 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: ra, dec : float scalars
This defines the center of the cone
radius : float scalar
The radius of the cone
degrees : bool, optional
If
True
, (default) ra, dec and radius are in decimal degrees, otherwise in radians.steps : int, optional
The number of steps to use when converting the small circle to a polygon.
Returns: polygon :
SphericalPolygon
object

classmethod
from_radec
(ra, dec, center=None, degrees=True)[source]¶ Create a new
SphericalPolygon
from a list of (ra, dec) points.Parameters: ra, dec : 1D arrays of the same length
The vertices of the polygon in rightascension and declination. It must be “closed”, i.e., that is, the last point is the same as the first.
center : (ra, dec) pair, optional
A point inside of the polygon to define its inside. If no center point is provided, the mean of the polygon’s points in vector space will be used. That approach may not work for concave polygons.
degrees : bool, optional
If
True
, (default) ra and dec are in decimal degrees, otherwise in radians.Returns: polygon :
SphericalPolygon
object

classmethod
from_wcs
(fitspath, steps=1, crval=None)[source]¶ Create a new
SphericalPolygon
from the footprint of a FITS WCS specification.This method requires having astropy installed.
Parameters: fitspath : path to a FITS file,
astropy.io.fits.Header
, orastropy.wcs.WCS
Refers to a FITS header containing a WCS specification.
steps : int, optional
The number of steps along each edge to convert into polygon edges.
Returns: polygon :
SphericalPolygon
object

intersection
(other)[source]¶ 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: other : SphericalPolygon
Returns: polygon : SphericalPolygon
objectNotes
For implementation details, see the
graph
module.

intersects_arc
(a, b)[source]¶ Determines if this
SphericalPolygon
intersects or contains the given arc.

intersects_poly
(other)[source]¶ Determines if this
SphericalPolygon
intersects anotherSphericalPolygon
.This method is much faster than actually computing the intersection region between two polygons.
Parameters: other :
SphericalPolygon
Returns: intersects : bool
Returns
True
if this polygon intersects the other polygon.

classmethod
multi_intersection
(polygons)[source]¶ Return a new
SphericalPolygon
that is the intersection of all of the polygons in polygons.Parameters: polygons : sequence of SphericalPolygon
Returns: polygon : SphericalPolygon
object

classmethod
multi_union
(polygons)[source]¶ Return a new
SphericalPolygon
that is the union of all of the polygons in polygons.Parameters: polygons : sequence of SphericalPolygon
Returns: polygon : SphericalPolygon
objectSee also

overlap
(other)[source]¶ Returns the fraction of self that is overlapped by other.
Let self be a and other be b, then the overlap is defined as:
Parameters: other :
SphericalPolygon
Returns: frac : float
The fraction of self that is overlapped by other.

to_radec
()[source]¶ Convert the
SphericalPolygon
footprint to RA and DEC coordinates.Returns: polyons : iterator
Each element in the iterator is a tuple of the form (ra, dec), where each is an array of points.

union
(other)[source]¶ Return a new
SphericalPolygon
that is the union of self and other.Parameters: other : SphericalPolygon
Returns: polygon : SphericalPolygon
objectSee also
Notes
For implementation details, see the
graph
module.