pygplates.PointOnSphere

class pygplates.PointOnSphere

Bases: pygplates.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

__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).

New 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())