pygplates.LocalCartesian

class pygplates.LocalCartesian

Bases: Boost.Python.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 (from 0 to 2*PI),
inclination is the angle (in radians) in the downward direction (eg, PI/2 if vector aligned with Down axis, -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 a dict).

__init__(local_origin)

Create a local cartesian coordinate system at a point on the sphere.

Parameters: local_origin (PointOnSphere or LatLonPoint 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).
`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).
`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).
`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).
`from_geocentric_to_magnitude_azimuth_inclination`(...)	Converts a geocentric vector to a tuple of spherical coordinates in the local North/East/Down coordinate system.
`from_geocentric_to_north_east_down`(...)	Converts a geocentric vector to a local North/East/Down cartesian vector.
`from_magnitude_azimuth_inclination_to_geocentric`(...)	Converts local spherical coordinates to a geocentric vector.
`from_north_east_down_to_geocentric`(...)	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.
`get_north`()	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 or LatLonPoint 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 or LatLonPoint 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 or LatLonPoint 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 or LatLonPoint 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 or LatLonPoint 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: Vector3D

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 or LatLonPoint 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: Vector3D

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 or LatLonPoint 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 or LatLonPoint 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: Vector3D

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 or LatLonPoint 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 (from 0 to 2*PI)
type azimuth: float
param inclination: the angle (in radians) in the downward direction (eg, PI/2 if vector aligned with Down axis, -PI/2 if aligned with up direction and 0 if vector in tangent plane)
type inclination: float
returns: geocentric vector
rtype: Vector3D

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 or LatLonPoint 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 or LatLonPoint 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: Vector3D

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 or LatLonPoint 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: Vector3D

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: Vector3D

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: Vector3D

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: Vector3D

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: Vector3D

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 (from 0 to 2*PI)
type azimuth: float
param inclination: the angle (in radians) in the downward direction (eg, PI/2 if vector aligned with Down axis, -PI/2 if aligned with up direction and 0 if vector in tangent plane)
type inclination: float
returns: geocentric vector
rtype: Vector3D

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: Vector3D

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: Vector3D

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: Vector3D

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: Vector3D

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: Vector3D

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