Module Mathutils

source code

The Blender.Mathutils submodule.

Mathutils

(when accessing it from the Game Engine use Mathutils instead of Blender.Mathutils)

This module provides access to matrices, eulers, quaternions and vectors.

Example:

 import Blender
 from Blender import Mathutils
 from Blender.Mathutils import *

 vec = Vector([1,2,3])
 mat = RotationMatrix(90, 4, 'x')
 matT = TranslationMatrix(vec)

 matTotal = mat * matT
 matTotal.invert()

 mat3 = matTotal.rotationPart
 quat1 = mat.toQuat()
 quat2 = mat3.toQuat()

 angle = DifferenceQuats(quat1, quat2)
 print angle

Classes

[hide private]

Vector
This object gives access to Vectors in Blender.

Euler
This object gives access to Eulers in Blender.

Quaternion
This object gives access to Quaternions in Blender.

Matrix
This object gives access to Matrices in Blender.

Functions

[hide private]

Rand(low=0.0, high=1.0)
Return a random number within a range.

source code

Vector object

Intersect(vec1, vec2, vec3, ray, orig, clip=1)
Return the intersection between a ray and a triangle, if possible, return None otherwise.

source code

float

TriangleArea(vec1, vec2, vec3)
Return the area size of the 2D or 3D triangle defined.

source code

float

TriangleNormal(vec1, vec2, vec3)
Return the normal of the 3D triangle defined.

source code

float

QuadNormal(vec1, vec2, vec3, vec4)
Return the normal of the 3D quad defined.

source code

(Vector object, Vector object)

LineIntersect(vec1, vec2, vec3, vec4)
Return a tuple with the points on each line respectively closest to the other (when both lines intersect, both vector hold the same value).

source code

float

AngleBetweenVecs(vec1, vec2)
Return the angle between two vectors.

source code

Vector object

MidpointVecs(vec1, vec2)
Return a vector to the midpoint between two vectors.

source code

Vector object

ProjectVecs(vec1, vec2)
Return the projection of vec1 onto vec2.

source code

Matrix object.

RotationMatrix(angle, matSize, axisFlag, axis)
Create a matrix representing a rotation.

source code

Matrix object.

TranslationMatrix(vector)
Create a matrix representing a translation

source code

Matrix object.

ScaleMatrix(factor, matSize, axis)
Create a matrix representing a scaling.

source code

Matrix object.

OrthoProjectionMatrix(plane, matSize, axis)
Create a matrix to represent an orthographic projection

source code

Matrix object.

ShearMatrix(plane, factor, matSize)
Create a matrix to represent an orthographic projection

source code

Quaternion object

DifferenceQuats(quat1, quat2)
Returns a quaternion represting the rotational difference.

source code

Quaternion object

Slerp(quat1, quat2, factor)
Returns the interpolation of two quaternions.

source code

Deprecated

Vector object.

CopyVec(vector)
Create a copy of the Vector object.

source code

Vector object.

CrossVecs(vec1, vec2)
Return the cross product of two vectors.

source code

float

DotVecs(vec1, vec2)
Return the dot product of two vectors.

source code

Vector object

VecMultMat(vec, mat)
Multiply a vector and matrix (pre-multiply) Vector size and matrix column size must equal.

source code

Matrix object.

CopyMat(matrix)
Create a copy of the Matrix object.

source code

Vector object

MatMultVec(mat, vec)
Multiply a matrix and a vector (post-multiply) Vector size and matrix row size must equal.

source code

Quaternion object.

CopyQuat(quaternion)
Create a copy of the Quaternion object.

source code

Quaternion object.

CrossQuats(quat1, quat2)
Return the cross product of two quaternions.

source code

float

DotQuats(quat1, quat2)
Return the dot product of two quaternions.

source code

Euler object

CopyEuler(euler)
Create a new euler object.

source code

RotateEuler(euler, angle, axis)
Roatate a euler by an amount in degrees around an axis.

source code

Function Details

[hide private]

Rand(low=0.0, high=1.0)

source code

Return a random number within a range. low and high represent are optional parameters which represent the range from which the random number must return its result.

Parameters:

low (float) - The lower range.
high (float) - The upper range.

Intersect(vec1, vec2, vec3, ray, orig, clip=1)

source code

Return the intersection between a ray and a triangle, if possible, return None otherwise.

Parameters:

vec1 (Vector object.) - A 3d vector, one corner of the triangle.
vec2 (Vector object.) - A 3d vector, one corner of the triangle.
vec3 (Vector object.) - A 3d vector, one corner of the triangle.
ray (Vector object.) - A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction.
orig (Vector object.) - A 3d vector, the origin of the ray.
clip (integer) - if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.

Returns: Vector object

The intersection between a ray and a triangle, if possible, None otherwise.

TriangleArea(vec1, vec2, vec3)

source code

Return the area size of the 2D or 3D triangle defined.

Parameters:

vec1 (Vector object.) - A 2d or 3d vector, one corner of the triangle.
vec2 (Vector object.) - A 2d or 3d vector, one corner of the triangle.
vec3 (Vector object.) - A 2d or 3d vector, one corner of the triangle.

Returns: float

The area size of the 2D or 3D triangle defined.

TriangleNormal(vec1, vec2, vec3)

source code

Return the normal of the 3D triangle defined.

Parameters:

vec1 (Vector object.) - A 3d vector, one corner of the triangle.
vec2 (Vector object.) - A 3d vector, one corner of the triangle.
vec3 (Vector object.) - A 3d vector, one corner of the triangle.

Returns: float

The normal of the 3D triangle defined.

QuadNormal(vec1, vec2, vec3, vec4)

source code

Return the normal of the 3D quad defined.

Parameters:

vec1 (Vector object.) - A 3d vector, the first vertex of the quad.
vec2 (Vector object.) - A 3d vector, the second vertex of the quad.
vec3 (Vector object.) - A 3d vector, the third vertex of the quad.
vec4 (Vector object.) - A 3d vector, the fourth vertex of the quad.

Returns: float

The normal of the 3D quad defined.

LineIntersect(vec1, vec2, vec3, vec4)

source code

Return a tuple with the points on each line respectively closest to the other (when both lines intersect, both vector hold the same value). The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.

Parameters:

vec1 (Vector object.) - A 3d vector, one point on the first line.
vec2 (Vector object.) - A 3d vector, another point on the first line.
vec3 (Vector object.) - A 3d vector, one point on the second line.
vec4 (Vector object.) - A 3d vector, another point on the second line.

Returns: (Vector object, Vector object)

A tuple with the points on each line respectively closest to the other.

CopyVec(vector)

source code

Create a copy of the Vector object.

Parameters:

vector (Vector object.) - A 2d,3d or 4d vector to be copied.

Returns: Vector object.

A new vector object which is a copy of the one passed in.

Attention: DEPRECATED use vector.copy() instead.

CrossVecs(vec1, vec2)

source code

Return the cross product of two vectors.

Parameters:

vec1 (Vector object.) - A 3d vector.
vec2 (Vector object.) - A 3d vector.

Returns: Vector object.

A new vector representing the cross product of the two vectors.

Attention: DEPRECATED use vector.cross(other) instead.

DotVecs(vec1, vec2)

source code

Return the dot product of two vectors.

Parameters:

vec1 (Vector object.) - A 2d,3d or 4d vector.
vec2 (Vector object.) - A 2d,3d or 4d vector.

Returns: float

Return the scalar product of vector muliplication.

Attention: DEPRECATED use vector.dot(other) instead.

AngleBetweenVecs(vec1, vec2)

source code

Return the angle between two vectors. Zero length vectors raise an error.

Parameters:

vec1 (Vector object.) - A 2d or 3d vector.
vec2 (Vector object.) - A 2d or 3d vector.

Returns: float

The angle between the vectors in degrees.

Raises:

AttributeError - When there is a zero-length vector as an argument.

MidpointVecs(vec1, vec2)

source code

Return a vector to the midpoint between two vectors.

Parameters:

vec1 (Vector object.) - A 2d,3d or 4d vector.
vec2 (Vector object.) - A 2d,3d or 4d vector.

Returns: Vector object

The vector to the midpoint.

VecMultMat(vec, mat)

source code

Multiply a vector and matrix (pre-multiply) Vector size and matrix column size must equal.

Parameters:

vec (Vector object.) - A 2d,3d or 4d vector.
mat (Matrix object.) - A 2d,3d or 4d matrix.

Returns: Vector object

The row vector that results from the muliplication.

Attention: DEPRECATED You should now multiply vector * matrix direcly Example:

   result = myVector * myMatrix

ProjectVecs(vec1, vec2)

source code

Return the projection of vec1 onto vec2.

Parameters:

vec1 (Vector object.) - A 2d,3d or 4d vector.
vec2 (Vector object.) - A 2d,3d or 4d vector.

Returns: Vector object

The parallel projection vector.

RotationMatrix(angle, matSize, axisFlag, axis)

source code

Create a matrix representing a rotation.

Parameters:

angle (float) - The angle of rotation desired.
matSize (int) - The size of the rotation matrix to construct. Can be 2d, 3d, or 4d.
axisFlag (string (optional)) - Possible values:
- "x - x-axis rotation"
- "y - y-axis rotation"
- "z - z-axis rotation"
- "r - arbitrary rotation around vector"
axis (Vector object. (optional)) - The arbitrary axis of rotation used with "R"

Returns: Matrix object.

A new rotation matrix.

TranslationMatrix(vector)

source code

Create a matrix representing a translation

Parameters:

vector (Vector object) - The translation vector

Returns: Matrix object.

An identity matrix with a translation.

ScaleMatrix(factor, matSize, axis)

source code

Create a matrix representing a scaling.

Parameters:

factor (float) - The factor of scaling to apply.
matSize (int) - The size of the scale matrix to construct. Can be 2d, 3d, or 4d.
axis (Vector object. (optional)) - Direction to influence scale.

Returns: Matrix object.

A new scale matrix.

OrthoProjectionMatrix(plane, matSize, axis)

source code

Create a matrix to represent an orthographic projection

Parameters:

plane (string) - Can be any of the following:
- "x - x projection (2D)"
- "y - y projection (2D)"
- "xy - xy projection"
- "xz - xz projection"
- "yz - yz projection"
- "r - arbitrary projection plane"
matSize (int) - The size of the projection matrix to construct. Can be 2d, 3d, or 4d.
axis (Vector object. (optional)) - Arbitrary perpendicular plane vector.

Returns: Matrix object.

A new projeciton matrix.

ShearMatrix(plane, factor, matSize)

source code

Create a matrix to represent an orthographic projection

Parameters:

plane (string) - Can be any of the following:
- "x - x shear (2D)"
- "y - y shear (2D)"
- "xy - xy shear"
- "xz - xz shear"
- "yz - yz shear"
factor (float) - The factor of shear to apply.
matSize (int) - The size of the projection matrix to construct. Can be 2d, 3d, or 4d.

Returns: Matrix object.

A new shear matrix.

CopyMat(matrix)

source code

Create a copy of the Matrix object.

Parameters:

matrix (Matrix object.) - A 2d,3d or 4d matrix to be copied.

Returns: Matrix object.

A new matrix object which is a copy of the one passed in.

Attention: DEPRECATED Use the matrix copy funtion to make a copy. Example:

   newMat = myMat.copy()

MatMultVec(mat, vec)

source code

Multiply a matrix and a vector (post-multiply) Vector size and matrix row size must equal.

Parameters:

vec (Vector object.) - A 2d,3d or 4d vector.
mat (Matrix object.) - A 2d,3d or 4d matrix.

Returns: Vector object

The column vector that results from the muliplication.

Attention: DEPRECATED You should use direct muliplication on the arguments Example:

   result = myMatrix * myVector

CopyQuat(quaternion)

source code

Create a copy of the Quaternion object.

Parameters:

quaternion (Quaternion object.) - Quaternion to be copied.

Returns: Quaternion object.

A new quaternion object which is a copy of the one passed in.

Attention: DEPRECATED You should use the Quaterion() constructor directly to create copies of quaternions Example:

   newQuat = Quaternion(myQuat)

CrossQuats(quat1, quat2)

source code

Return the cross product of two quaternions.

Parameters:

quat1 (Quaternion object.) - Quaternion.
quat2 (Quaternion object.) - Quaternion.

Returns: Quaternion object.

A new quaternion representing the cross product of the two quaternions.

Attention: DEPRECATED use quat.cross(other) instead.

DotQuats(quat1, quat2)

source code

Return the dot product of two quaternions.

Parameters:

quat1 (Quaternion object.) - Quaternion.
quat2 (Quaternion object.) - Quaternion.

Returns: float

Return the scalar product of quaternion muliplication.

Attention: DEPRECATED use quat.dot(other) instead.

DifferenceQuats(quat1, quat2)

source code

Returns a quaternion represting the rotational difference.

Parameters:

quat1 (Quaternion object.) - Quaternion.
quat2 (Quaternion object.) - Quaternion.

Returns: Quaternion object

Return a quaternion which which represents the rotational difference between the two quat rotations.

Slerp(quat1, quat2, factor)

source code

Returns the interpolation of two quaternions.

Parameters:

quat1 (Quaternion object.) - Quaternion.
quat2 (Quaternion object.) - Quaternion.
factor (float) - The interpolation value

Returns: Quaternion object

The interpolated rotation.

CopyEuler(euler)

source code

Create a new euler object.

Parameters:

euler (Euler object) - The euler to copy

Returns: Euler object

A copy of the euler object passed in.

Attention: DEPRECATED You should use the Euler constructor directly to make copies of Euler objects Example:

   newEuler = Euler(myEuler)

RotateEuler(euler, angle, axis)

source code

Roatate a euler by an amount in degrees around an axis.

Parameters:

euler (Euler object) - Euler to rotate.
angle (float) - The amount of rotation in degrees
axis (string) - axis to rotate around:
- "x"
- "y"
- "z"