Spherical Polygons in Python¶

class sphersgeo.SphericalPolygon(polygon: ArcString | tuple[ArcString, SphericalPoint])¶

polygon on the sphere, represented by a counterclockwise ArcString (assumed to be closed) to form the boundary, and a SphericalPoint guaranteed to be inside the polygon (inferred if not provided)

Attention

The inside of a SphericalPolygon is always assumed to be the area to the left of the boundary. Thus, passing a clockwise boundary will make the “inside” of the polygon the entire surface area of the sphere sans the area enclosed by the boundary.

Attention

SphericalPolygon s in sphersgeo do NOT have holes.

Create a SphericalPolygon from an ArcString:

from sphersgeo import ArcString, SphericalPolygon

abc = SphericalPolygon(ArcString([(60.0, 0.0), (60.0, 30.0), (-30.0, -30.0)]))

... or from the inputs required to make an ArcString:

from sphersgeo import SphericalPolygon

abc = SphericalPolygon(
    [
        (0.43301270189221946, 0.75, 0.5),
        (0.5, 0.8660254037844386, 0.0),
        (0.75, -0.4330127018922193, -0.5),
    ]
)

classmethod from_cone(center: SphericalPoint, radius: float, steps: int = 16) → SphericalPolygon¶

property convex: bool¶: whether this polygon is convex, that is, all possible arcs between points inside the polygon can never leave the enclosed space

property inverse: SphericalPolygon¶

simplify()¶: remove redundant vertices that already lie along an arc in the boundary

property boundary: ArcString¶

lower dimension geometry that bounds this geometry’s interior

The boundary of a polygon is a closed arcstring, the boundary of an arcstring is two endpoints (unless closed), and the boundary of a point (and a closed arcstring) is null.

property vertices: MultiSphericalPoint¶

property representative: SphericalPoint¶: point guaranteed to be within this geometry

property centroid: SphericalPoint¶: mean position of all possible points within this geometry

property convex_hull: SphericalPolygon | None¶: smallest convex polygon containing this geometry

property area: float¶: surface area of this geometry in square degrees

property length: float¶: angular length of this geometry in degrees

Whether this and the other geometry’s interiors are identical and the geometry types are the same.

For further explanation of Equals see ArcGIS Equals or Shapely’s object.equals.

Whether this and the other geometry share ANY point(s). If this geometries contains, is within, crosses, touches, or overlaps the other geometry, they intersect.

For further explanation of Intersects see ArcGIS Intersects or Shapely’s object.intersects.

Whether this and the other geometry share any vertices but do not overlap.

For further explanation of Touches see ArcGIS Touches or Shapely’s object.touches.

Whether this and the other geometry do NOT share ANY point(s).

Disjoint is the inverse of Intersects.

For further explanation of Disjoint see ArcGIS Disjoint or Shapely’s object.disjoint.

Whether this arcstring / polygon and the other arcstring / polygon share only SOME (not all) interior points, but do NOT overlap.

Two arcstrings cross if they meet at point(s) only, and at least one of the shared points is internal to both arcstrings. An arcstring and polygon cross if they share an arcstring on the interior of the polygon, which is NOT equal to the entire arcstring.

For further explanation of Crosses see ArcGIS Crosses or Shapely’s object.crosses.

Whether the other geometry covers this geometry AND the interiors share at least one point.

Within is the inverse of Contains.

For further explanation of Contains see ArcGIS Contains or Shapely’s object.contains.

Whether this geometry covers the other geometry AND the interiors share at least one point.

Contains is the inverse of Within.

For further explanation of Contains see ArcGIS Contains or Shapely’s object.contains.

Whether this and the other geometry are of the same geometry type, AND their intersection is also of the same geometry type BUT is not equal to either.

For further explanation of Overlaps see ArcGIS Overlaps or Shapely’s object.overlaps.

covers(other: SphericalPoint | MultiSphericalPoint | ArcString | MultiArcString | SphericalPolygon | MultiSphericalPolygon) → bool¶: Whether the other geometry is a subset of this geometry (every point of the other geometry is a point on the interior OR boundary of this geometry).

union(other: SphericalPoint | MultiSphericalPoint) → MultiSphericalPoint | None¶

union of points from this geometry and the other geometry

For further explanation of Union see Shapely’s object.union.

distance(other: SphericalPoint | MultiSphericalPoint | ArcString | MultiArcString | SphericalPolygon | MultiSphericalPolygon) → float¶: shortest great-circle distance over the sphere from any part of this geometry to another

any part of this geometry that is within another

NOTE: this function is NOT rigorous; it will ONLY return the lower order of geometry being compared and will NOT handle touching, colinear overlap, or degenerate cases

points in this object not in the other geometric object, and the points in the other not in this geometric object.

Splits this geometry into a multi-geometry, at the crossing with the other geometry.

For further explanation of Symmetric Difference see Shapely’s object.symmetric_difference.

class sphersgeo.MultiSphericalPolygon(polygons: list[SphericalPolygon])¶

collection of multiple polygons on the sphere

Create a MultiSphericalPolygon from a list of SphericalPolygon s:

from sphersgeo import SphericalPolygon, MultiSphericalPolygon

abc_def = MultiSphericalPolygon(
    [
        SphericalPolygon(
            [
                (0.43301270189221946, 0.75, 0.5),
                (0.5, 0.8660254037844386, 0.0),
                (0.75, -0.4330127018922193, -0.5),
            ]
        ),
        SphericalPolygon(
            [
                (0.0, 0.0, 1.0),
                (0.0, 0.0, -1.0),
                (1.0, 1.0, 0.0),
            ]
        ),
    ]
)

... or from the inputs required to make a list of SphericalPolygon s:

from sphersgeo import MultiSphericalPolygon

abc_def = MultiSphericalPolygon(
    [
        [
            (0.43301270189221946, 0.75, 0.5),
            (0.5, 0.8660254037844386, 0.0),
            (0.75, -0.4330127018922193, -0.5),
        ],
        [
            (0.0, 0.0, 1.0),
            (0.0, 0.0, -1.0),
            (1.0, 1.0, 0.0),
        ],
    ]
)

property boundary: MultiArcString¶

lower dimension geometry that bounds this geometry’s interior

The boundary of a polygon is a closed arcstring, the boundary of an arcstring is two endpoints (unless closed), and the boundary of a point (and a closed arcstring) is null.

property parts: list[SphericalPolygon]¶

append(other: SphericalPolygon)¶: append the geometry to this collection

extend(other: MultiSphericalPolygon)¶: extend this collection with geometries from the other collection

property vertices: MultiSphericalPoint¶

property representative: SphericalPoint¶: point guaranteed to be within this geometry

property centroid: SphericalPoint¶: mean position of all possible points within this geometry

property convex_hull: SphericalPolygon | None¶: smallest convex polygon containing this geometry

property area: float¶: surface area of this geometry in square degrees

property length: float¶: angular length of this geometry in degrees

Whether this and the other geometry’s interiors are identical and the geometry types are the same.

For further explanation of Equals see ArcGIS Equals or Shapely’s object.equals.

Whether this and the other geometry share ANY point(s). If this geometries contains, is within, crosses, touches, or overlaps the other geometry, they intersect.

For further explanation of Intersects see ArcGIS Intersects or Shapely’s object.intersects.

Whether this and the other geometry share any vertices but do not overlap.

For further explanation of Touches see ArcGIS Touches or Shapely’s object.touches.

Whether this and the other geometry do NOT share ANY point(s).

Disjoint is the inverse of Intersects.

For further explanation of Disjoint see ArcGIS Disjoint or Shapely’s object.disjoint.

Whether this arcstring / polygon and the other arcstring / polygon share only SOME (not all) interior points, but do NOT overlap.

For further explanation of Crosses see ArcGIS Crosses or Shapely’s object.crosses.

Whether the other geometry covers this geometry AND the interiors share at least one point.

Within is the inverse of Contains.

For further explanation of Contains see ArcGIS Contains or Shapely’s object.contains.

Whether this geometry covers the other geometry AND the interiors share at least one point.

Contains is the inverse of Within.

For further explanation of Contains see ArcGIS Contains or Shapely’s object.contains.

Whether this and the other geometry are of the same geometry type, AND their intersection is also of the same geometry type BUT is not equal to either.

For further explanation of Overlaps see ArcGIS Overlaps or Shapely’s object.overlaps.

covers(other: SphericalPoint | MultiSphericalPoint | ArcString | MultiArcString | SphericalPolygon | MultiSphericalPolygon) → bool¶: Whether the other geometry is a subset of this geometry (every point of the other geometry is a point on the interior OR boundary of this geometry).

union(other: SphericalPoint | MultiSphericalPoint) → MultiSphericalPoint | None¶

union of points from this geometry and the other geometry

For further explanation of Union see Shapely’s object.union.

distance(other: SphericalPoint | MultiSphericalPoint | ArcString | MultiArcString | SphericalPolygon | MultiSphericalPolygon) → float¶: shortest great-circle distance over the sphere from any part of this geometry to another

any part of this geometry that is within another

NOTE: this function is NOT rigorous; it will ONLY return the lower order of geometry being compared and will NOT handle touching, colinear overlap, or degenerate cases

points in this object not in the other geometric object, and the points in the other not in this geometric object.

Splits this geometry into a multi-geometry, at the crossing with the other geometry.

For further explanation of Symmetric Difference see Shapely’s object.symmetric_difference.

sphersgeo.from_wcs.polygon_from_wcs(wcs, steps: int | None = None) → sphersgeo.SphericalPolygon[source]¶

Infer the image footprint of a world coordinate system (WCS) from wcs.array_shape (and its intersection with wcs.bounding_box, if available).

Requires astropy to be installed.

Parameters¶

wcs: astropy.wcs.WCS | astropy.io.fits.Header | gwcs.WCS | str :: any WCS object that implements the common WCS API
steps: int :: The number of edges along each side of the footprint. More than 1 step captures WCS distortion along the edges. (Default value = 1)

Returns¶

sphersgeo.SphericalPolygon