# 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 float the y component of the 3D vector float the z component of the 3D vector 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 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 float 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 sequence (such as list or tuple) of (float,float,float), or Vector3D Vector3D 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 float the y component of the 3D vector float the z component of the 3D vector float 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 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 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