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