# 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). [staticmethod] Returns a new vector that is a normalised (unit length) version of another. [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. Returns the magnitude, or length, of the vector. Returns the x coordinate. Returns the y coordinate. Returns the z coordinate. Returns `True` if the magnitude of this vector is zero. Returns a new vector that is a normalised (unit length) version of this vector. 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()
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()
```