SphericalPolygon¶
- class spherical_geometry.polygon.SphericalPolygon(init, inside=None)[source]¶
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
Iterate over the inside point of each of the polygons.
The points defining the 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 givencontains_point
(point)Determines if this
SphericalPolygon
contains a given point.contains_radec
(lon, lat[, degrees])Determines if this
SphericalPolygon
contains a givenconvex_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
(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
.Construct a polygon which is the inverse (complement) of the original polygon
Return True if all subpolygons are clockwise
Iterate over all base polygons that make up this multi-polygon set.
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
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
- 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. To get a flattened sequence of all base polygons, use
iter_polygons_flat
.
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 \(\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_lonlat(lon, lat, degrees=True)[source]¶
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
Returns
True
if the polygon contains the given point.
- contains_point(point)[source]¶
Determines if this
SphericalPolygon
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
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
Returns
True
if the polygon contains the given point.
- classmethod convex_hull(points)[source]¶
Create a new
SphericalPolygon
from the convex hull of a list of points.- Parameters:
- points: A list of points on the unit sphere
- Returns:
- polygon
SphericalPolygon
object
- polygon
- copy()¶
- draw(m, **plot_args)[source]¶
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)[source]¶
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:
- polygon
SphericalPolygon
object
- polygon
- classmethod from_lonlat(lon, lat, center=None, degrees=True)[source]¶
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:
- polygon
SphericalPolygon
object
- polygon
- 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:
- polygon
SphericalPolygon
object
- polygon
- 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:
- fitspathpath to a FITS file,
astropy.io.fits.Header
, orastropy.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.
- fitspathpath to a FITS file,
- Returns:
- polygon
SphericalPolygon
object
- polygon
- 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
- other
- Returns:
- polygon
SphericalPolygon
object
- polygon
Notes
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
- other
- Returns:
- intersectsbool
Returns
True
if this polygon intersects the other polygon.
- invert_polygon()[source]¶
Construct a polygon which is the inverse (complement) of the original polygon
- iter_polygons_flat()¶
Iterate over all base polygons that make up this multi-polygon set.
- classmethod multi_intersection(polygons)[source]¶
Return a new
SphericalPolygon
that is the intersection of all of the polygons in polygons.- Parameters:
- polygonssequence of
SphericalPolygon
- polygonssequence of
- Returns:
- polygon
SphericalPolygon
object
- polygon
- classmethod multi_union(polygons)[source]¶
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
, andz
cordinates on a unit sphere) differ by less than5e-9
. This is equivalent to polygon vertices being separated by less than 0.0015 arcsec on the sky or by less than2 mm
on Earth (at average Earth radius).- Parameters:
- polygonssequence of
SphericalPolygon
- polygonssequence of
- Returns:
- polygon
SphericalPolygon
object
- polygon
See also
- static self_intersect(points)[source]¶
Return true if the path defined by a list of points intersects itself
- to_lonlat()[source]¶
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)[source]¶
Return a new
SphericalPolygon
that is the union of self and other.- Parameters:
- other
SphericalPolygon
- other
- Returns:
- polygon
SphericalPolygon
object
- polygon
See also
Notes
For implementation details, see the
graph
module.