copy of docs from 2.4x for python modules that have been kept

1 files changed, 941 insertions, 0 deletions

diff --git a/source/blender/python/doc/epy/Mathutils.py b/source/blender/python/doc/epy/Mathutils.py
new file mode 100644
index 00000000000..92836237fa6
--- /dev/null
+++ b/source/blender/python/doc/epy/Mathutils.py
@@ -0,0 +1,941 @@
+# Blender.Mathutils module and its subtypes
+
+"""
+The Blender.Mathutils submodule.
+
+Mathutils
+=========
+(when accessing it from the Game Engine use Mathutils instead of Blender.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  
+  
+@group Deprecated: CopyMat, CopyVec, CopyQuat, CopyEuler, RotateEuler, MatMultVec, VecMultMat, CrossVecs, DotVecs, CrossQuats, DotQuats
+"""
+
+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 CopyVec(vector):
+  """
+  Create a copy of the Vector object.
+  @attention: B{DEPRECATED} use vector.copy() instead.
+  @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.
+  @attention: B{DEPRECATED} use vector.cross(other) instead.
+  @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.
+  @attention: B{DEPRECATED} use vector.dot(other) instead.
+  @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. 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 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.
+  @attention: B{DEPRECATED} You should now multiply vector * matrix direcly
+  Example::
+      result = myVector * myMatrix
+  """
+
+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.
+  @attention: B{DEPRECATED} Use the matrix copy funtion to make a copy.
+  Example::
+      newMat = myMat.copy()
+  """
+
+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.
+  @attention: B{DEPRECATED} You should use direct muliplication on the arguments
+  Example::
+      result = myMatrix * myVector
+  """
+
+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.
+  @attention: B{DEPRECATED} You should use the Quaterion() constructor directly
+  to create copies of quaternions
+  Example::
+      newQuat = Quaternion(myQuat)
+  """
+
+def CrossQuats(quat1, quat2):
+  """
+  Return the cross product of two quaternions.
+  @attention: B{DEPRECATED} use quat.cross(other) instead.
+  @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.
+  @attention: B{DEPRECATED} use quat.dot(other) instead.
+  @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.
+  @attention: B{DEPRECATED} You should use the Euler constructor directly
+  to make copies of Euler objects
+  Example::
+      newEuler = Euler(myEuler)
+  """
+
+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.
+  @group Axises: x, y, z, w
+  @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.
+  @ivar magnitude: This is a synonym for length.
+  @ivar wrapped: Whether or not this item is wrapped data
+  @note: Comparison operators can be done on Vector classes:
+      - >, >=, <, <= test the vector magnitude
+      - ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length
+  @note: Math can be performed on Vector classes
+      - vec + vec
+      - vec - vec
+      - vec * float/int
+      - vec * matrix
+      - vec * vec
+      - vec * quat
+      - -vec
+  @note: You can access a vector object like a sequence
+      - x = vector[0]
+      - vec_a[:] vec_b
+      - vec2d[:] vec3d[:2]
+  @note: Vectors support 'swizzle' operations
+      - vec.xyz = vec.zyx
+      - vec.xy = vec.zw
+      - vec.xxy = vec.wzz
+      - vec.yzyz = vec.yxyx
+
+      See U{http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)}
+  
+  @attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list = None):
+    """
+    Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers.
+    @note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error.
+    
+
+    Example::
+      v = Vector(1,0,0)
+      v = Vector(myVec)
+      v = Vector(list)
+    @type list: PyList of float or int
+    @param list: The list of values for the Vector object. Can be a sequence or raw numbers.
+    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 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
+  ================
+    This object gives access to Eulers in Blender.
+  @group Axises: x, y, z
+  @ivar x: The heading value in degrees.
+  @ivar y: The pitch value in degrees.
+  @ivar z: The roll value in degrees.
+  @ivar wrapped: Whether or not this object is wrapping data directly
+  @note: You can access a euler object like a sequence
+      - x = euler[0]
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list = None):
+    """
+    Create a new euler object.
+
+    Example::
+      euler = Euler(45,0,0)
+      euler = Euler(myEuler)
+      euler = Euler(sequence)
+    @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.
+    @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
+  =====================
+    This object gives access to Quaternions in Blender.
+  @group Axises: x, y, z, w
+  @ivar w: The w value.
+  @ivar x: The x value.
+  @ivar y: The y value.
+  @ivar z: The z value.
+  @ivar wrapped: Wether or not this object wraps data directly
+  @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.
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @note: Math can be performed on Quaternion classes
+      - quat + quat
+      - quat - quat 
+      - quat * float/int
+      - quat * vec
+      - quat * quat
+  @note: You can access a quaternion object like a sequence
+      - x = quat[0]
+  @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list, angle = None):
+    """  
+    Create a new quaternion object from initialized values.
+
+    Example::
+      quat = Quaternion(1,2,3,4)
+      quat = Quaternion(axis, angle)
+    quat = Quaternion()
+    quat = Quaternion(180, list)
+
+    @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.
+    @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
+  =================
+    This object gives access to Matrices in Blender.
+  @ivar rowSize: The row size of the matrix.
+  @ivar colSize: The column size of the matrix.
+  @ivar wrapped: Whether or not this object wrapps internal data
+  @note: Math can be performed on Matrix classes
+      - mat + mat 
+      - mat - mat 
+      - mat * float/int
+      - mat * vec
+      - mat * mat 
+  @note: Comparison operators can be done:
+      - ==, != test numeric values within epsilon
+  @note: You can access a quaternion object like a 2d sequence
+      - x = matrix[0][1]
+      - vector = matrix[2]
+  @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
+  means that the object will give you direct access to the data inside of blender. Modification
+  of this object will directly change the data inside of blender. To copy a wrapped object
+  you need to use the object's constructor. If you copy and object by assignment you will not get
+  a second copy but a second reference to the same data. Only certain functions will return 
+  wrapped data. This will be indicated in the method description.
+  Example::
+      wrappedObject = Object.getAttribute() #this is wrapped data
+      print wrappedObject.wrapped #prints 'True'
+      copyOfObject = wrappedObject.copy() #creates a copy of the object
+      secondPointer = wrappedObject #creates a second pointer to the same data
+      print wrappedObject.attribute #prints '5'
+      secondPointer.attribute = 10
+      print wrappedObject.attribute #prints '10'
+      print copyOfObject.attribute #prints '5'
+  """
+
+  def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
+    """  
+    Create a new matrix object from initialized values.
+
+    Example::
+      matrix = Matrix([1,1,1],[0,1,0],[1,0,0])
+      matrix = Matrix(mat)
+      matrix = Matrix(seq1, seq2, vector)
+
+    @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.
+    @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
+    """
+