Vector

[[module omega | Python-Reference#module-omega]]

Two mutable vector types are available: Vector2 and Vector3, for 2D and 3D vectors, respectively. Vectors are assumed to hold floats, but most operations will also work if you use ints or longs instead. Construct a vector in the obvious way::

>>> Vector2(1.5, 2.0)
Vector2(1.50, 2.00)

>>> Vector3(1.0, 2.0, 3.0)
Vector3(1.00, 2.00, 3.00)

Element access

Components may be accessed as attributes (examples that follow use Vector3, but all results are similar for Vector2, using only the x and y components)::

>>> v = Vector3(1, 2, 3)
>>> v.x
1
>>> v.y
2
>>> v.z
3

Vectors support the list interface via slicing::

>>> v = Vector3(1, 2, 3)
>>> len(v)
3
>>> v[0]
1
>>> v[:]
(1, 2, 3)

You can also "swizzle" the components (a la GLSL or Cg)::

>>> v = Vector3(1, 2, 3)
>>> v.xyz
(1, 2, 3)
>>> v.zx
(3, 1)
>>> v.zzzz
(3, 3, 3, 3)

All of the above accessors are also mutators[1]::

>>> v = Vector3(1, 2, 3)
>>> v.x = 5
>>> v
Vector3(5.00, 2.00, 3.00)
>>> v[1:] = (10, 20)
>>> v
Vector3(5.00, 10.00, 20.00)

[1] assignment via a swizzle (e.g., v.xyz = (1, 2, 3)) is supported only if the _enable_swizzle_set variable is set. This is disabled by default, as it impacts on the performance of ordinary attribute setting, and is slower than setting components sequentially anyway.

Operators

Addition and subtraction are supported via operator overloading (note that in-place operators perform faster than those that create a new object)::

>>> v1 = Vector3(1, 2, 3)
>>> v2 = Vector3(4, 5, 6)
>>> v1 + v2
Vector3(5.00, 7.00, 9.00)
>>> v1 -= v2
>>> v1
Vector3(-3.00, -3.00, -3.00)

Multiplication and division can be performed with a scalar only::

>>> Vector3(1, 2, 3) * 2
Vector3(2.00, 4.00, 6.00)
>>> v1 = Vector3(1., 2., 3.)
>>> v1 /= 2
>>> v1
Vector3(0.50, 1.00, 1.50)

The magnitude of a vector can be found with abs::

>>> v = Vector3(1., 2., 3.)
>>> abs(v)
3.7416573867739413

A vector can be normalized in-place (note that the in-place method also returns self, so you can chain it with further operators)::

>>> v = Vector3(1., 2., 3.)
>>> v.normalize()
Vector3(0.27, 0.53, 0.80)
>>> v
Vector3(0.27, 0.53, 0.80)

The following methods do not alter the original vector or their arguments:

copy() Returns a copy of the vector. __copy__ is also implemented.

magnitude() Returns the magnitude of the vector; equivalent to abs(v). Example::

    >>> v = Vector3(1., 2., 3.)
    >>> v.magnitude()
    3.7416573867739413

magnitude_squared() Returns the sum of the squares of each component. Useful for comparing the length of two vectors without the expensive square root operation. Example::

    >>> v = Vector3(1., 2., 3.)
    >>> v.magnitude_squared()
    14.0

normalized() Return a unit length vector in the same direction. Note that this method differs from normalize in that it does not modify the vector in-place. Example::

    >>> v = Vector3(1., 2., 3.)
    >>> v.normalized()
    Vector3(0.27, 0.53, 0.80)
    >>> v
    Vector3(1.00, 2.00, 3.00)

dot(other) Return the scalar "dot" product of two vectors. Example::

    >>> v1 = Vector3(1., 2., 3.)
    >>> v2 = Vector3(4., 5., 6.)
    >>> v1.dot(v2)
    32.0

cross() and cross(other) Return the cross product of a vector (for Vector2), or the cross product of two vectors (for Vector3). The return type is a vector. Example::

    >>> v1 = Vector3(1., 2., 3.)
    >>> v2 = Vector3(4., 5., 6.)
    >>> v1.cross(v2)
    Vector3(-3.00, 6.00, -3.00)

In two dimensions there can be no argument to ``cross``::

    >>> v1 = Vector2(1., 2.)
    >>> v1.cross()
    Vector2(2.00, -1.00)

reflect(normal) Return the vector reflected about the given normal. In two dimensions, normal is the normal to a line, in three dimensions it is the normal to a plane. The normal must have unit length. Example::

    >>> v = Vector3(1., 2., 3.)
    >>> v.reflect(Vector3(0, 1, 0))
    Vector3(1.00, -2.00, 3.00)
    >>> v = Vector2(1., 2.)
    >>> v.reflect(Vector2(1, 0))
    Vector2(-1.00, 2.00)

rotate_around(axes, theta) For 3D vectors, return the vector rotated around axis by the angle theta.

    >>> v = Vector3(1., 2., 3.)
    >>> axes = Vector3(1.,1.,0)
    >>> v.rotate_around(axes,math.pi/4)
    Vector3(2.65, 0.35, 2.62)

angle(other) Return the angle between two vectors.

project(other) Return the projection (the component) of the vector on other.

Tests for equality include comparing against other sequences::

>>> v2 = Vector2(1, 2)
>>> v2 == Vector2(3, 4)
False
>>> v2 != Vector2(1, 2)
False
>>> v2 == (1, 2)
True

>>> v3 = Vector3(1, 2, 3)
>>> v3 == Vector3(3, 4, 5)
False
>>> v3 != Vector3(1, 2, 3)
False
>>> v3 == (1, 2, 3)
True

Vectors are not hashable, and hence cannot be put in sets nor used as dictionary keys::

>>> {Vector2(): 0}
Traceback (most recent call last):
    ...
TypeError: unhashable type: 'Vector2'

>>> {Vector3(): 0}
Traceback (most recent call last):
    ...
TypeError: unhashable type: 'Vector3'