Module Mathutils

Module Mathutils

source code

The Blender.Mathutils submodule.

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
  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
 
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
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
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
VecMultMat(vec, mat)
Multiply a vector and matrix (pre-multiply) Vector size and matrix column size must equal.
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
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
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
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

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.

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.

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.

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.

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"