Joseph Gilbert
9656e8be02
- adds intersections for lines - triangle area - tracking quaternion from vector - some helpful normal calculators
676 lines
18 KiB
Python
676 lines
18 KiB
Python
# Blender.Mathutils module and its subtypes
|
|
|
|
"""
|
|
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
|
|
"""
|
|
|
|
def 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.
|
|
@type high: float
|
|
@param high: The upper range.
|
|
@type low: float
|
|
@param low: The lower range.
|
|
"""
|
|
|
|
def Intersect(vec1, vec2, vec3, ray, orig, clip=1):
|
|
"""
|
|
Return the intersection between a ray and a triangle, if possible, return None otherwise.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 3d vector, one corner of the triangle.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 3d vector, one corner of the triangle.
|
|
@type vec3: Vector object.
|
|
@param vec3: A 3d vector, one corner of the triangle.
|
|
@type ray: Vector object.
|
|
@param ray: A 3d vector, the orientation of the ray.
|
|
@type orig: Vector object.
|
|
@param orig: A 3d vector, the origin of the ray.
|
|
@type clip: integer
|
|
@param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.
|
|
@rtype: Vector object
|
|
@return: The intersection between a ray and a triangle, if possible, None otherwise.
|
|
"""
|
|
|
|
def TriangleArea(vec1, vec2, vec3):
|
|
"""
|
|
Return the area size of the 2D or 3D triangle defined.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 2d or 3d vector, one corner of the triangle.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 2d or 3d vector, one corner of the triangle.
|
|
@type vec3: Vector object.
|
|
@param vec3: A 2d or 3d vector, one corner of the triangle.
|
|
@rtype: float
|
|
@return: The area size of the 2D or 3D triangle defined.
|
|
"""
|
|
|
|
def TriangleNormal(vec1, vec2, vec3):
|
|
"""
|
|
Return the normal of the 3D triangle defined.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 3d vector, one corner of the triangle.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 3d vector, one corner of the triangle.
|
|
@type vec3: Vector object.
|
|
@param vec3: A 3d vector, one corner of the triangle.
|
|
@rtype: float
|
|
@return: The normal of the 3D triangle defined.
|
|
"""
|
|
|
|
def QuadNormal(vec1, vec2, vec3, vec4):
|
|
"""
|
|
Return the normal of the 3D quad defined.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 3d vector, the first vertex of the quad.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 3d vector, the second vertex of the quad.
|
|
@type vec3: Vector object.
|
|
@param vec3: A 3d vector, the third vertex of the quad.
|
|
@type vec4: Vector object.
|
|
@param vec4: A 3d vector, the fourth vertex of the quad.
|
|
@rtype: float
|
|
@return: The normal of the 3D quad defined.
|
|
"""
|
|
|
|
def 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).
|
|
@type vec1: Vector object.
|
|
@param vec1: A 3d vector, one point on the first line.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 3d vector, another point on the first line.
|
|
@type vec3: Vector object.
|
|
@param vec3: A 3d vector, one point on the second line.
|
|
@type vec4: Vector object.
|
|
@param vec4: A 3d vector, another point on the second line.
|
|
@rtype: (Vector object, Vector object)
|
|
@return: A tuple with the points on each line respectively closest to the other.
|
|
"""
|
|
|
|
def CopyVec(vector):
|
|
"""
|
|
Create a copy of the Vector object.
|
|
@type vector: Vector object.
|
|
@param vector: A 2d,3d or 4d vector to be copied.
|
|
@rtype: Vector object.
|
|
@return: A new vector object which is a copy of the one passed in.
|
|
"""
|
|
|
|
def CrossVecs(vec1, vec2):
|
|
"""
|
|
Return the cross product of two vectors.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 3d vector.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 3d vector.
|
|
@rtype: Vector object.
|
|
@return: A new vector representing the cross product of
|
|
the two vectors.
|
|
"""
|
|
|
|
def DotVecs(vec1, vec2):
|
|
"""
|
|
Return the dot product of two vectors.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 2d,3d or 4d vector.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 2d,3d or 4d vector.
|
|
@rtype: float
|
|
@return: Return the scalar product of vector muliplication.
|
|
"""
|
|
|
|
def AngleBetweenVecs(vec1, vec2):
|
|
"""
|
|
Return the angle between two vectors.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 2d or 3d vector.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 2d or 3d vector.
|
|
@rtype: float
|
|
@return: The angle between the vectors in degrees.
|
|
"""
|
|
|
|
def MidpointVecs(vec1, vec2):
|
|
"""
|
|
Return a vector to the midpoint between two vectors.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 2d,3d or 4d vector.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 2d,3d or 4d vector.
|
|
@rtype: Vector object
|
|
@return: The vector to the midpoint.
|
|
"""
|
|
|
|
def VecMultMat(vec, mat):
|
|
"""
|
|
Multiply a vector and matrix (pre-multiply)
|
|
Vector size and matrix column size must equal.
|
|
@type vec: Vector object.
|
|
@param vec: A 2d,3d or 4d vector.
|
|
@type mat: Matrix object.
|
|
@param mat: A 2d,3d or 4d matrix.
|
|
@rtype: Vector object
|
|
@return: The row vector that results from the muliplication.
|
|
"""
|
|
|
|
def ProjectVecs(vec1, vec2):
|
|
"""
|
|
Return the projection of vec1 onto vec2.
|
|
@type vec1: Vector object.
|
|
@param vec1: A 2d,3d or 4d vector.
|
|
@type vec2: Vector object.
|
|
@param vec2: A 2d,3d or 4d vector.
|
|
@rtype: Vector object
|
|
@return: The parallel projection vector.
|
|
"""
|
|
|
|
def RotationMatrix(angle, matSize, axisFlag, axis):
|
|
"""
|
|
Create a matrix representing a rotation.
|
|
@type angle: float
|
|
@param angle: The angle of rotation desired.
|
|
@type matSize: int
|
|
@param matSize: The size of the rotation matrix to construct.
|
|
Can be 2d, 3d, or 4d.
|
|
@type axisFlag: string (optional)
|
|
@param axisFlag: Possible values:
|
|
- "x - x-axis rotation"
|
|
- "y - y-axis rotation"
|
|
- "z - z-axis rotation"
|
|
- "r - arbitrary rotation around vector"
|
|
@type axis: Vector object. (optional)
|
|
@param axis: The arbitrary axis of rotation used with "R"
|
|
@rtype: Matrix object.
|
|
@return: A new rotation matrix.
|
|
"""
|
|
|
|
def TranslationMatrix(vector):
|
|
"""
|
|
Create a matrix representing a translation
|
|
@type vector: Vector object
|
|
@param vector: The translation vector
|
|
@rtype: Matrix object.
|
|
@return: An identity matrix with a translation.
|
|
"""
|
|
|
|
def ScaleMatrix(factor, matSize, axis):
|
|
"""
|
|
Create a matrix representing a scaling.
|
|
@type factor: float
|
|
@param factor: The factor of scaling to apply.
|
|
@type matSize: int
|
|
@param matSize: The size of the scale matrix to construct.
|
|
Can be 2d, 3d, or 4d.
|
|
@type axis: Vector object. (optional)
|
|
@param axis: Direction to influence scale.
|
|
@rtype: Matrix object.
|
|
@return: A new scale matrix.
|
|
"""
|
|
|
|
def OrthoProjectionMatrix(plane, matSize, axis):
|
|
"""
|
|
Create a matrix to represent an orthographic projection
|
|
@type plane: string
|
|
@param 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 matSize: int
|
|
@param matSize: The size of the projection matrix to construct.
|
|
Can be 2d, 3d, or 4d.
|
|
@type axis: Vector object. (optional)
|
|
@param axis: Arbitrary perpendicular plane vector.
|
|
@rtype: Matrix object.
|
|
@return: A new projeciton matrix.
|
|
"""
|
|
|
|
def ShearMatrix(plane, factor, matSize):
|
|
"""
|
|
Create a matrix to represent an orthographic projection
|
|
@type plane: string
|
|
@param 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 factor: float
|
|
@param factor: The factor of shear to apply.
|
|
@type matSize: int
|
|
@param matSize: The size of the projection matrix to construct.
|
|
Can be 2d, 3d, or 4d.
|
|
@rtype: Matrix object.
|
|
@return: A new shear matrix.
|
|
"""
|
|
|
|
def CopyMat(matrix):
|
|
"""
|
|
Create a copy of the Matrix object.
|
|
@type matrix: Matrix object.
|
|
@param matrix: A 2d,3d or 4d matrix to be copied.
|
|
@rtype: Matrix object.
|
|
@return: A new matrix object which is a copy of the one passed in.
|
|
"""
|
|
|
|
def MatMultVec(mat, vec):
|
|
"""
|
|
Multiply a matrix and a vector (post-multiply)
|
|
Vector size and matrix row size must equal.
|
|
@type vec: Vector object.
|
|
@param vec: A 2d,3d or 4d vector.
|
|
@type mat: Matrix object.
|
|
@param mat: A 2d,3d or 4d matrix.
|
|
@rtype: Vector object
|
|
@return: The column vector that results from the muliplication.
|
|
"""
|
|
|
|
def CopyQuat(quaternion):
|
|
"""
|
|
Create a copy of the Quaternion object.
|
|
@type quaternion: Quaternion object.
|
|
@param quaternion: Quaternion to be copied.
|
|
@rtype: Quaternion object.
|
|
@return: A new quaternion object which is a copy of the one passed in.
|
|
"""
|
|
|
|
def CrossQuats(quat1, quat2):
|
|
"""
|
|
Return the cross product of two quaternions.
|
|
@type quat1: Quaternion object.
|
|
@param quat1: Quaternion.
|
|
@type quat2: Quaternion object.
|
|
@param quat2: Quaternion.
|
|
@rtype: Quaternion object.
|
|
@return: A new quaternion representing the cross product of
|
|
the two quaternions.
|
|
"""
|
|
|
|
def DotQuats(quat1, quat2):
|
|
"""
|
|
Return the dot product of two quaternions.
|
|
@type quat1: Quaternion object.
|
|
@param quat1: Quaternion.
|
|
@type quat2: Quaternion object.
|
|
@param quat2: Quaternion.
|
|
@rtype: float
|
|
@return: Return the scalar product of quaternion muliplication.
|
|
"""
|
|
|
|
def DifferenceQuats(quat1, quat2):
|
|
"""
|
|
Returns a quaternion represting the rotational difference.
|
|
@type quat1: Quaternion object.
|
|
@param quat1: Quaternion.
|
|
@type quat2: Quaternion object.
|
|
@param quat2: Quaternion.
|
|
@rtype: Quaternion object
|
|
@return: Return a quaternion which which represents the rotational
|
|
difference between the two quat rotations.
|
|
"""
|
|
|
|
def Slerp(quat1, quat2, factor):
|
|
"""
|
|
Returns the interpolation of two quaternions.
|
|
@type quat1: Quaternion object.
|
|
@param quat1: Quaternion.
|
|
@type quat2: Quaternion object.
|
|
@param quat2: Quaternion.
|
|
@type factor: float
|
|
@param factor: The interpolation value
|
|
@rtype: Quaternion object
|
|
@return: The interpolated rotation.
|
|
"""
|
|
|
|
def CopyEuler(euler):
|
|
"""
|
|
Create a new euler object.
|
|
@type euler: Euler object
|
|
@param euler: The euler to copy
|
|
@rtype: Euler object
|
|
@return: A copy of the euler object passed in.
|
|
"""
|
|
|
|
def RotateEuler(euler, angle, axis):
|
|
"""
|
|
Roatate a euler by an amount in degrees around an axis.
|
|
@type euler: Euler object
|
|
@param euler: Euler to rotate.
|
|
@type angle: float
|
|
@param angle: The amount of rotation in degrees
|
|
@type axis: string
|
|
@param axis: axis to rotate around:
|
|
- "x"
|
|
- "y"
|
|
- "z"
|
|
"""
|
|
|
|
class Vector:
|
|
"""
|
|
The Vector object
|
|
=================
|
|
This object gives access to Vectors in Blender.
|
|
@ivar x: The x value.
|
|
@ivar y: The y value.
|
|
@ivar z: The z value (if any).
|
|
@ivar w: The w value (if any).
|
|
@ivar length: The magnitude of the vector.
|
|
"""
|
|
|
|
def __init__(list = None):
|
|
"""
|
|
Create a new Vector object from a list.
|
|
|
|
Example::
|
|
v = Blender.Mathutils.Vector([1,0,0])
|
|
@type list: PyList of float or int
|
|
@param list: The list of values for the Vector object.
|
|
Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w].
|
|
@rtype: Vector object.
|
|
@return: It depends wheter a parameter was passed:
|
|
- (list): Vector object initialized with the given values;
|
|
- (): An empty 3 dimensional vector.
|
|
"""
|
|
|
|
def zero():
|
|
"""
|
|
Set all values to zero.
|
|
"""
|
|
|
|
def normalize():
|
|
"""
|
|
Normalize the vector.
|
|
"""
|
|
|
|
def negate():
|
|
"""
|
|
Set all values to their negative.
|
|
"""
|
|
|
|
def resize2D():
|
|
"""
|
|
Resize the vector to 2d.
|
|
"""
|
|
|
|
def resize3D():
|
|
"""
|
|
Resize the vector to 3d.
|
|
"""
|
|
|
|
def resize4D():
|
|
"""
|
|
Resize the vector to 4d.
|
|
"""
|
|
|
|
def toTrackQuat(track, up):
|
|
"""
|
|
Return a quaternion rotation from the vector and the track and up axis.
|
|
@type track: String.
|
|
@param track: Possible values:
|
|
- "x - x-axis up"
|
|
- "y - y-axis up"
|
|
- "z - z-axis up"
|
|
- "-x - negative x-axis up"
|
|
- "-y - negative y-axis up"
|
|
- "-z - negative z-axis up"
|
|
@type up: String.
|
|
@param up: Possible values:
|
|
- "x - x-axis up"
|
|
- "y - y-axis up"
|
|
- "z - z-axis up"
|
|
@rtype: Quaternion
|
|
@return: Return a quaternion rotation from the vector and the track and up axis.
|
|
"""
|
|
|
|
class Euler:
|
|
"""
|
|
The Euler object
|
|
================
|
|
This object gives access to Eulers in Blender.
|
|
@ivar x: The heading value in degrees.
|
|
@ivar y: The pitch value in degrees.
|
|
@ivar z: The roll value in degrees.
|
|
"""
|
|
|
|
def __init__(list = None):
|
|
"""
|
|
Create a new euler object.
|
|
|
|
Example::
|
|
euler = Euler([45,0,0])
|
|
@type list: PyList of float/int
|
|
@param list: 3d list to initialize euler
|
|
@rtype: Euler object
|
|
@return: Euler representing heading, pitch, bank.
|
|
@note: Values are in degrees.
|
|
"""
|
|
|
|
def zero():
|
|
"""
|
|
Set all values to zero.
|
|
"""
|
|
|
|
def unique():
|
|
"""
|
|
Calculate a unique rotation for this euler.
|
|
"""
|
|
|
|
def toMatrix():
|
|
"""
|
|
Return a matrix representation of the euler.
|
|
@rtype: Matrix object
|
|
@return: A roation matrix representation of the euler.
|
|
|
|
"""
|
|
|
|
def toQuat():
|
|
"""
|
|
Return a quaternion representation of the euler.
|
|
@rtype: Quaternion object
|
|
@return: Quaternion representation of the euler.
|
|
|
|
"""
|
|
|
|
class Quaternion:
|
|
"""
|
|
The Quaternion object
|
|
=====================
|
|
This object gives access to Quaternions in Blender.
|
|
@ivar w: The w value.
|
|
@ivar x: The x value.
|
|
@ivar y: The y value.
|
|
@ivar z: The z value.
|
|
@ivar magnitude: The magnitude of the quaternion.
|
|
@ivar axis: Vector representing the axis of rotation.
|
|
@ivar angle: A scalar representing the amount of rotation
|
|
in degrees.
|
|
"""
|
|
|
|
def __init__(list, angle = None):
|
|
"""
|
|
Create a new quaternion object from initialized values.
|
|
|
|
Example::
|
|
quat = Mathutils.Quaternion([1.0,0.0,0.0])
|
|
|
|
@type list: PyList of int/float
|
|
@param list: A 3d or 4d list to initialize quaternion.
|
|
4d if intializing [w,x,y,z], 3d if used as an axis of rotation.
|
|
@type angle: float (optional)
|
|
@param angle: An arbitrary rotation amount around 'list'.
|
|
List is used as an axis of rotation in this case.
|
|
@rtype: New quaternion object.
|
|
@return: It depends wheter a parameter was passed:
|
|
- (list/angle): Quaternion object initialized with the given values;
|
|
- (): An identity 4 dimensional quaternion.
|
|
"""
|
|
|
|
def identity():
|
|
"""
|
|
Set the quaternion to the identity quaternion.
|
|
"""
|
|
|
|
def negate():
|
|
"""
|
|
Set the quaternion to it's negative.
|
|
"""
|
|
|
|
def conjugate():
|
|
"""
|
|
Set the quaternion to it's conjugate.
|
|
"""
|
|
|
|
def inverse():
|
|
"""
|
|
Set the quaternion to it's inverse
|
|
"""
|
|
|
|
def normalize():
|
|
"""
|
|
Normalize the quaternion.
|
|
"""
|
|
|
|
def toEuler():
|
|
"""
|
|
Return Euler representation of the quaternion.
|
|
@rtype: Euler object
|
|
@return: Euler representation of the quaternion.
|
|
|
|
"""
|
|
|
|
def toMatrix():
|
|
"""
|
|
Return a matrix representation of the quaternion.
|
|
@rtype: Matrix object
|
|
@return: A rotation matrix representation of the quaternion.
|
|
|
|
"""
|
|
|
|
class Matrix:
|
|
"""
|
|
The Matrix Object
|
|
=================
|
|
This object gives access to Matrices in Blender.
|
|
@ivar rowsize: The row size of the matrix.
|
|
@ivar colsize: The column size of the matrix.
|
|
"""
|
|
|
|
def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
|
|
"""
|
|
Create a new matrix object from initialized values.
|
|
|
|
Example::
|
|
matrix = Mathutils.Matrix([1,1,1],[0,1,0],[1,0,0])
|
|
|
|
@type list1: PyList of int/float
|
|
@param list1: A 2d,3d or 4d list.
|
|
@type list2: PyList of int/float
|
|
@param list2: A 2d,3d or 4d list.
|
|
@type list3: PyList of int/float
|
|
@param list3: A 2d,3d or 4d list.
|
|
@type list4: PyList of int/float
|
|
@param list4: A 2d,3d or 4d list.
|
|
@rtype: New matrix object.
|
|
@return: It depends wheter a parameter was passed:
|
|
- (list1, etc.): Matrix object initialized with the given values;
|
|
- (): An empty 3 dimensional matrix.
|
|
"""
|
|
|
|
def zero():
|
|
"""
|
|
Set all matrix values to 0.
|
|
"""
|
|
|
|
def identity():
|
|
"""
|
|
Set the matrix to the identity matrix.
|
|
"""
|
|
|
|
def transpose():
|
|
"""
|
|
Set the matrix to it's transpose.
|
|
"""
|
|
|
|
def determinant():
|
|
"""
|
|
Return the determinant of a matrix.
|
|
@rtype: int
|
|
@return: Return a the determinant of a matrix.
|
|
|
|
"""
|
|
|
|
def invert():
|
|
"""
|
|
Set the matrix to it's inverse.
|
|
"""
|
|
|
|
def rotationPart():
|
|
"""
|
|
Return the 3d submatrix corresponding to the linear term of the
|
|
embedded affine transformation in 3d. This matrix represents rotation
|
|
and scale. Note that the (4,4) element of a matrix can be used for uniform
|
|
scaling, too.
|
|
@rtype: Matrix object.
|
|
@return: Return the 3d matrix for rotation and scale.
|
|
|
|
"""
|
|
|
|
def translationPart():
|
|
"""
|
|
Return a the translation part of a 4 row matrix.
|
|
@rtype: Vector object.
|
|
@return: Return a the translation of a matrix.
|
|
|
|
"""
|
|
|
|
def resize4x4():
|
|
"""
|
|
Resize the matrix to by 4x4
|
|
"""
|
|
|
|
def toEuler():
|
|
"""
|
|
Return an Euler representation of the rotation matrix.
|
|
@rtype: Euler object
|
|
@return: Euler representation of the rotation matrix.
|
|
|
|
"""
|
|
|
|
def toQuat():
|
|
"""
|
|
Return a quaternion representation of the rotation matrix
|
|
@rtype: Quaternion object
|
|
@return: Quaternion representation of the rotation matrix
|
|
|
|
"""
|
|
|