Math Types & Utilities (mathutils)

This module provides access to math operations.

Note

Classes, methods and attributes that accept vectors also accept other numeric sequences, such as tuples, lists.

Submodules:

• Geometry Utilities (mathutils.geometry)
• BVHTree Utilities (mathutils.bvhtree)
• KDTree Utilities (mathutils.kdtree)
• Interpolation Utilities (mathutils.interpolate)
• Noise Utilities (mathutils.noise)

The mathutils module provides the following classes:

• Color,

• Euler,

• Matrix,

• Quaternion,

• Vector,

import mathutils
from math import radians

vec = mathutils.Vector((1.0, 2.0, 3.0))

mat_rot = mathutils.Matrix.Rotation(radians(90.0), 4, 'X')
mat_trans = mathutils.Matrix.Translation(vec)

mat = mat_trans @ mat_rot
mat.invert()

mat3 = mat.to_3x3()
quat1 = mat.to_quaternion()
quat2 = mat3.to_quaternion()

quat_diff = quat1.rotation_difference(quat2)

print(quat_diff.angle)

class mathutils.Color(rgb)

This object gives access to Colors in Blender.

Parameters

rgb (3d vector) – (r, g, b) color values

import mathutils

# color values are represented as RGB values from 0 - 1, this is blue
col = mathutils.Color((0.0, 0.0, 1.0))

# as well as r/g/b attribute access you can adjust them by h/s/v
col.s *= 0.5

# you can access its components by attribute or index
print("Color R:", col.r)
print("Color G:", col[1])
print("Color B:", col[-1])
print("Color HSV: %.2f, %.2f, %.2f", col[:])


# components of an existing color can be set
col[:] = 0.0, 0.5, 1.0

# components of an existing color can use slice notation to get a tuple
print("Values: %f, %f, %f" % col[:])

# colors can be added and subtracted
col += mathutils.Color((0.25, 0.0, 0.0))

# Color can be multiplied, in this example color is scaled to 0-255
# can printed as integers
print("Color: %d, %d, %d" % (col * 255.0)[:])

# This example prints the color as hexadecimal
print("Hexadecimal: %.2x%.2x%.2x" % (int(col.r * 255), int(col.g * 255), int(col.b * 255)))

copy()

Returns a copy of this color.

Returns

A copy of the color.

Return type

Color

Note

use this to get a copy of a wrapped color with no reference to the original data.

freeze()

Make this object immutable.

After this the object can be hashed, used in dictionaries & sets.

Returns

An instance of this object.

b

Blue color channel.

Type

float

g

Green color channel.

Type

float

h

HSV Hue component in [0, 1].

Type

float

hsv

HSV Values in [0, 1].

Type

float triplet

is_frozen

True when this object has been frozen (read-only).

Type

boolean

is_wrapped

True when this object wraps external data (read-only).

Type

boolean

owner

The item this is wrapping or None (read-only).

r

Red color channel.

Type

float

s

HSV Saturation component in [0, 1].

Type

float

v

HSV Value component in [0, 1].

Type

float

class mathutils.Euler(angles, order='XYZ')

This object gives access to Eulers in Blender.

See also

Euler angles on Wikipedia.

Parameters

• angles (3d vector) – Three angles, in radians.

• order (str) – Optional order of the angles, a permutation of XYZ.

import mathutils
import math

# create a new euler with default axis rotation order
eul = mathutils.Euler((0.0, math.radians(45.0), 0.0), 'XYZ')

# rotate the euler
eul.rotate_axis('Z', math.radians(10.0))

# you can access its components by attribute or index
print("Euler X", eul.x)
print("Euler Y", eul[1])
print("Euler Z", eul[-1])

# components of an existing euler can be set
eul[:] = 1.0, 2.0, 3.0

# components of an existing euler can use slice notation to get a tuple
print("Values: %f, %f, %f" % eul[:])

# the order can be set at any time too
eul.order = 'ZYX'

# eulers can be used to rotate vectors
vec = mathutils.Vector((0.0, 0.0, 1.0))
vec.rotate(eul)

# often its useful to convert the euler into a matrix so it can be used as
# transformations with more flexibility
mat_rot = eul.to_matrix()
mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
mat = mat_loc @ mat_rot.to_4x4()

copy()

Returns a copy of this euler.

Returns

A copy of the euler.

Return type

Euler

Note

use this to get a copy of a wrapped euler with no reference to the original data.

freeze()

Make this object immutable.

After this the object can be hashed, used in dictionaries & sets.

Returns

An instance of this object.

make_compatible(other)

Make this euler compatible with another, so interpolating between them works as intended.

Note

the rotation order is not taken into account for this function.

rotate(other)

Rotates the euler by another mathutils value.

Parameters

other (Euler, Quaternion or Matrix) – rotation component of mathutils value

rotate_axis(axis, angle)

Rotates the euler a certain amount and returning a unique euler rotation (no 720 degree pitches).

Parameters

• axis (string) – single character in [‘X, ‘Y’, ‘Z’].

• angle (float) – angle in radians.

to_matrix()

Return a matrix representation of the euler.

Returns

A 3x3 rotation matrix representation of the euler.

Return type

Matrix

to_quaternion()

Return a quaternion representation of the euler.

Returns

Quaternion representation of the euler.

Return type

Quaternion

zero()

Set all values to zero.

is_frozen

True when this object has been frozen (read-only).

Type

boolean

is_wrapped

True when this object wraps external data (read-only).

Type

boolean

order

Euler rotation order.

Type

string in [‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’]

owner

The item this is wrapping or None (read-only).

x

Euler axis angle in radians.

Type

float

y

Euler axis angle in radians.

Type

float

z

Euler axis angle in radians.

Type

float

class mathutils.Matrix([rows])

This object gives access to Matrices in Blender, supporting square and rectangular matrices from 2x2 up to 4x4.

Parameters

rows (2d number sequence) – Sequence of rows. When omitted, a 4x4 identity matrix is constructed.

import mathutils
import math

# create a location matrix
mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))

# create an identitiy matrix
mat_sca = mathutils.Matrix.Scale(0.5, 4, (0.0, 0.0, 1.0))

# create a rotation matrix
mat_rot = mathutils.Matrix.Rotation(math.radians(45.0), 4, 'X')

# combine transformations
mat_out = mat_loc @ mat_rot @ mat_sca
print(mat_out)

# extract components back out of the matrix
loc, rot, sca = mat_out.decompose()
print(loc, rot, sca)

# it can also be useful to access components of a matrix directly
mat = mathutils.Matrix()
mat[0][0], mat[1][0], mat[2][0] = 0.0, 1.0, 2.0

mat[0][0:3] = 0.0, 1.0, 2.0

# each item in a matrix is a vector so vector utility functions can be used
mat[0].xyz = 0.0, 1.0, 2.0

classmethod Diagonal(vector)

Create a diagonal (scaling) matrix using the values from the vector.

Parameters

vector (Vector) – The vector of values for the diagonal.

Returns

A diagonal matrix.

Return type

Matrix

classmethod Identity(size)

Create an identity matrix.

Parameters

size (int) – The size of the identity matrix to construct [2, 4].

Returns

A new identity matrix.

Return type

Matrix

classmethod OrthoProjection(axis, size)

Create a matrix to represent an orthographic projection.

Parameters

• axis (string or Vector) – Can be any of the following: [‘X’, ‘Y’, ‘XY’, ‘XZ’, ‘YZ’], where a single axis is for a 2D matrix. Or a vector for an arbitrary axis

• size (int) – The size of the projection matrix to construct [2, 4].

Returns

A new projection matrix.

Return type

Matrix

classmethod Rotation(angle, size, axis)

Create a matrix representing a rotation.

Parameters

• angle (float) – The angle of rotation desired, in radians.

• size (int) – The size of the rotation matrix to construct [2, 4].

• axis (string or Vector) – a string in [‘X’, ‘Y’, ‘Z’] or a 3D Vector Object (optional when size is 2).

Returns

A new rotation matrix.

Return type

Matrix

classmethod Scale(factor, size, axis)

Create a matrix representing a scaling.

Parameters

• factor (float) – The factor of scaling to apply.

• size (int) – The size of the scale matrix to construct [2, 4].

• axis (Vector) – Direction to influence scale. (optional).

Returns

A new scale matrix.

Return type

Matrix

classmethod Shear(plane, size, factor)

Create a matrix to represent an shear transformation.

Parameters

• plane (string) – Can be any of the following: [‘X’, ‘Y’, ‘XY’, ‘XZ’, ‘YZ’], where a single axis is for a 2D matrix only.

• size (int) – The size of the shear matrix to construct [2, 4].

• factor (float or float pair) – The factor of shear to apply. For a 3 or 4 size matrix pass a pair of floats corresponding with the plane axis.

Returns

A new shear matrix.

Return type

Matrix

classmethod Translation(vector)

Create a matrix representing a translation.

Parameters

vector (Vector) – The translation vector.

Returns

An identity matrix with a translation.

Return type

Matrix

adjugate()

Set the matrix to its adjugate.

Note

When the matrix cannot be adjugated a ValueError exception is raised.

See also

Adjugate matrix <https://en.wikipedia.org/wiki/Adjugate_matrix> on Wikipedia.

adjugated()

Return an adjugated copy of the matrix.

Returns

the adjugated matrix.

Return type

Matrix

Note

When the matrix cant be adjugated a ValueError exception is raised.

copy()

Returns a copy of this matrix.

Returns

an instance of itself

Return type

Matrix

decompose()

Return the translation, rotation, and scale components of this matrix.

Returns

tuple of translation, rotation, and scale

Return type

(Vector, Quaternion, Vector)

determinant()

Return the determinant of a matrix.

Returns

Return the determinant of a matrix.

Return type

float

See also

Determinant <https://en.wikipedia.org/wiki/Determinant> on Wikipedia.

freeze()

Make this object immutable.

After this the object can be hashed, used in dictionaries & sets.

Returns

An instance of this object.

identity()

Set the matrix to the identity matrix.

Note

An object with a location and rotation of zero, and a scale of one will have an identity matrix.

See also

Identity matrix <https://en.wikipedia.org/wiki/Identity_matrix> on Wikipedia.

invert(fallback=None)

Set the matrix to its inverse.

Parameters

fallback (Matrix) – Set the matrix to this value when the inverse cannot be calculated (instead of raising a ValueError exception).

See also

Inverse matrix <https://en.wikipedia.org/wiki/Inverse_matrix> on Wikipedia.

invert_safe()

Set the matrix to its inverse, will never error. If degenerated (e.g. zero scale on an axis), add some epsilon to its diagonal, to get an invertible one. If tweaked matrix is still degenerated, set to the identity matrix instead.

See also

Inverse Matrix <https://en.wikipedia.org/wiki/Inverse_matrix> on Wikipedia.

inverted(fallback=None)

Return an inverted copy of the matrix.

Parameters

fallback (any) – return this when the inverse can’t be calculated (instead of raising a ValueError).

Returns

the inverted matrix or fallback when given.

Return type

Matrix

inverted_safe()

Return an inverted copy of the matrix, will never error. If degenerated (e.g. zero scale on an axis), add some epsilon to its diagonal, to get an invertible one. If tweaked matrix is still degenerated, return the identity matrix instead.

Returns

the inverted matrix.

Return type

Matrix

lerp(other, factor)

Returns the interpolation of two matrices. Uses polar decomposition, see “Matrix Animation and Polar Decomposition”, Shoemake and Duff, 1992.

Parameters

• other (Matrix) – value to interpolate with.

• factor (float) – The interpolation value in [0.0, 1.0].

Returns

The interpolated matrix.

Return type

Matrix

normalize()

Normalize each of the matrix columns.

normalized()

Return a column normalized matrix

Returns

a column normalized matrix

Return type

Matrix

resize_4x4()

Resize the matrix to 4x4.

rotate(other)

Rotates the matrix by another mathutils value.

Parameters

other (Euler, Quaternion or Matrix) – rotation component of mathutils value

Note

If any of the columns are not unit length this may not have desired results.

to_2x2()

Return a 2x2 copy of this matrix.

Returns

a new matrix.

Return type

Matrix

to_3x3()

Return a 3x3 copy of this matrix.

Returns

a new matrix.

Return type

Matrix

to_4x4()

Return a 4x4 copy of this matrix.

Returns

a new matrix.

Return type

Matrix

to_euler(order, euler_compat)

Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).

Parameters

• order (string) – Optional rotation order argument in [‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’].

• euler_compat (Euler) – Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.

Returns

Euler representation of the matrix.

Return type

Euler

to_quaternion()

Return a quaternion representation of the rotation matrix.

Returns

Quaternion representation of the rotation matrix.

Return type

Quaternion

to_scale()

Return the scale part of a 3x3 or 4x4 matrix.

Returns

Return the scale of a matrix.

Return type

Vector

Note

This method does not return a negative scale on any axis because it is not possible to obtain this data from the matrix alone.

to_translation()

Return the translation part of a 4 row matrix.

Returns

Return the translation of a matrix.

Return type

Vector

transpose()

Set the matrix to its transpose.

See also

Transpose <https://en.wikipedia.org/wiki/Transpose> on Wikipedia.

transposed()

Return a new, transposed matrix.

Returns

a transposed matrix

Return type

Matrix

zero()

Set all the matrix values to zero.

Return type

Matrix

col

Access the matrix by columns, 3x3 and 4x4 only, (read-only).

Type

Matrix Access

is_frozen

True when this object has been frozen (read-only).

Type

boolean

is_negative

True if this matrix results in a negative scale, 3x3 and 4x4 only, (read-only).

Type

bool

is_orthogonal

True if this matrix is orthogonal, 3x3 and 4x4 only, (read-only).

Type

bool

is_orthogonal_axis_vectors

True if this matrix has got orthogonal axis vectors, 3x3 and 4x4 only, (read-only).

Type

bool

is_wrapped

True when this object wraps external data (read-only).

Type

boolean

median_scale

The average scale applied to each axis (read-only).

Type

float

owner

The item this is wrapping or None (read-only).

row

Access the matrix by rows (default), (read-only).

Type

Matrix Access

translation

The translation component of the matrix.

Type

Vector

class mathutils.Quaternion([seq[, angle]])

This object gives access to Quaternions in Blender.

Parameters

• seq (Vector) – size 3 or 4

• angle (float) – rotation angle, in radians

The constructor takes arguments in various forms:

(), no args

Create an identity quaternion

(wxyz)

Create a quaternion from a (w, x, y, z) vector.

(exponential_map)

Create a quaternion from a 3d exponential map vector.

See also

to_exponential_map()

(axis, angle)

Create a quaternion representing a rotation of angle radians over axis.

See also

to_axis_angle()

import mathutils
import math

# a new rotation 90 degrees about the Y axis
quat_a = mathutils.Quaternion((0.7071068, 0.0, 0.7071068, 0.0))

# passing values to Quaternion's directly can be confusing so axis, angle
# is supported for initializing too
quat_b = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))

print("Check quaternions match", quat_a == quat_b)

# like matrices, quaternions can be multiplied to accumulate rotational values
quat_a = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
quat_b = mathutils.Quaternion((0.0, 0.0, 1.0), math.radians(45.0))
quat_out = quat_a @ quat_b

# print the quat, euler degrees for mere mortals and (axis, angle)
print("Final Rotation:")
print(quat_out)
print("%.2f, %.2f, %.2f" % tuple(math.degrees(a) for a in quat_out.to_euler()))
print("(%.2f, %.2f, %.2f), %.2f" % (quat_out.axis[:] +
                                    (math.degrees(quat_out.angle), )))

# multiple rotations can be interpolated using the exponential map
quat_c = mathutils.Quaternion((1.0, 0.0, 0.0), math.radians(15.0))
exp_avg = (quat_a.to_exponential_map() +
           quat_b.to_exponential_map() +
           quat_c.to_exponential_map()) / 3.0
quat_avg = mathutils.Quaternion(exp_avg)
print("Average rotation:")
print(quat_avg)

conjugate()

Set the quaternion to its conjugate (negate x, y, z).

conjugated()

Return a new conjugated quaternion.

Returns

a new quaternion.

Return type

Quaternion

copy()

Returns a copy of this quaternion.

Returns

A copy of the quaternion.

Return type

Quaternion

Note

use this to get a copy of a wrapped quaternion with no reference to the original data.

cross(other)

Return the cross product of this quaternion and another.

Parameters

other (Quaternion) – The other quaternion to perform the cross product with.

Returns

The cross product.

Return type

Quaternion

dot(other)

Return the dot product of this quaternion and another.

Parameters

other (Quaternion) – The other quaternion to perform the dot product with.

Returns

The dot product.

Return type

float

freeze()

Make this object immutable.

After this the object can be hashed, used in dictionaries & sets.

Returns

An instance of this object.

identity()

Set the quaternion to an identity quaternion.

Return type

Quaternion

invert()

Set the quaternion to its inverse.

inverted()

Return a new, inverted quaternion.

Returns

the inverted value.

Return type

Quaternion

make_compatible(other)

Make this quaternion compatible with another, so interpolating between them works as intended.

negate()

Set the quaternion to its negative.

Return type

Quaternion

normalize()

Normalize the quaternion.

normalized()

Return a new normalized quaternion.

Returns

a normalized copy.

Return type

Quaternion

rotate(other)

Rotates the quaternion by another mathutils value.

Parameters

other (Euler, Quaternion or Matrix) – rotation component of mathutils value

rotation_difference(other)

Returns a quaternion representing the rotational difference.

Parameters

other (Quaternion) – second quaternion.

Returns

the rotational difference between the two quat rotations.

Return type

Quaternion

slerp(other, factor)

Returns the interpolation of two quaternions.

Parameters

• other (Quaternion) – value to interpolate with.

• factor (float) – The interpolation value in [0.0, 1.0].

Returns

The interpolated rotation.

Return type

Quaternion

to_axis_angle()

Return the axis, angle representation of the quaternion.

Returns

axis, angle.

Return type

(Vector, float) pair

to_euler(order, euler_compat)

Return Euler representation of the quaternion.

Parameters

• order (string) – Optional rotation order argument in [‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’].

• euler_compat (Euler) – Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.

Returns

Euler representation of the quaternion.

Return type

Euler

to_exponential_map()

Return the exponential map representation of the quaternion.

This representation consist of the rotation axis multiplied by the rotation angle. Such a representation is useful for interpolation between multiple orientations.

Returns

exponential map.

Return type

Vector of size 3

To convert back to a quaternion, pass it to the Quaternion constructor.

to_matrix()

Return a matrix representation of the quaternion.

Returns

A 3x3 rotation matrix representation of the quaternion.

Return type

Matrix

to_swing_twist(axis)

Split the rotation into a swing quaternion with the specified axis fixed at zero, and the remaining twist rotation angle.

Parameters

axis – twist axis as a string in [‘X’, ‘Y’, ‘Z’]

Returns

swing, twist angle.

Return type

(Quaternion, float) pair

angle

Angle of the quaternion.

Type

float

axis

Quaternion axis as a vector.

Type

Vector

is_frozen

True when this object has been frozen (read-only).

Type

boolean

is_wrapped

True when this object wraps external data (read-only).

Type

boolean

magnitude

Size of the quaternion (read-only).

Type

float

owner

The item this is wrapping or None (read-only).

w

Quaternion axis value.

Type

float

x

Quaternion axis value.

Type

float

y

Quaternion axis value.

Type

float

z

Quaternion axis value.

Type

float

class mathutils.Vector(seq)

This object gives access to Vectors in Blender.

Parameters

seq (sequence of numbers) – Components of the vector, must be a sequence of at least two

import mathutils

# zero length vector
vec = mathutils.Vector((0.0, 0.0, 1.0))

# unit length vector
vec_a = vec.normalized()

vec_b = mathutils.Vector((0.0, 1.0, 2.0))

vec2d = mathutils.Vector((1.0, 2.0))
vec3d = mathutils.Vector((1.0, 0.0, 0.0))
vec4d = vec_a.to_4d()

# other mathutuls types
quat = mathutils.Quaternion()
matrix = mathutils.Matrix()

# Comparison operators can be done on Vector classes:

# (In)equality operators == and != test component values, e.g. 1,2,3 != 3,2,1
vec_a == vec_b
vec_a != vec_b

# Ordering operators >, >=, > and <= test vector length.
vec_a > vec_b
vec_a >= vec_b
vec_a < vec_b
vec_a <= vec_b


# Math can be performed on Vector classes
vec_a + vec_b
vec_a - vec_b
vec_a @ vec_b
vec_a * 10.0
matrix @ vec_a
quat @ vec_a
-vec_a


# You can access a vector object like a sequence
x = vec_a[0]
len(vec)
vec_a[:] = vec_b
vec_a[:] = 1.0, 2.0, 3.0
vec2d[:] = vec3d[:2]


# Vectors support 'swizzle' operations
# See https://en.wikipedia.org/wiki/Swizzling_(computer_graphics)
vec.xyz = vec.zyx
vec.xy = vec4d.zw
vec.xyz = vec4d.wzz
vec4d.wxyz = vec.yxyx

classmethod Fill(size, fill=0.0)

Create a vector of length size with all values set to fill.

Parameters

• size (int) – The length of the vector to be created.

• fill (float) – The value used to fill the vector.

classmethod Linspace(start, stop, size)

Create a vector of the specified size which is filled with linearly spaced values between start and stop values.

Parameters

• start (int) – The start of the range used to fill the vector.

• stop (int) – The end of the range used to fill the vector.

• size (int) – The size of the vector to be created.

classmethod Range(start=0, stop, step=1)

Create a filled with a range of values.

Parameters

• start (int) – The start of the range used to fill the vector.

• stop (int) – The end of the range used to fill the vector.

• step (int) – The step between successive values in the vector.

classmethod Repeat(vector, size)

Create a vector by repeating the values in vector until the required size is reached.

Parameters

• tuple (mathutils.Vector) – The vector to draw values from.

• size (int) – The size of the vector to be created.

angle(other, fallback=None)

Return the angle between two vectors.

Parameters

• other (Vector) – another vector to compare the angle with

• fallback (any) – return this when the angle can’t be calculated (zero length vector), (instead of raising a ValueError).

Returns

angle in radians or fallback when given

Return type

float

angle_signed(other, fallback)

Return the signed angle between two 2D vectors (clockwise is positive).

Parameters

• other (Vector) – another vector to compare the angle with

• fallback (any) – return this when the angle can’t be calculated (zero length vector), (instead of raising a ValueError).

Returns

angle in radians or fallback when given

Return type

float

copy()

Returns a copy of this vector.

Returns

A copy of the vector.

Return type

Vector

Note

use this to get a copy of a wrapped vector with no reference to the original data.

cross(other)

Return the cross product of this vector and another.

Parameters

other (Vector) – The other vector to perform the cross product with.

Returns

The cross product.

Return type

Vector or float when 2D vectors are used

Note

both vectors must be 2D or 3D

dot(other)

Return the dot product of this vector and another.

Parameters

other (Vector) – The other vector to perform the dot product with.

Returns

The dot product.

Return type

Vector

freeze()

Make this object immutable.

After this the object can be hashed, used in dictionaries & sets.

Returns

An instance of this object.

lerp(other, factor)

Returns the interpolation of two vectors.

Parameters

• other (Vector) – value to interpolate with.

• factor (float) – The interpolation value in [0.0, 1.0].

Returns

The interpolated vector.

Return type

Vector

negate()

Set all values to their negative.

normalize()

Normalize the vector, making the length of the vector always 1.0.

Warning

Normalizing a vector where all values are zero has no effect.

Note

Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched.

normalized()

Return a new, normalized vector.

Returns

a normalized copy of the vector

Return type

Vector

orthogonal()

Return a perpendicular vector.

Returns

a new vector 90 degrees from this vector.

Return type

Vector

Note

the axis is undefined, only use when any orthogonal vector is acceptable.

project(other)

Return the projection of this vector onto the other.

Parameters

other (Vector) – second vector.

Returns

the parallel projection vector

Return type

Vector

reflect(mirror)

Return the reflection vector from the mirror argument.

Parameters

mirror (Vector) – This vector could be a normal from the reflecting surface.

Returns

The reflected vector matching the size of this vector.

Return type

Vector

resize(size=3)

Resize the vector to have size number of elements.

resize_2d()

Resize the vector to 2D (x, y).

resize_3d()

Resize the vector to 3D (x, y, z).

resize_4d()

Resize the vector to 4D (x, y, z, w).

resized(size=3)

Return a resized copy of the vector with size number of elements.

Returns

a new vector

Return type

Vector

rotate(other)

Rotate the vector by a rotation value.

Note

2D vectors are a special case that can only be rotated by a 2x2 matrix.

Parameters

other (Euler, Quaternion or Matrix) – rotation component of mathutils value

rotation_difference(other)

Returns a quaternion representing the rotational difference between this vector and another.

Parameters

other (Vector) – second vector.

Returns

the rotational difference between the two vectors.

Return type

Quaternion

Note

2D vectors raise an AttributeError.

slerp(other, factor, fallback=None)

Returns the interpolation of two non-zero vectors (spherical coordinates).

Parameters

• other (Vector) – value to interpolate with.

• factor (float) – The interpolation value typically in [0.0, 1.0].

• fallback (any) – return this when the vector can’t be calculated (zero length vector or direct opposites), (instead of raising a ValueError).

Returns

The interpolated vector.

Return type

Vector

to_2d()

Return a 2d copy of the vector.

Returns

a new vector

Return type

Vector

to_3d()

Return a 3d copy of the vector.

Returns

a new vector

Return type

Vector

to_4d()

Return a 4d copy of the vector.

Returns

a new vector

Return type

Vector

to_track_quat(track, up)

Return a quaternion rotation from the vector and the track and up axis.

Parameters

• track (string) – Track axis in [‘X’, ‘Y’, ‘Z’, ‘-X’, ‘-Y’, ‘-Z’].

• up (string) – Up axis in [‘X’, ‘Y’, ‘Z’].

Returns

rotation from the vector and the track and up axis.

Return type

Quaternion

to_tuple(precision=-1)

Return this vector as a tuple with.

Parameters

precision (int) – The number to round the value to in [-1, 21].

Returns

the values of the vector rounded by precision

Return type

tuple

zero()

Set all values to zero.

is_frozen

True when this object has been frozen (read-only).

Type

boolean

is_wrapped

True when this object wraps external data (read-only).

Type

boolean

length

Vector Length.

Type

float

length_squared

Vector length squared (v.dot(v)).

Type

float

magnitude

Vector Length.

Type

float

owner

The item this is wrapping or None (read-only).

w

Vector W axis (4D Vectors only).

Type

float

ww

Undocumented, consider contributing.

www

Undocumented, consider contributing.

wwww

Undocumented, consider contributing.

wwwx

Undocumented, consider contributing.

wwwy

Undocumented, consider contributing.

wwwz

Undocumented, consider contributing.

wwx

Undocumented, consider contributing.

wwxw

Undocumented, consider contributing.

wwxx

Undocumented, consider contributing.

wwxy

Undocumented, consider contributing.

wwxz

Undocumented, consider contributing.

wwy

Undocumented, consider contributing.

wwyw

Undocumented, consider contributing.

wwyx

Undocumented, consider contributing.

wwyy

Undocumented, consider contributing.

wwyz

Undocumented, consider contributing.

wwz

Undocumented, consider contributing.

wwzw

Undocumented, consider contributing.

wwzx

Undocumented, consider contributing.

wwzy

Undocumented, consider contributing.

wwzz

Undocumented, consider contributing.

wx

Undocumented, consider contributing.

wxw

Undocumented, consider contributing.

wxww

Undocumented, consider contributing.

wxwx

Undocumented, consider contributing.

wxwy

Undocumented, consider contributing.

wxwz

Undocumented, consider contributing.

wxx

Undocumented, consider contributing.

wxxw

Undocumented, consider contributing.

wxxx

Undocumented, consider contributing.

wxxy

Undocumented, consider contributing.

wxxz

Undocumented, consider contributing.

wxy

Undocumented, consider contributing.

wxyw

Undocumented, consider contributing.

wxyx

Undocumented, consider contributing.

wxyy

Undocumented, consider contributing.

wxyz

Undocumented, consider contributing.

wxz

Undocumented, consider contributing.

wxzw

Undocumented, consider contributing.

wxzx

Undocumented, consider contributing.

wxzy

Undocumented, consider contributing.

wxzz

Undocumented, consider contributing.

wy

Undocumented, consider contributing.

wyw

Undocumented, consider contributing.

wyww

Undocumented, consider contributing.

wywx

Undocumented, consider contributing.

wywy

Undocumented, consider contributing.

wywz

Undocumented, consider contributing.

wyx

Undocumented, consider contributing.

wyxw

Undocumented, consider contributing.

wyxx

Undocumented, consider contributing.

wyxy

Undocumented, consider contributing.

wyxz

Undocumented, consider contributing.

wyy

Undocumented, consider contributing.

wyyw

Undocumented, consider contributing.

wyyx

Undocumented, consider contributing.

wyyy

Undocumented, consider contributing.

wyyz

Undocumented, consider contributing.

wyz

Undocumented, consider contributing.

wyzw

Undocumented, consider contributing.

wyzx

Undocumented, consider contributing.

wyzy

Undocumented, consider contributing.

wyzz

Undocumented, consider contributing.

wz

Undocumented, consider contributing.

wzw

Undocumented, consider contributing.

wzww

Undocumented, consider contributing.

wzwx

Undocumented, consider contributing.

wzwy

Undocumented, consider contributing.

wzwz

Undocumented, consider contributing.

wzx

Undocumented, consider contributing.

wzxw

Undocumented, consider contributing.

wzxx

Undocumented, consider contributing.

wzxy

Undocumented, consider contributing.

wzxz

Undocumented, consider contributing.

wzy

Undocumented, consider contributing.

wzyw

Undocumented, consider contributing.

wzyx

Undocumented, consider contributing.

wzyy

Undocumented, consider contributing.

wzyz

Undocumented, consider contributing.

wzz

Undocumented, consider contributing.

wzzw

Undocumented, consider contributing.

wzzx

Undocumented, consider contributing.

wzzy

Undocumented, consider contributing.

wzzz

Undocumented, consider contributing.

x

Vector X axis.

Type

float

xw

Undocumented, consider contributing.

xww

Undocumented, consider contributing.

xwww

Undocumented, consider contributing.

xwwx

Undocumented, consider contributing.

xwwy

Undocumented, consider contributing.

xwwz

Undocumented, consider contributing.

xwx

Undocumented, consider contributing.

xwxw

Undocumented, consider contributing.

xwxx

Undocumented, consider contributing.

xwxy

Undocumented, consider contributing.

xwxz

Undocumented, consider contributing.

xwy

Undocumented, consider contributing.

xwyw

Undocumented, consider contributing.

xwyx

Undocumented, consider contributing.

xwyy

Undocumented, consider contributing.

xwyz

Undocumented, consider contributing.

xwz

Undocumented, consider contributing.

xwzw

Undocumented, consider contributing.

xwzx

Undocumented, consider contributing.

xwzy

Undocumented, consider contributing.

xwzz

Undocumented, consider contributing.

xx

Undocumented, consider contributing.

xxw

Undocumented, consider contributing.

xxww

Undocumented, consider contributing.

xxwx

Undocumented, consider contributing.

xxwy

Undocumented, consider contributing.

xxwz

Undocumented, consider contributing.

xxx

Undocumented, consider contributing.

xxxw

Undocumented, consider contributing.

xxxx

Undocumented, consider contributing.

xxxy

Undocumented, consider contributing.

xxxz

Undocumented, consider contributing.

xxy

Undocumented, consider contributing.

xxyw

Undocumented, consider contributing.

xxyx

Undocumented, consider contributing.

xxyy

Undocumented, consider contributing.

xxyz

Undocumented, consider contributing.

xxz

Undocumented, consider contributing.

xxzw

Undocumented, consider contributing.

xxzx

Undocumented, consider contributing.

xxzy

Undocumented, consider contributing.

xxzz

Undocumented, consider contributing.

xy

Undocumented, consider contributing.

xyw

Undocumented, consider contributing.

xyww

Undocumented, consider contributing.

xywx

Undocumented, consider contributing.

xywy

Undocumented, consider contributing.

xywz

Undocumented, consider contributing.

xyx

Undocumented, consider contributing.

xyxw

Undocumented, consider contributing.

xyxx

Undocumented, consider contributing.

xyxy

Undocumented, consider contributing.

xyxz

Undocumented, consider contributing.

xyy

Undocumented, consider contributing.

xyyw

Undocumented, consider contributing.

xyyx

Undocumented, consider contributing.

xyyy

Undocumented, consider contributing.

xyyz

Undocumented, consider contributing.

xyz

Undocumented, consider contributing.

xyzw

Undocumented, consider contributing.

xyzx

Undocumented, consider contributing.

xyzy

Undocumented, consider contributing.

xyzz

Undocumented, consider contributing.

xz

Undocumented, consider contributing.

xzw

Undocumented, consider contributing.

xzww

Undocumented, consider contributing.

xzwx

Undocumented, consider contributing.

xzwy

Undocumented, consider contributing.

xzwz

Undocumented, consider contributing.

xzx

Undocumented, consider contributing.

xzxw

Undocumented, consider contributing.

xzxx

Undocumented, consider contributing.

xzxy

Undocumented, consider contributing.

xzxz

Undocumented, consider contributing.

xzy

Undocumented, consider contributing.

xzyw

Undocumented, consider contributing.

xzyx

Undocumented, consider contributing.

xzyy

Undocumented, consider contributing.

xzyz

Undocumented, consider contributing.

xzz

Undocumented, consider contributing.

xzzw

Undocumented, consider contributing.

xzzx

Undocumented, consider contributing.

xzzy

Undocumented, consider contributing.

xzzz

Undocumented, consider contributing.

y

Vector Y axis.

Type

float

yw

Undocumented, consider contributing.

yww

Undocumented, consider contributing.

ywww

Undocumented, consider contributing.

ywwx

Undocumented, consider contributing.

ywwy

Undocumented, consider contributing.

ywwz

Undocumented, consider contributing.

ywx

Undocumented, consider contributing.

ywxw

Undocumented, consider contributing.

ywxx

Undocumented, consider contributing.

ywxy

Undocumented, consider contributing.

ywxz

Undocumented, consider contributing.

ywy

Undocumented, consider contributing.

ywyw

Undocumented, consider contributing.

ywyx

Undocumented, consider contributing.

ywyy

Undocumented, consider contributing.

ywyz

Undocumented, consider contributing.

ywz

Undocumented, consider contributing.

ywzw

Undocumented, consider contributing.

ywzx

Undocumented, consider contributing.

ywzy

Undocumented, consider contributing.

ywzz

Undocumented, consider contributing.

yx

Undocumented, consider contributing.

yxw

Undocumented, consider contributing.

yxww

Undocumented, consider contributing.

yxwx

Undocumented, consider contributing.

yxwy

Undocumented, consider contributing.

yxwz

Undocumented, consider contributing.

yxx

Undocumented, consider contributing.

yxxw

Undocumented, consider contributing.

yxxx

Undocumented, consider contributing.

yxxy

Undocumented, consider contributing.

yxxz

Undocumented, consider contributing.

yxy

Undocumented, consider contributing.

yxyw

Undocumented, consider contributing.

yxyx

Undocumented, consider contributing.

yxyy

Undocumented, consider contributing.

yxyz

Undocumented, consider contributing.

yxz

Undocumented, consider contributing.

yxzw

Undocumented, consider contributing.

yxzx

Undocumented, consider contributing.

yxzy

Undocumented, consider contributing.

yxzz

Undocumented, consider contributing.

yy

Undocumented, consider contributing.

yyw

Undocumented, consider contributing.

yyww

Undocumented, consider contributing.

yywx

Undocumented, consider contributing.

yywy

Undocumented, consider contributing.

yywz

Undocumented, consider contributing.

yyx

Undocumented, consider contributing.

yyxw

Undocumented, consider contributing.

yyxx

Undocumented, consider contributing.

yyxy

Undocumented, consider contributing.

yyxz

Undocumented, consider contributing.

yyy

Undocumented, consider contributing.

yyyw

Undocumented, consider contributing.

yyyx

Undocumented, consider contributing.

yyyy

Undocumented, consider contributing.

yyyz

Undocumented, consider contributing.

yyz

Undocumented, consider contributing.

yyzw

Undocumented, consider contributing.

yyzx

Undocumented, consider contributing.

yyzy

Undocumented, consider contributing.

yyzz

Undocumented, consider contributing.

yz

Undocumented, consider contributing.

yzw

Undocumented, consider contributing.

yzww

Undocumented, consider contributing.

yzwx

Undocumented, consider contributing.

yzwy

Undocumented, consider contributing.

yzwz

Undocumented, consider contributing.

yzx

Undocumented, consider contributing.

yzxw

Undocumented, consider contributing.

yzxx

Undocumented, consider contributing.

yzxy

Undocumented, consider contributing.

yzxz

Undocumented, consider contributing.

yzy

Undocumented, consider contributing.

yzyw

Undocumented, consider contributing.

yzyx

Undocumented, consider contributing.

yzyy

Undocumented, consider contributing.

yzyz

Undocumented, consider contributing.

yzz

Undocumented, consider contributing.

yzzw

Undocumented, consider contributing.

yzzx

Undocumented, consider contributing.

yzzy

Undocumented, consider contributing.

yzzz

Undocumented, consider contributing.

z

Vector Z axis (3D Vectors only).

Type

float

zw

Undocumented, consider contributing.

zww

Undocumented, consider contributing.

zwww

Undocumented, consider contributing.

zwwx

Undocumented, consider contributing.

zwwy

Undocumented, consider contributing.

zwwz

Undocumented, consider contributing.

zwx

Undocumented, consider contributing.

zwxw

Undocumented, consider contributing.

zwxx

Undocumented, consider contributing.

zwxy

Undocumented, consider contributing.

zwxz

Undocumented, consider contributing.

zwy

Undocumented, consider contributing.

zwyw

Undocumented, consider contributing.

zwyx

Undocumented, consider contributing.

zwyy

Undocumented, consider contributing.

zwyz

Undocumented, consider contributing.

zwz

Undocumented, consider contributing.

zwzw

Undocumented, consider contributing.

zwzx

Undocumented, consider contributing.

zwzy

Undocumented, consider contributing.

zwzz

Undocumented, consider contributing.

zx

Undocumented, consider contributing.

zxw

Undocumented, consider contributing.

zxww

Undocumented, consider contributing.

zxwx

Undocumented, consider contributing.

zxwy

Undocumented, consider contributing.

zxwz

Undocumented, consider contributing.

zxx

Undocumented, consider contributing.

zxxw

Undocumented, consider contributing.

zxxx

Undocumented, consider contributing.

zxxy

Undocumented, consider contributing.

zxxz

Undocumented, consider contributing.

zxy

Undocumented, consider contributing.

zxyw

Undocumented, consider contributing.

zxyx

Undocumented, consider contributing.

zxyy

Undocumented, consider contributing.

zxyz

Undocumented, consider contributing.

zxz

Undocumented, consider contributing.

zxzw

Undocumented, consider contributing.

zxzx

Undocumented, consider contributing.

zxzy

Undocumented, consider contributing.

zxzz

Undocumented, consider contributing.

zy

Undocumented, consider contributing.

zyw

Undocumented, consider contributing.

zyww

Undocumented, consider contributing.

zywx

Undocumented, consider contributing.

zywy

Undocumented, consider contributing.

zywz

Undocumented, consider contributing.

zyx

Undocumented, consider contributing.

zyxw

Undocumented, consider contributing.

zyxx

Undocumented, consider contributing.

zyxy

Undocumented, consider contributing.

zyxz

Undocumented, consider contributing.

zyy

Undocumented, consider contributing.

zyyw

Undocumented, consider contributing.

zyyx

Undocumented, consider contributing.

zyyy

Undocumented, consider contributing.

zyyz

Undocumented, consider contributing.

zyz

Undocumented, consider contributing.

zyzw

Undocumented, consider contributing.

zyzx

Undocumented, consider contributing.

zyzy

Undocumented, consider contributing.

zyzz

Undocumented, consider contributing.

zz

Undocumented, consider contributing.

zzw

Undocumented, consider contributing.

zzww

Undocumented, consider contributing.

zzwx

Undocumented, consider contributing.

zzwy

Undocumented, consider contributing.

zzwz

Undocumented, consider contributing.

zzx

Undocumented, consider contributing.

zzxw

Undocumented, consider contributing.

zzxx

Undocumented, consider contributing.

zzxy

Undocumented, consider contributing.

zzxz

Undocumented, consider contributing.

zzy

Undocumented, consider contributing.

zzyw

Undocumented, consider contributing.

zzyx

Undocumented, consider contributing.

zzyy

Undocumented, consider contributing.

zzyz

Undocumented, consider contributing.

zzz

Undocumented, consider contributing.

zzzw

Undocumented, consider contributing.

zzzx

Undocumented, consider contributing.

zzzy

Undocumented, consider contributing.

zzzz

Undocumented, consider contributing.