pygplates.LocalCartesian
- class pygplates.LocalCartesian
Bases:
instance
A local cartesian coordinate system located at a point on the sphere.
Conversions between global geocentric cartesian and local cartesian North/East/Down coordinates are supported.
Also the spherical coordinates equivalent of local cartesian coordinates is supported as the triplet (magnitude, azimuth, inclination) that is related to the North/East/Down coordinate frame in the following way.For a 3D vector in the North/East/Down coordinate frame:magnitude is the length of the 3D vector,
azimuth is the angle (in radians) clockwise (East-wise) from North (in the range \([0, 2\pi]\)),
inclination is the angle (in radians) in the downward direction (eg, \(\frac{\pi}{2}\) if vector aligned with Down axis, \(-\frac{\pi}{2}\) if aligned with up direction and \(0\) if vector in tangent plane).
Local cartesians are equality (
==
,!=
) comparable (but not hashable - cannot be used as a key in adict
).- __init__(local_origin)
Create a local cartesian coordinate system at a point on the sphere.
- Parameters:
local_origin (
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)) – the origin of the local coordinate system
local_cartesian = pygplates.LocalCartesian(local_origin)
Methods
__init__
(local_origin)Create a local cartesian coordinate system at a point on the sphere.
convert_from_geocentric_to_magnitude_azimuth_inclination
(...)[staticmethod] Converts a geocentric vector (or vectors) to spherical coordinates in a local North/East/Down coordinate system (or systems).
[staticmethod] Converts a geocentric vector (or vectors) to a cartesian vector (or vectors) in a local North/East/Down coordinate system (or systems).
convert_from_magnitude_azimuth_inclination_to_geocentric
(...)[staticmethod] Converts a local North/East/Down tuple (or tuples) of spherical coordinates to a cartesian geocentric vector (or vectors).
[staticmethod] Converts a cartesian vector (or vectors) in a local North/East/Down coordinate system (or systems) to a geocentric vector (or vectors).
Converts a geocentric vector to a tuple of spherical coordinates in the local North/East/Down coordinate system.
Converts a geocentric vector to a local North/East/Down cartesian vector.
Converts local spherical coordinates to a geocentric vector.
Converts a local North/East/Down cartesian vector to a geocentric vector.
get_down
()Returns the Down coordinate axis.
get_east
()Returns the East coordinate axis.
Returns the North coordinate axis.
- static convert_from_geocentric_to_magnitude_azimuth_inclination(...)
[staticmethod] Converts a geocentric vector (or vectors) to spherical coordinates in a local North/East/Down coordinate system (or systems).
This function can be called in more than one way…
- convert_from_geocentric_to_magnitude_azimuth_inclination(local_origins, vectors)
Converts geocentric vectors to spherical coordinates in local North/East/Down coordinate systems located at local_origins.
- param local_origins:
sequence of origins (points) of local cartesian systems.
- type local_origins:
any sequence of
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vectors:
the geocentric vectors
- type vectors:
Any sequence of
Vector3D
or tuple (x,y,z)- returns:
list of (magnitude, azimuth, inclination)
- rtype:
list of tuple
- raises:
ValueError if the sequences local_origins and vectors have different lengths
Convert geocentric vectors to local spherical coordinates:
local_origins = [...] geocentric_vectors = [...] local_coords = pygplates.LocalCartesian.convert_from_geocentric_to_magnitude_azimuth_inclination( local_origins, geocentric_vectors)
- convert_from_geocentric_to_magnitude_azimuth_inclination(local_origin, vector)
Converts a geocentric vector to a tuple of spherical coordinates in the local North/East/Down coordinate system located at local_origin.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vector:
the geocentric vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
tuple of (magnitude, azimuth, inclination)
- rtype:
tuple
Convert a geocentric vector to the local North/East/Down spherical coordinate system located at latitude/longitude (0, 0) on the globe:
magnitude, azimuth, inclination = pygplates.LocalCartesian.convert_from_geocentric_to_magnitude_azimuth_inclination( (0, 0), geocentric_vector)
- convert_from_geocentric_to_magnitude_azimuth_inclination(local_origin, x, y, z)
Converts the geocentric vector (x, y, z) to a tuple of spherical coordinates in the local North/East/Down coordinate system located at local_origin.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param x:
the x component of the geocentric vector
- type x:
float
- param y:
the y component of the geocentric vector
- type y:
float
- param z:
the z component of the geocentric vector
- type z:
float
- returns:
tuple of (magnitude, azimuth, inclination)
- rtype:
tuple
Convert the geocentric vector (2, 1, 0) to the local North/East/Down spherical coordinate system located at latitude/longitude (0, 0) on the globe:
magnitude, azimuth, inclination = pygplates.LocalCartesian.convert_from_geocentric_to_magnitude_azimuth_inclination( (0,0), 2, 1, 0)
- static convert_from_geocentric_to_north_east_down(...)
[staticmethod] Converts a geocentric vector (or vectors) to a cartesian vector (or vectors) in a local North/East/Down coordinate system (or systems).
This function can be called in more than one way…
- convert_from_geocentric_to_north_east_down(local_origins, vectors)
Converts a sequence of geocentric vectors to a sequence of cartesian vectors in local North/East/Down coordinate systems located at local_origins.
- param local_origins:
sequence of origins (points) of local cartesian systems.
- type local_origins:
Any sequence of
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vectors:
the geocentric vectors
- type vectors:
Any sequence of
Vector3D
or tuple (x,y,z)- returns:
list of local cartesian North/East/Down vectors
- rtype:
list of
Vector3D
- raises:
ValueError if the sequences local_origins and vectors have different lengths
Convert geocentric vectors to local cartesian vectors:
local_origins = [...] geocentric_vectors = [...] local_vectors = pygplates.LocalCartesian.convert_from_geocentric_to_north_east_down( local_origins, geocentric_vectors)
- convert_from_geocentric_to_north_east_down(local_origin, vector)
Converts a geocentric vector to a cartesian vector in the local North/East/Down coordinate system located at local_origin.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vector:
the geocentric vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
local cartesian North/East/Down vector
- rtype:
Convert a geocentric vector to the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe:
local_vector = pygplates.LocalCartesian.convert_from_geocentric_to_north_east_down( (0, 0), geocentric_vector)
- convert_from_geocentric_to_north_east_down(local_origin, x, y, z)
Converts the geocentric vector (x, y, z) to a cartesian vector in the local North/East/Down coordinate system located at local_origin.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param x:
the x component of the geocentric vector
- type x:
float
- param y:
the y component of the geocentric vector
- type y:
float
- param z:
the z component of the geocentric vector
- type z:
float
- returns:
local cartesian North/East/Down vector
- rtype:
Convert the geocentric vector (2, 1, 0) to the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe:
local_vector = pygplates.LocalCartesian.convert_from_geocentric_to_north_east_down( (0,0), 2, 1, 0)
- static convert_from_magnitude_azimuth_inclination_to_geocentric(...)
[staticmethod] Converts a local North/East/Down tuple (or tuples) of spherical coordinates to a cartesian geocentric vector (or vectors).
This function can be called in more than one way…
- convert_from_magnitude_azimuth_inclination_to_geocentric(local_origins, local_coordinates)
Converts a sequence of local North/East/Down tuples of spherical coordinates located at local_origins to a sequence of geocentric vectors.
- param local_origins:
sequence of origins (points) of local cartesian systems.
- type local_origins:
any sequence of
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param local_coordinates:
sequence of local spherical coordinates (magnitude, azimuth, inclination)
- type local_coordinates:
Any sequence of (float, float, float) tuples
- returns:
list of geocentric vectors
- rtype:
list of
Vector3D
- raises:
ValueError if the sequences local_origins and local_coordinates have different lengths
Convert local spherical coordinates to geocentric vectors:
local_origins = [...] local_coords = [...] geocentric_vectors = pygplates.LocalCartesian.convert_from_magnitude_azimuth_inclination_to_geocentric( local_origins, local_coords)
- convert_from_magnitude_azimuth_inclination_to_geocentric(local_origin, local_coordinate)
Converts a local North/East/Down tuple of spherical coordinates located at local_origin to a geocentric vector.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param local_coordinate:
the local spherical coordinates (magnitude, azimuth, inclination)
- type local_coordinate:
sequence (such as list or tuple) of (float,float,float)
- returns:
geocentric vector
- rtype:
Convert a local vector of unit magnitude aligned with the local East axis to a geocentric vector:
geocentric_vector = pygplates.LocalCartesian.convert_from_magnitude_azimuth_inclination_to_geocentric( (0, 0), (1, 0.5 * math.pi, 0))
- convert_from_magnitude_azimuth_inclination_to_geocentric(local_origin, magnitude, azimuth, inclination)
Converts local North/East/Down spherical coordinates located at local_origin to a geocentric vector.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param magnitude:
the length of the local cartesian vector
- type magnitude:
float
- param azimuth:
the angle (in radians) clockwise (East-wise) from North (in the range \([0, 2\pi]\))
- type azimuth:
float
- param inclination:
the angle (in radians) in the downward direction (eg, \(\frac{\pi}{2}\) if vector aligned with Down axis, \(-\frac{\pi}{2}\) if aligned with up direction and \(0\) if vector in tangent plane)
- type inclination:
float
- returns:
geocentric vector
- rtype:
Convert a local vector of unit magnitude aligned with the local East axis to a geocentric vector:
geocentric_vector = pygplates.LocalCartesian.convert_from_magnitude_azimuth_inclination_to_geocentric( (0,0), 1, 0.5 * math.pi, 0)
- static convert_from_north_east_down_to_geocentric(...)
[staticmethod] Converts a cartesian vector (or vectors) in a local North/East/Down coordinate system (or systems) to a geocentric vector (or vectors).
This function can be called in more than one way…
- convert_from_north_east_down_to_geocentric(local_origins, vectors)
Converts a cartesian vector in the local North/East/Down coordinate system located at local_origin to a geocentric vector.
- param local_origins:
sequence of origins (points) of local cartesian systems.
- type local_origins:
any sequence of
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vectors:
the local cartesian vectors
- type vectors:
Any sequence of
Vector3D
or tuple (x,y,z)- returns:
list of geocentric vectors
- rtype:
list of
Vector3D
- raises:
ValueError if the sequences local_origins and vectors have different lengths
Convert local cartesian vectors to geocentric vectors:
local_origins = [...] local_vectors = [...] geocentric_vectors = pygplates.LocalCartesian.convert_from_north_east_down_to_geocentric( local_origins, local_vectors)
- convert_from_north_east_down_to_geocentric(local_origin, vector)
Converts a cartesian vector in the local North/East/Down coordinate system located at local_origin to a geocentric vector.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param vector:
the local cartesian vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
geocentric vector
- rtype:
Convert a local cartesian vector in a local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe to a geocentric vector:
geocentric_vector = pygplates.LocalCartesian.convert_from_north_east_down_to_geocentric( (0, 0), geocentric_vector)
- convert_from_north_east_down_to_geocentric(local_origin, x, y, z)
Converts a cartesian vector (x, y, z) in the local North/East/Down coordinate system located at local_origin to a geocentric vector.
- param local_origin:
origin of local cartesian system.
- type local_origin:
PointOnSphere
orLatLonPoint
or tuple (latitude,longitude), in degrees, or tuple (x,y,z)- param x:
the x component of the local cartesian vector
- type x:
float
- param y:
the y component of the local cartesian vector
- type y:
float
- param z:
the z component of the local cartesian vector
- type z:
float
- returns:
geocentric vector
- rtype:
Convert the local cartesian vector (2, 1, 0) in the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe to a geocentric vector:
geocentric_vector = pygplates.LocalCartesian.convert_from_north_east_down_to_geocentric( (0,0), 2, 1, 0)
- from_geocentric_to_magnitude_azimuth_inclination(...)
Converts a geocentric vector to a tuple of spherical coordinates in the local North/East/Down coordinate system.
This method can be called in more than one way…
- from_geocentric_to_magnitude_azimuth_inclination(vector)
Converts the geocentric vector to a local North/East/Down tuple of spherical coordinates.
- param vector:
the geocentric vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
tuple of (magnitude, azimuth, inclination)
- rtype:
tuple
Convert a geocentric vector to the local North/East/Down spherical coordinate system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) magnitude, azimuth, inclination = local_cartesian.from_geocentric_to_magnitude_azimuth_inclination(geocentric_vector)
- from_geocentric_to_magnitude_azimuth_inclination(x, y, z)
Converts the geocentric vector (x, y, z) to a local North/East/Down tuple of spherical coordinates.
- param x:
the x component of the geocentric vector
- type x:
float
- param y:
the y component of the geocentric vector
- type y:
float
- param z:
the z component of the geocentric vector
- type z:
float
- returns:
tuple of (magnitude, azimuth, inclination)
- rtype:
tuple
Convert the geocentric vector (2, 1, 0) to the local North/East/Down spherical coordinate system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) magnitude, azimuth, inclination = local_cartesian.from_geocentric_to_magnitude_azimuth_inclination(2, 1, 0)
- from_geocentric_to_north_east_down(...)
Converts a geocentric vector to a local North/East/Down cartesian vector.
This method can be called in more than one way…
- from_geocentric_to_north_east_down(vector)
Converts the geocentric vector to a local North/East/Down cartesian vector.
- param vector:
the geocentric vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
local cartesian North/East/Down vector
- rtype:
Convert a geocentric vector to the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) local_vector = local_cartesian.from_geocentric_to_north_east_down(geocentric_vector)
- from_geocentric_to_north_east_down(x, y, z)
Converts the geocentric vector (x, y, z) to a local North/East/Down cartesian vector.
- param x:
the x component of the geocentric vector
- type x:
float
- param y:
the y component of the geocentric vector
- type y:
float
- param z:
the z component of the geocentric vector
- type z:
float
- returns:
local cartesian North/East/Down vector
- rtype:
Convert the geocentric vector (2, 1, 0) to the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) local_vector = local_cartesian.from_geocentric_to_north_east_down(2, 1, 0)
- from_magnitude_azimuth_inclination_to_geocentric(...)
Converts local spherical coordinates to a geocentric vector.
This method can be called in more than one way…
- from_magnitude_azimuth_inclination_to_geocentric(local_coordinate)
Converts a local North/East/Down tuple of spherical coordinates to a geocentric vector.
- param local_coordinate:
the local spherical coordinates (magnitude, azimuth, inclination)
- type local_coordinate:
sequence (such as list or tuple) of (float,float,float)
- returns:
geocentric vector
- rtype:
Convert a local vector of unit magnitude aligned with the local East axis to a geocentric vector:
local_cartesian = pygplates.LocalCartesian((0,0)) geocentric_vector = local_cartesian.from_magnitude_azimuth_inclination_to_geocentric( (1, 0.5 * math.pi, 0))
- from_magnitude_azimuth_inclination_to_geocentric(magnitude, azimuth, inclination)
Converts local North/East/Down spherical coordinates to a geocentric vector.
- param magnitude:
the length of the local cartesian vector
- type magnitude:
float
- param azimuth:
the angle (in radians) clockwise (East-wise) from North (in the range \([0, 2\pi]\))
- type azimuth:
float
- param inclination:
the angle (in radians) in the downward direction (eg, \(\frac{\pi}{2}\) if vector aligned with Down axis, \(-\frac{\pi}{2}\) if aligned with up direction and \(0\) if vector in tangent plane)
- type inclination:
float
- returns:
geocentric vector
- rtype:
Convert a local vector of unit magnitude aligned with the local East axis to a geocentric vector:
local_cartesian = pygplates.LocalCartesian((0,0)) geocentric_vector = local_cartesian.from_magnitude_azimuth_inclination_to_geocentric( 1, 0.5 * math.pi, 0)
- from_north_east_down_to_geocentric(...)
Converts a local North/East/Down cartesian vector to a geocentric vector.
This method can be called in more than one way…
- from_north_east_down_to_geocentric(vector)
Converts the local North/East/Down cartesian vector to a geocentric vector.
- param vector:
the local cartesian vector
- type vector:
Vector3D
, or sequence (such as list or tuple) of (float,float,float)- returns:
geocentric vector
- rtype:
Convert a cartesian vector in the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe to a geocentric vector:
local_cartesian = pygplates.LocalCartesian((0,0)) geocentric_vector = local_cartesian.from_north_east_down_to_geocentric(local_cartesian_vector)
- from_north_east_down_to_geocentric(x, y, z)
Converts the local North/East/Down cartesian vector (x, y, z) to a geocentric vector.
- param x:
the x component of the local cartesian vector
- type x:
float
- param y:
the y component of the local cartesian vector
- type y:
float
- param z:
the z component of the local cartesian vector
- type z:
float
- returns:
geocentric vector
- rtype:
Convert the local cartesian vector (2, 1, 0) in the local North/East/Down coordinate system located at latitude/longitude (0, 0) on the globe to a geocentric vector:
local_cartesian = pygplates.LocalCartesian((0,0)) geocentric_vector = local_cartesian.from_north_east_down_to_geocentric(2, 1, 0)
- get_down()
Returns the Down coordinate axis.
- Return type:
The Down axis points at the centre of the globe. It has unit magnitude.
Get the Down axis of the local cartesian system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) down = local_cartesian.get_down()
- get_east()
Returns the East coordinate axis.
- Return type:
The East axis is the tangential vector (to the unit globe) that is most Eastward pointing. It has unit magnitude.
Get the East axis of the local cartesian system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) east = local_cartesian.get_east()
- get_north()
Returns the North coordinate axis.
- Return type:
The North axis is the tangential vector (to the unit globe) that is most Northward pointing. It has unit magnitude.
Get the North axis of the local cartesian system located at latitude/longitude (0, 0) on the globe:
local_cartesian = pygplates.LocalCartesian((0,0)) north = local_cartesian.get_north()