Module Mathutils

Module Mathutils

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
`Euler`	This object gives access to Eulers in Blender.
`Matrix`	This object gives access to Matrices in Blender.
`Quaternion`	This object gives access to Quaternions in Blender.
`Vector`	This object gives access to Vectors in Blender.

Function Summary
float	`AngleBetweenVecs(vec1, vec2)` Return the angle between two vectors.
Euler object	`CopyEuler(euler)` Create a new euler object.
Matrix object.	`CopyMat(matrix)` Create a copy of the Matrix object.
Quaternion object.	`CopyQuat(quaternion)` Create a copy of the Quaternion object.
Vector object.	`CopyVec(vector)` Create a copy of the Vector object.
Quaternion object.	`CrossQuats(quat1, quat2)` Return the cross product of two quaternions.
Vector object.	`CrossVecs(vec1, vec2)` Return the cross product of two vectors.
Quaternion object	`DifferenceQuats(quat1, quat2)` Returns a quaternion represting the rotational difference.
float	`DotQuats(quat1, quat2)` Return the dot product of two quaternions.
float	`DotVecs(vec1, vec2)` Return the dot product of two vectors.
Vector object	`Intersect(vec1, vec2, vec3, ray, orig, clip)` Return the intersection between a ray and a triangle, if possible, return None otherwise.
(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).
Vector object	`MatMultVec(mat, vec)` Multiply a matrix and a vector (post-multiply) Vector size and matrix row size must equal.
Vector object	`MidpointVecs(vec1, vec2)` Return a vector to the midpoint between two vectors.
Matrix object.	`OrthoProjectionMatrix(plane, matSize, axis)` Create a matrix to represent an orthographic projection
Vector object	`ProjectVecs(vec1, vec2)` Return the projection of vec1 onto vec2.
float	`QuadNormal(vec1, vec2, vec3, vec4)` Return the normal of the 3D quad defined.
	`Rand(high, low)` Return a random number within a range.
	`RotateEuler(euler, angle, axis)` Roatate a euler by an amount in degrees around an axis.
Matrix object.	`RotationMatrix(angle, matSize, axisFlag, axis)` Create a matrix representing a rotation.
Matrix object.	`ScaleMatrix(factor, matSize, axis)` Create a matrix representing a scaling.
Matrix object.	`ShearMatrix(plane, factor, matSize)` Create a matrix to represent an orthographic projection
Quaternion object	`Slerp(quat1, quat2, factor)` Returns the interpolation of two quaternions.
Matrix object.	`TranslationMatrix(vector)` Create a matrix representing a translation
float	`TriangleArea(vec1, vec2, vec3)` Return the area size of the 2D or 3D triangle defined.
float	`TriangleNormal(vec1, vec2, vec3)` Return the normal of the 3D triangle defined.
Vector object	`VecMultMat(vec, mat)` Multiply a vector and matrix (pre-multiply) Vector size and matrix column size must equal.

Function Details

AngleBetweenVecs(vec1, vec2)

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

Parameters:: vec1 - A 2d or 3d vector.
(type=Vector object.); vec2 - A 2d or 3d vector.
(type=Vector object.)

Returns:: The angle between the vectors in degrees.
(type=float)

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

CopyEuler(euler)

Create a new euler object.

Parameters:: euler - The euler to copy
(type=Euler object)

Returns:: A copy of the euler object passed in.
(type=Euler object)

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

   newEuler = Euler(myEuler)

CopyMat(matrix)

Create a copy of the Matrix object.

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

Returns:: A new matrix object which is a copy of the one passed in.
(type=Matrix object.)

Attention: DEPRECATED You should use the matrix constructor to create a copy of a matrix Example:

   newMat = Matrix(myMat)

CopyQuat(quaternion)

Create a copy of the Quaternion object.

Parameters:: quaternion - Quaternion to be copied.
(type=Quaternion object.)

Returns:: A new quaternion object which is a copy of the one passed in.
(type=Quaternion object.)

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

   newQuat = Quaternion(myQuat)

CopyVec(vector)

Create a copy of the Vector object.

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

Returns:: A new vector object which is a copy of the one passed in.
(type=Vector object.)

Attention: DEPRECATED use Vector(vector) instead.

CrossQuats(quat1, quat2)

Return the cross product of two quaternions.

Parameters:: quat1 - Quaternion.
(type=Quaternion object.); quat2 - Quaternion.
(type=Quaternion object.)

Returns:: A new quaternion representing the cross product of the two quaternions.
(type=Quaternion object.)

CrossVecs(vec1, vec2)

Return the cross product of two vectors.

Parameters:: vec1 - A 3d vector.
(type=Vector object.); vec2 - A 3d vector.
(type=Vector object.)

Returns:: A new vector representing the cross product of the two vectors.
(type=Vector object.)

DifferenceQuats(quat1, quat2)

Returns a quaternion represting the rotational difference.

Parameters:: quat1 - Quaternion.
(type=Quaternion object.); quat2 - Quaternion.
(type=Quaternion object.)

Returns:: Return a quaternion which which represents the rotational difference between the two quat rotations.
(type=Quaternion object)

DotQuats(quat1, quat2)

Return the dot product of two quaternions.

Parameters:: quat1 - Quaternion.
(type=Quaternion object.); quat2 - Quaternion.
(type=Quaternion object.)

Returns:: Return the scalar product of quaternion muliplication.
(type=float)

DotVecs(vec1, vec2)

Return the dot product of two vectors.

Parameters:: vec1 - A 2d,3d or 4d vector.
(type=Vector object.); vec2 - A 2d,3d or 4d vector.
(type=Vector object.)

Returns:: Return the scalar product of vector muliplication.
(type=float)

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

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

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

Returns:: The intersection between a ray and a triangle, if possible, None otherwise.
(type=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).

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

Returns:: A tuple with the points on each line respectively closest to the other.
(type=(Vector object, Vector object))

MatMultVec(mat, vec)

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

Parameters:: mat - A 2d,3d or 4d matrix.
(type=Matrix object.); vec - A 2d,3d or 4d vector.
(type=Vector object.)

Returns:: The column vector that results from the muliplication.
(type=Vector object)

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

   result = myMatrix * myVector

MidpointVecs(vec1, vec2)

Return a vector to the midpoint between two vectors.

Parameters:: vec1 - A 2d,3d or 4d vector.
(type=Vector object.); vec2 - A 2d,3d or 4d vector.
(type=Vector object.)

Returns:: The vector to the midpoint.
(type=Vector object)

OrthoProjectionMatrix(plane, matSize, axis)

Create a matrix to represent an orthographic projection

Parameters:

plane - 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"

(type=string)

matSize - The size of the projection matrix to construct. Can be 2d, 3d, or 4d.
(type=int)

axis - Arbitrary perpendicular plane vector.
(type=Vector object. (optional))

Returns:: A new projeciton matrix.
(type=Matrix object.)

ProjectVecs(vec1, vec2)

Return the projection of vec1 onto vec2.

Parameters:: vec1 - A 2d,3d or 4d vector.
(type=Vector object.); vec2 - A 2d,3d or 4d vector.
(type=Vector object.)

Returns:: The parallel projection vector.
(type=Vector object)

QuadNormal(vec1, vec2, vec3, vec4)

Return the normal of the 3D quad defined.

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

Returns:: The normal of the 3D quad defined.
(type=float)

Rand(high=1, low=0)

Return a random number within a range. High and low represent the range from which the random number must return its result.

Parameters:: high - The upper range.
(type=float); low - The lower range.
(type=float)

RotateEuler(euler, angle, axis)

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

Parameters:

euler - Euler to rotate.
(type=Euler object)

angle - The amount of rotation in degrees
(type=float)

axis - axis to rotate around:

(type=string)

RotationMatrix(angle, matSize, axisFlag, axis)

Create a matrix representing a rotation.

Parameters:

angle - The angle of rotation desired.
(type=float)

matSize - The size of the rotation matrix to construct. Can be 2d, 3d, or 4d.
(type=int)

axisFlag - Possible values:

"x - x-axis rotation"
"y - y-axis rotation"
"z - z-axis rotation"
"r - arbitrary rotation around vector"

(type=string (optional))

axis - The arbitrary axis of rotation used with "R"
(type=Vector object. (optional))

Returns:: A new rotation matrix.
(type=Matrix object.)

ScaleMatrix(factor, matSize, axis)

Create a matrix representing a scaling.

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

Returns:: A new scale matrix.
(type=Matrix object.)

ShearMatrix(plane, factor, matSize)

Create a matrix to represent an orthographic projection

Parameters:

plane - Can be any of the following:

"x - x shear (2D)"
"y - y shear (2D)"
"xy - xy shear"
"xz - xz shear"
"yz - yz shear"

(type=string)

factor - The factor of shear to apply.
(type=float)

matSize - The size of the projection matrix to construct. Can be 2d, 3d, or 4d.
(type=int)

Returns:: A new shear matrix.
(type=Matrix object.)

Slerp(quat1, quat2, factor)

Returns the interpolation of two quaternions.

Parameters:: quat1 - Quaternion.
(type=Quaternion object.); quat2 - Quaternion.
(type=Quaternion object.); factor - The interpolation value
(type=float)

Returns:: The interpolated rotation.
(type=Quaternion object)

TranslationMatrix(vector)

Create a matrix representing a translation

Parameters:: vector - The translation vector
(type=Vector object)

Returns:: An identity matrix with a translation.
(type=Matrix object.)

TriangleArea(vec1, vec2, vec3)

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

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

Returns:: The area size of the 2D or 3D triangle defined.
(type=float)

TriangleNormal(vec1, vec2, vec3)

Return the normal of the 3D triangle defined.

Parameters:: vec1 - A 3d vector, one corner of the triangle.
(type=Vector object.); vec2 - A 3d vector, one corner of the triangle.
(type=Vector object.); vec3 - A 3d vector, one corner of the triangle.
(type=Vector object.)

Returns:: The normal of the 3D triangle defined.
(type=float)

VecMultMat(vec, mat)

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

Parameters:: vec - A 2d,3d or 4d vector.
(type=Vector object.); mat - A 2d,3d or 4d matrix.
(type=Matrix object.)

Returns:: The row vector that results from the muliplication.
(type=Vector object)

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

   result = myVector * myMatrix

Generated by Epydoc 2.1 on Thu Jan 26 09:17:44 2006

http://epydoc.sf.net