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
list	`PolyFill(polylines)` Takes a list of polylines and calculates triangles that would fill in the polylines.
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). 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 - 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.)

PolyFill(polylines)

Takes a list of polylines and calculates triangles that would fill in the polylines. Multiple lines can be used to make holes inside a polyline, or fill in 2 seperate lines at once.

Parameters:: polylines
(type=List of lists containing vectors, each representing a closed polyline.)

Returns:: a list if tuples each a tuple of 3 ints representing a triangle indexing the points given.
(type=list)

Note: 2D Vectors will have an assumed Z axis of zero, 4D Vectors W axis is ignored.

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 Jul 13 16:50:05 2006

http://epydoc.sf.net