archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Mathutils refactor & include in sphinx generated docs, (TODO, include getset'ers in docs)

Browse Source 
- Mathutils.MidpointVecs --> vector.lerp(other, fac)
 - Mathutils.AngleBetweenVecs --> vector.angle(other)
 - Mathutils.ProjectVecs --> vector.project(other)
 - Mathutils.DifferenceQuats --> quat.difference(other)
 - Mathutils.Slerp --> quat.slerp(other, fac)
 - Mathutils.Rand: removed, use pythons random module
 - Mathutils.RotationMatrix(angle, size, axis_flag, axis) --> Mathutils.RotationMatrix(angle, size, axis); merge axis & axis_flag args
 - Matrix.scalePart --> Matrix.scale_part
 - Matrix.translationPart --> Matrix.translation_part
 - Matrix.rotationPart --> Matrix.rotation_part
 - toMatrix --> to_matrix
 - toEuler --> to_euler
 - toQuat --> to_quat
 - Vector.toTrackQuat --> Vector.to_track_quat
This commit is contained in:
Campbell Barton
2010-01-25 09:44:04 +00:00
parent eed13d859b
commit 0a0f4c9d81
26 changed files with 1540 additions and 1714 deletions
Download Patch File Download Diff File Expand all files Collapse all files

530
source/blender/python/doc/epy/Mathutils.py
View File

@@ -22,242 +22,13 @@ Example::
matTotal.invert()
mat3 = matTotal.rotationPart
quat1 = mat.toQuat()
quat2 = mat3.toQuat()
quat1 = mat.to_quat()
quat2 = mat3.to_quat()
angle = DifferenceQuats(quat1, quat2)
print angle
"""
def Rand (low=0.0, high = 1.0):
"""
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.
@type low: float
@param low: The lower range.
@type high: float
@param high: The upper 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. the length of the ray is not used, only the direction.
@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).
The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.
@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 AngleBetweenVecs(vec1, vec2):
"""
Return the angle between two vectors. Zero length vectors raise an error.
@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.
@raise AttributeError: When there is a zero-length vector as an argument.
"""
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 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 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.
"""
class Vector:
"""
The Vector object
@@ -330,100 +101,6 @@ class Vector:
- (): An empty 3 dimensional vector.
"""
def copy():
"""
Returns a copy of this vector
@return: a copy of itself
"""
def zero():
"""
Set all values to zero.
@return: an instance of itself
"""
def normalize():
"""
Normalize the vector, making the length of the vector always 1.0
@note: Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched.
@note: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).
@return: an instance of itself
"""
def negate():
"""
Set all values to their negative.
@return: an instance of its self
"""
def resize2D():
"""
Resize the vector to 2d.
@return: an instance of itself
"""
def resize3D():
"""
Resize the vector to 3d. New axis will be 0.0.
@return: an instance of itself
"""
def resize4D():
"""
Resize the vector to 4d. New axis will be 0.0.
The last component will be 1.0, to make multiplying 3d vectors by 4x4 matrices easier.
@return: an instance of itself
"""
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.
"""
def reflect(mirror):
"""
Return the reflection vector from the mirror vector argument.
@type mirror: Vector object
@param mirror: This vector could be a normal from the reflecting surface.
@rtype: Vector object matching the size of this vector.
@return: The reflected vector.
"""
def cross(other):
"""
Return the cross product of this vector and another.
@note: both vectors must be 3D.
@type other: Vector object
@param other: The other vector to perform the cross product with.
@rtype: Vector
@return: The cross product.
"""
def dot(other):
"""
Return the dot product of this vector and another.
@note: both vectors must be the same size.
@type other: Vector object
@param other: The other vector to perform the dot product with.
@rtype: float
@return: The dot product.
"""
class Euler:
"""
The Euler object
@@ -470,43 +147,6 @@ class Euler:
@note: Values are in degrees.
"""
def zero():
"""
Set all values to zero.
@return: an instance of itself
"""
def copy():
"""
@return: a copy of this euler.
"""
def unique():
"""
Calculate a unique rotation for this euler. Avoids gimble lock.
@return: an instance of itself
"""
def toMatrix():
"""
Return a matrix representation of the euler.
@rtype: Matrix object
@return: A 3x3 roation matrix representation of the euler.
"""
def toQuat():
"""
Return a quaternion representation of the euler.
@rtype: Quaternion object
@return: Quaternion representation of the euler.
"""
def makeCompatible(eul_compat):
"""
Make this euler compatible with another, so interpolating between them works as expected.
@rtype: Euler object
@return: an instance of itself
"""
class Quaternion:
"""
The Quaternion object
@@ -571,76 +211,6 @@ class Quaternion:
- (): An identity 4 dimensional quaternion.
"""
def identity():
"""
Set the quaternion to the identity quaternion.
@return: an instance of itself
"""
def copy():
"""
make a copy of the quaternion.
@return: a copy of itself
"""
def negate():
"""
Set the quaternion to its negative.
@return: an instance of itself
"""
def conjugate():
"""
Set the quaternion to its conjugate.
@return: an instance of itself
"""
def inverse():
"""
Set the quaternion to its inverse
@return: an instance of itself
"""
def normalize():
"""
Normalize the quaternion.
@return: an instance of itself
"""
def toEuler(eul_compat):
"""
Return Euler representation of the quaternion.
@type eul_compat: L{Euler}
@param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
@rtype: Euler object
@return: Euler representation of the quaternion.
"""
def toMatrix():
"""
Return a matrix representation of the quaternion.
@rtype: Matrix object
@return: A 3x3 rotation matrix representation of the quaternion.
"""
def cross(other):
"""
Return the cross product of this quaternion and another.
@type other: Quaterion object
@param other: The other quaternion to perform the cross product with.
@rtype: Vector
@return: The cross product.
"""
def dot(other):
"""
Return the dot product of this quaternion and another.
@type other: Quaterion object
@param other: The other quaternion to perform the dot product with.
@rtype: float
@return: The dot product.
"""
class Matrix:
"""
The Matrix Object
@@ -699,99 +269,3 @@ class Matrix:
- (list1, etc.): Matrix object initialized with the given values;
- (): An empty 3 dimensional matrix.
"""
def zero():
"""
Set all matrix values to 0.
@return: an instance of itself
"""
def copy():
"""
Returns a copy of this matrix
@return: a copy of itself
"""
def identity():
"""
Set the matrix to the identity matrix.
An object with zero location and rotation, a scale of 1, will have an identity matrix.
See U{http://en.wikipedia.org/wiki/Identity_matrix}
@return: an instance of itself
"""
def transpose():
"""
Set the matrix to its transpose.
See U{http://en.wikipedia.org/wiki/Transpose}
@return: None
"""
def determinant():
"""
Return the determinant of a matrix.
See U{http://en.wikipedia.org/wiki/Determinant}
@rtype: float
@return: Return a the determinant of a matrix.
"""
def invert():
"""
Set the matrix to its inverse.
See U{http://en.wikipedia.org/wiki/Inverse_matrix}
@return: an instance of itself.
@raise ValueError: When matrix is singular.
"""
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 scalePart():
"""
Return a the scale part of a 3x3 or 4x4 matrix.
@note: This method does not return negative a scale on any axis because it is not possible to obtain this data from the matrix alone.
@rtype: Vector object.
@return: Return a the scale of a matrix.
"""
def resize4x4():
"""
Resize the matrix to by 4x4
@return: an instance of itself.
"""
def toEuler(eul_compat):
"""
Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).
@type eul_compat: L{Euler}
@param eul_compat: Optional euler argument the new euler will be made compatible with (no axis flipping between them). Useful for converting a series of matrices to animation curves.
@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
"""