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