# 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 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.
    """

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

    """