Spherical Points in Python¶

class sphersgeo.SphericalPoint(point: tuple[float, float, float] | numpy.ndarray[tuple[numpy.typing.Literal[3]], numpy.dtype[numpy.float64]] | tuple[float, float] | list[float])¶

single point on the sphere, represented internally as a 3-dimensional Cartesian point (X, Y, Z) with origin at the center of the unit sphere

Create a SphericalPoint from angular coordinates (longitude, latitude):

from sphersgeo import SphericalPoint

a = SphericalPoint((60.0, 30.0))
b = SphericalPoint((60.0, 0.0))
c = SphericalPoint((-30.0, -30.0))

... or Cartesian coordinates (X, Y, Z):

from sphersgeo import SphericalPoint

a = SphericalPoint((0.43301270189221946, 0.75, 0.5))
b = SphericalPoint((0.5, 0.8660254037844386, 0.0))
c = SphericalPoint((0.75, -0.4330127018922193, -0.5))
d = SphericalPoint((0.0, 0.0, 1.0))
e = SphericalPoint((0.0, 0.0, -1.0))

property xyz: tuple[float, float, float]¶: coordinates of this point as X, Y, and Z from the center of the sphere

property lonlat: tuple[float, float]¶: coordinates of this point as longitude and latitude

property antipode: SphericalPoint¶: antipodal point on the opposite side of the sphere

two_arc_angle(a: SphericalPoint, c: SphericalPoint) → float¶

given three points on the sphere:

a

b (this point)

c

retrieves the turning angle, in radians, at b formed by arcs ab and bc

colinear(a: SphericalPoint, b: SphericalPoint) → bool¶: whether this point lies on an arc between two other points

is_clockwise_turn(a: SphericalPoint, b: SphericalPoint) → bool¶: whether the angle formed between this point and two other points is a clockwise turn

interpolate_points(end: SphericalPoint, n: int) → MultiSphericalPoint¶: create n number of equally-spaced points on the arc between this point and another point

property vector_length: float¶: length of the underlying xyz vector

vector_cross(other: SphericalPoint) → SphericalPoint¶: cross product of this xyz vector with another xyz vector

vector_dot(other: SphericalPoint) → float¶: dot product of this xyz vector with another xyz vector

vector_rotate_around(other: SphericalPoint, theta: float) → SphericalPoint¶: rotate this xyz vector by theta radians around another xyz vector

to(other: SphericalPoint) → ArcString¶: arc to another point

property boundary: None¶

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.MultiSphericalPoint(points: list[tuple[float, float, float]] | list[SphericalPoint] | tuple[float, float] | numpy.ndarray[tuple[Any, numpy.typing.Literal[3]], numpy.dtype[numpy.float64]])¶

collection of multiple points on the sphere

Create a MultiSphericalPoint from a list of SphericalPoint s:

from sphersgeo import SphericalPoint, MultiSphericalPoint

a = SphericalPoint((60.0, 30.0))
b = SphericalPoint((60.0, 0.0))
c = SphericalPoint((0.75, -0.4330127018922193, -0.5))

abc = MultiSphericalPoint([a, b, c])

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

from sphersgeo import MultiSphericalPoint

abc = MultiSphericalPoint(
    [(60.0, 30.0), (60.0, 0.0), (0.75, -0.4330127018922193, -0.5)]
)

... or from a numpy.ndarray of shape Nx2 (longitude, latitude) or Nx3 (X, Y, Z):

import numpy as np
from sphersgeo import MultiSphericalPoint

abc = MultiSphericalPoint(np.array([(60.0, 30.0), (60.0, 0.0), (-30.0, -30.0)]))
abc = MultiSphericalPoint(
    np.array(
        [
            (0.43301270189221946, 0.75, 0.5),
            (0.5, 0.8660254037844386, 0.0),
            (0.75, -0.4330127018922193, -0.5),
        ]
    )
)

property xyzs: numpy.ndarray[tuple[Any, numpy.typing.Literal[3]], numpy.dtype[numpy.float64]]¶: coordinates of these points as X, Y, and Z (Nx3 numpy.ndarray)

property lonlats: numpy.ndarray[tuple[Any, numpy.typing.Literal[2]], numpy.dtype[numpy.float64]]¶: coordinates of these points as longitude and latitude (Nx2 numpy.ndarray)

nearest(other: SphericalPoint) → tuple[SphericalPoint, float]¶: retrieve the nearest of these points to the given point, along with the normalized 3D Cartesian distance to that point across the unit sphere

property vectors_lengths: numpy.ndarray[tuple[Any], numpy.dtype[numpy.float64]]¶: lengths of the underlying (X, Y, Z) vectors

property parts: list[SphericalPoint]¶

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

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

property boundary: None¶

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.

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.