pygplates.PointOnSphere

class pygplates.PointOnSphere

Bases: GeometryOnSphere

Represents a point on the surface of the unit length sphere in 3D cartesian coordinates.

Points are equality (==, !=) comparable (but not hashable - cannot be used as a key in a dict). Two points are considered equal if their coordinates match within a very small numerical epsilon that accounts for the limits of floating-point precision. Note that usually two points will only compare equal if they are the same point or created from the exact same input data. If two points are generated in two different ways (eg, two different processing paths) they will most likely not compare equal even if mathematically they should be identical.

Note

Since a PointOnSphere is immutable it contains no operations or methods that modify its state.

Convenience class static data are available for the North and South poles:

• pygplates.PointOnSphere.north_pole

• pygplates.PointOnSphere.south_pole

A PointOnSphere can also be pickled.

Changed in version 0.42: Added pickle support.

__init__(...)

A PointOnSphere object can be constructed in more than one way…

__init__(point)

Create a PointOnSphere instance from a (x,y,z) or (latitude,longitude) point.

param point:

(x,y,z) point, or (latitude,longitude) point (in degrees)

type point:

PointOnSphere or LatLonPoint or tuple (float,float,float) or tuple (float,float)

raises:

InvalidLatLonError if latitude or longitude is invalid

raises:

ViolatedUnitVectorInvariantError if (x,y,z) is not unit magnitude

The following example shows a few different ways to use this method:

point = pygplates.PointOnSphere((x,y,z))
point = pygplates.PointOnSphere([x,y,z])
point = pygplates.PointOnSphere(numpy.array([x,y,z]))
point = pygplates.PointOnSphere(pygplates.LatLonPoint(latitude,longitude))
point = pygplates.PointOnSphere((latitude,longitude))
point = pygplates.PointOnSphere([latitude,longitude])
point = pygplates.PointOnSphere(numpy.array([latitude,longitude]))
point = pygplates.PointOnSphere(pygplates.PointOnSphere(x,y,z))

__init__(latitude, longitude)

Create a PointOnSphere instance from a latitude and longitude.

param latitude:

the latitude (in degrees)

type latitude:

float

param longitude:

the longitude (in degrees)

type longitude:

float

raises:

InvalidLatLonError if latitude or longitude is invalid

Note

latitude must satisfy LatLonPoint.is_valid_latitude() and longitude must satisfy LatLonPoint.is_valid_longitude(), otherwise InvalidLatLonError will be raised.

point = pygplates.PointOnSphere(latitude, longitude)

__init__(x, y, z, [normalise=False])

Create a PointOnSphere instance from a 3D cartesian coordinate consisting of floating-point coordinates x, y and z.

param x:

the x component of the 3D unit vector

type x:

float

param y:

the y component of the 3D unit vector

type y:

float

param z:

the z component of the 3D unit vector

type z:

float

param normalise:

whether to normalise (to unit-length magnitude) the vector (x,y,z) - defaults to False

type normalise:

bool

raises:

ViolatedUnitVectorInvariantError if normalise is False and the resulting vector does not have unit magnitude

raises:

UnableToNormaliseZeroVectorError if normalise is True and the resulting vector is (0,0,0) (ie, has zero magnitude)

NOTE: If the length of the 3D vector (x,y,z) is not 1.0 then you should set normalise to True (to normalise the vector components such that the 3D vector has unit magnitude). Otherwise if (x,y,z) is not unit magnitude then ViolatedUnitVectorInvariantError is raised.

# If you know that (x,y,z) has unit magnitude (is on the unit globe).
point = pygplates.PointOnSphere(x, y, z)

# If (x,y,z) might not be on the unit globe.
point = pygplates.PointOnSphere(x, y, z, normalise=True)

Methods

__init__(...)	A PointOnSphere object can be constructed in more than one way...
clone()	Create a duplicate of this geometry (derived) instance.
distance(geometry1, geometry2, ...)	[staticmethod] Returns the (minimum) distance between two geometries (in radians).
get_centroid()	Simply returns this point.
get_points()	Returns a read-only sequence of points in this geometry.
get_x()	Returns the x coordinate.
get_y()	Returns the y coordinate.
get_z()	Returns the z coordinate.
to_lat_lon()	Returns the tuple (latitude,longitude) in degrees.
to_lat_lon_array()	Returns the sequence of points, in this geometry, as a numpy array of (latitude,longitude) pairs (in degrees).
to_lat_lon_list()	Returns the sequence of points, in this geometry, as (latitude,longitude) tuples (in degrees).
to_lat_lon_point()	Returns the (latitude,longitude) equivalent of this PointOnSphere.
to_lat_lon_point_list()	Returns the sequence of points, in this geometry, as lat lon points.
to_xyz()	Returns the cartesian coordinates as the tuple (x,y,z).
to_xyz_array()	Returns the sequence of points, in this geometry, as a numpy array of (x,y,z) triplets.
to_xyz_list()	Returns the sequence of points, in this geometry, as (x,y,z) cartesian coordinate tuples.

Attributes

north_pole
south_pole

get_centroid()

Simply returns this point.

Return type:

PointOnSphere

Note

This method is only here so that get_centroid() can be called for all geometry types (points, multi-points, polylines and polygons).

Added in version 0.36.

get_x()

Returns the x coordinate.

Return type:

float

get_y()

Returns the y coordinate.

Return type:

float

get_z()

Returns the z coordinate.

Return type:

float

to_lat_lon()

Returns the tuple (latitude,longitude) in degrees.

Return type:

the tuple (float, float)

latitude, longitude = point.to_lat_lon()

This is similar to LatLonPoint.to_lat_lon().

to_lat_lon_point()

Returns the (latitude,longitude) equivalent of this PointOnSphere.

Return type:

LatLonPoint

to_xyz()

Returns the cartesian coordinates as the tuple (x,y,z).

Return type:

the tuple (float,float,float)

x, y, z = point.to_xyz()

This is also useful for performing vector dot and cross products:

dot_product = pygplates.Vector3D.dot(point1.to_xyz(), point2.to_xyz())
cross_product = pygplates.Vector3D.cross(point1.to_xyz(), point2.to_xyz())