pygplates.Vector3D

class pygplates.Vector3D

Bases: instance

Represents a vector in 3D cartesian coordinates. Vectors are equality (==, !=) comparable (but not hashable - cannot be used as a key in a dict).

The following operations can be used:

Operation	Result
`-vector`	Creates a new Vector3D that points in the opposite direction to vector
`scalar * vector`	Creates a new Vector3D from vector with each component of (x,y,z) multiplied by scalar
`vector * scalar`	Creates a new Vector3D from vector with each component of (x,y,z) multiplied by scalar
`vector1 + vector2`	Creates a new Vector3D that is the sum of vector1 and vector2
`vector1 - vector2`	Creates a new Vector3D that is vector2 subtracted from vector1

For example, to interpolate between two vectors:

vector1 = pygplates.Vector3D(...)
vector2 = pygplates.Vector3D(...)
vector_interp = t * vector1 + (1-t) * vector2

Convenience class static data are available for the zero vector (all zero components) and the x, y and z axes (unit vectors in the respective directions):

pygplates.Vector3D.zero
pygplates.Vector3D.x_axis
pygplates.Vector3D.y_axis
pygplates.Vector3D.z_axis

For example, to create a vector from a triplet of axis basis weights (triplet of scalars):

vector = (
    x_weight * pygplates.Vector3D.x_axis +
    y_weight * pygplates.Vector3D.y_axis +
    z_weight * pygplates.Vector3D.z_axis)

A Vector3D can also be pickled.

Changed in version 0.42: Added pickle support.

__init__(...)

A Vector3D object can be constructed in more than one way…

__init__(x, y, z)

Construct a Vector3D instance from 3D cartesian coordinates consisting of the floating-point numbers x, y and z.

param x:: the x component of the 3D vector
type x:: float
param y:: the y component of the 3D vector
type y:: float
param z:: the z component of the 3D vector
type z:: float

vector = pygplates.Vector3D(x, y, z)

__init__(vector)

Create a Vector3D instance from an (x,y,z) sequence (or Vector3D).

param point:: (x,y,z) vector
type point:: sequence, such as list or tuple, of (float,float,float), or Vector3D

The following example shows a few different ways to use this method:

vector = pygplates.Vector3D((x,y,z))
vector = pygplates.Vector3D([x,y,z])
vector = pygplates.Vector3D(numpy.array([x,y,z]))
vector = pygplates.Vector3D(pygplates.Vector3D(x,y,z))

__init__()

Construct a zero Vector3D.

vector = pygplates.Vector3D()

Note

Alternatively you can use vector = pygplates.Vector3D.zero.

Added in version 0.43.

Methods

`__init__`(...)	A Vector3D object can be constructed in more than one way...
`angle_between`(vector1, vector2)	[staticmethod] Returns the angle between two vectors (in radians).
`create_normalised`(...)	[staticmethod] Returns a new vector that is a normalised (unit length) version of another.
`create_normalized`(...)	[staticmethod] See `create_normalised()`.
`cross`(vector1, vector2)	[staticmethod] Returns the cross product of two vectors.
`dot`(vector1, vector2)	[staticmethod] Returns the dot product of two vectors.
`get_magnitude`()	Returns the magnitude, or length, of the vector.
`get_x`()	Returns the x coordinate.
`get_y`()	Returns the y coordinate.
`get_z`()	Returns the z coordinate.
`is_zero_magnitude`()	Returns `True` if the magnitude of this vector is zero.
`to_normalised`()	Returns a new vector that is a normalised (unit length) version of this vector.
`to_normalized`()	See `to_normalised()`.
`to_xyz`()	Returns the cartesian coordinates as the tuple (x,y,z).

Attributes

`x_axis`
`y_axis`
`z_axis`
`zero`

static angle_between(vector1, vector2)

[staticmethod] Returns the angle between two vectors (in radians).

Parameters:

vector1 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the first vector
vector2 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the second vector

Return type:

float

Raises:

UnableToNormaliseZeroVectorError if either vector1 or vector2 is (0,0,0) (ie, has zero magnitude)

Note that the angle between a vector (vec) and its opposite (-vec) is math.pi (and not zero) even though both vectors are parallel. This is because they point in opposite directions.

The following example shows a few different ways to use this function:

vec1 = pygplates.Vector3D(1.1, 2.2, 3.3)
vec2 = pygplates.Vector3D(-1.1, -2.2, -3.3)
angle = pygplates.Vector3D.angle_between(vec1, vec2)

angle = pygplates.Vector3D.angle_between((1.1, 2.2, 3.3), (-1.1, -2.2, -3.3))

angle = pygplates.Vector3D.angle_between(vec1, (-1.1, -2.2, -3.3))

angle = pygplates.Vector3D.angle_between((1.1, 2.2, 3.3), vec2)

This function is the equivalent of:

if not vector1.is_zero_magnitude() and not vector2.is_zero_magnitude():
    angle_between = math.acos(
        pygplates.Vector3D.dot(vector1.to_normalised(), vector2.to_normalised()))
else:
    raise pygplates.UnableToNormaliseZeroVectorError

static create_normalised(...)

[staticmethod] Returns a new vector that is a normalised (unit length) version of another.

This function can be called in more than one way…

create_normalised(xyz)

Returns a new vector that is a normalised (unit length) version of vector.

param xyz:: the vector (x,y,z) components
type xyz:: sequence (such as list or tuple) of (float,float,float), or Vector3D
rtype:: Vector3D
raises:: UnableToNormaliseZeroVectorError if xyz is (0,0,0) (ie, has zero magnitude)

normalised_vector = pygplates.Vector3D.create_normalised((2, 1, 0))

This function is similar to to_normalised() but is typically used when you don’t have a Vector3D object to call to_normalised() on. Such as pygplates.Vector3D.create_normalised((2, 1, 0)).

create_normalised(x, y, z)

Returns a new vector that is a normalised (unit length) version of vector (x, y, z).

param x:: the x component of the 3D vector
type x:: float
param y:: the y component of the 3D vector
type y:: float
param z:: the z component of the 3D vector
type z:: float
rtype:: Vector3D
raises:: UnableToNormaliseZeroVectorError if (x,y,z) is (0,0,0) (ie, has zero magnitude)

normalised_vector = pygplates.Vector3D.create_normalised(2, 1, 0)

This function is similar to the create_normalised function above but takes three arguments x, y and z instead of a single argument (such as a tuple or list).

static create_normalized(...): [staticmethod] See create_normalised().

static cross(vector1, vector2)

[staticmethod] Returns the cross product of two vectors.

Parameters:

vector1 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the first vector
vector2 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the second vector

Return type:

Vector3D

The following example shows a few different ways to use this function:

vec1 = pygplates.Vector3D(1.1, 2.2, 3.3)
vec2 = pygplates.Vector3D(-1.1, -2.2, -3.3)
cross_product = pygplates.Vector3D.cross(vec1, vec2)

cross_product = pygplates.Vector3D.cross((1.1, 2.2, 3.3), (-1.1, -2.2, -3.3))

cross_product = pygplates.Vector3D.cross(vec1, (-1.1, -2.2, -3.3))

cross_product = pygplates.Vector3D.cross((1.1, 2.2, 3.3), vec2)

The cross product is the equivalent of:

cross_product = pygplates.Vector3D(
    vector1.get_y() * vector2.get_z() - vector1.get_z() * vector2.get_y(),
    vector1.get_z() * vector2.get_x() - vector1.get_x() * vector2.get_z(),
    vector1.get_x() * vector2.get_y() - vector1.get_y() * vector2.get_x())

static dot(vector1, vector2)

[staticmethod] Returns the dot product of two vectors.

Parameters:

vector1 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the first vector
vector2 (Vector3D, or sequence (such as list or tuple) of (float,float,float)) – the second vector

Return type:

float

The following example shows a few different ways to use this function:

vec1 = pygplates.Vector3D(1.1, 2.2, 3.3)
vec2 = pygplates.Vector3D(-1.1, -2.2, -3.3)
dot_product = pygplates.Vector3D.dot(vec1, vec2)

dot_product = pygplates.Vector3D.dot((1.1, 2.2, 3.3), (-1.1, -2.2, -3.3))

dot_product = pygplates.Vector3D.dot(vec1, (-1.1, -2.2, -3.3))

dot_product = pygplates.Vector3D.dot((1.1, 2.2, 3.3), vec2)

The dot product is the equivalent of:

dot_product = (
    vector1.get_x() * vector2.get_x() +
    vector1.get_y() * vector2.get_y() +
    vector1.get_z() * vector2.get_z())

get_magnitude()

Returns the magnitude, or length, of the vector.

Return type:: float

magnitude = vector.get_magnitude()

The magnitude is the equivalent of:

magnitude = math.sqrt(
    vector.get_x() * vector.get_x() +
    vector.get_y() * vector.get_y() +
    vector.get_z() * vector.get_z())

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

is_zero_magnitude()

Returns True if the magnitude of this vector is zero.

Return type:: bool

This method will also return True for tiny, non-zero magnitudes that would cause to_normalised() to raise UnableToNormaliseZeroVectorError.

to_normalised()

Returns a new vector that is a normalised (unit length) version of this vector.

Return type:: Vector3D
Raises:: UnableToNormaliseZeroVectorError if this vector is (0,0,0) (ie, has zero magnitude)

If a vector is not zero magnitude then it can return a normalised version of itself:

if not vector.is_zero_magnitude():
    normalised_vector = vector.to_normalised()

NOTE: This does not normalise this vector. Instead it returns a new vector object that is the equivalent of this vector but has a magnitude of 1.0.

This function is the equivalent of:

if not vector.is_zero_magnitude():
    scale = 1.0 / vector.get_magnitude()
    normalised_vector = pygplates.Vector3D(
        scale * vector.get_x(),
        scale * vector.get_y(),
        scale * vector.get_z())
else:
    raise pygplates.UnableToNormaliseZeroVectorError

to_normalized(): See to_normalised().

to_xyz()

Returns the cartesian coordinates as the tuple (x,y,z).

Return type:: the tuple (float,float,float)

x, y, z = vector.to_xyz()