pygplates.Vector3D

class pygplates.Vector3D(...)

Bases: Boost.Python.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)
__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))

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

create_normalized(...)

[staticmethod] See create_normalised().

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

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

Previous topic

pygplates.LocalCartesian

Next topic

pygplates.EnumerationType

This Page