fix from 2.5x r26079
[blender.git] / source / blender / python / api2_2x / doc / Mathutils.py
1 # Blender.Mathutils module and its subtypes
2
3 """
4 The Blender.Mathutils submodule.
5
6 Mathutils
7 =========
8 (when accessing it from the Game Engine use Mathutils instead of Blender.Mathutils)
9
10 This module provides access to matrices, eulers, quaternions and vectors.
11
12 Example::
13   import Blender
14   from Blender import Mathutils
15   from Blender.Mathutils import *
16
17   vec = Vector([1,2,3])
18   mat = RotationMatrix(90, 4, 'x')
19   matT = TranslationMatrix(vec)
20
21   matTotal = mat * matT
22   matTotal.invert()
23
24   mat3 = matTotal.rotationPart
25   quat1 = mat.toQuat()
26   quat2 = mat3.toQuat()
27
28   angle = DifferenceQuats(quat1, quat2)
29   print angle  
30   
31 @group Deprecated: CopyMat, CopyVec, CopyQuat, CopyEuler, RotateEuler, MatMultVec, VecMultMat, CrossVecs, DotVecs, CrossQuats, DotQuats
32 """
33
34 def Rand (low=0.0, high = 1.0):
35   """
36   Return a random number within a range.
37   low and high represent are optional parameters which represent the range
38   from which the random number must return its result.
39   @type low: float
40   @param low: The lower range.
41   @type high: float
42   @param high: The upper range.
43   """
44
45 def Intersect(vec1, vec2, vec3, ray, orig, clip=1):
46   """
47   Return the intersection between a ray and a triangle, if possible, return None otherwise.
48   @type vec1: Vector object.
49   @param vec1: A 3d vector, one corner of the triangle.
50   @type vec2: Vector object.
51   @param vec2: A 3d vector, one corner of the triangle.
52   @type vec3: Vector object.
53   @param vec3: A 3d vector, one corner of the triangle.
54   @type ray: Vector object.
55   @param ray: A 3d vector, the orientation of the ray. the length of the ray is not used, only the direction.
56   @type orig: Vector object.
57   @param orig: A 3d vector, the origin of the ray.
58   @type clip: integer
59   @param clip: if 0, don't restrict the intersection to the area of the triangle, use the infinite plane defined by the triangle.
60   @rtype: Vector object
61   @return: The intersection between a ray and a triangle, if possible, None otherwise.
62   """
63
64 def TriangleArea(vec1, vec2, vec3):
65   """
66   Return the area size of the 2D or 3D triangle defined.
67   @type vec1: Vector object.
68   @param vec1: A 2d or 3d vector, one corner of the triangle.
69   @type vec2: Vector object.
70   @param vec2: A 2d or 3d vector, one corner of the triangle.
71   @type vec3: Vector object.
72   @param vec3: A 2d or 3d vector, one corner of the triangle.
73   @rtype: float
74   @return: The area size of the 2D or 3D triangle defined.
75   """
76
77 def TriangleNormal(vec1, vec2, vec3):
78   """
79   Return the normal of the 3D triangle defined.
80   @type vec1: Vector object.
81   @param vec1: A 3d vector, one corner of the triangle.
82   @type vec2: Vector object.
83   @param vec2: A 3d vector, one corner of the triangle.
84   @type vec3: Vector object.
85   @param vec3: A 3d vector, one corner of the triangle.
86   @rtype: float
87   @return: The normal of the 3D triangle defined.
88   """
89
90 def QuadNormal(vec1, vec2, vec3, vec4):
91   """
92   Return the normal of the 3D quad defined.
93   @type vec1: Vector object.
94   @param vec1: A 3d vector, the first vertex of the quad.
95   @type vec2: Vector object.
96   @param vec2: A 3d vector, the second vertex of the quad.
97   @type vec3: Vector object.
98   @param vec3: A 3d vector, the third vertex of the quad.
99   @type vec4: Vector object.
100   @param vec4: A 3d vector, the fourth vertex of the quad.
101   @rtype: float
102   @return: The normal of the 3D quad defined.
103   """
104
105 def LineIntersect(vec1, vec2, vec3, vec4):
106   """
107   Return a tuple with the points on each line respectively closest to the other
108   (when both lines intersect, both vector hold the same value).
109   The lines are evaluated as infinite lines in space, the values returned may not be between the 2 points given for each line.
110   @type vec1: Vector object.
111   @param vec1: A 3d vector, one point on the first line.
112   @type vec2: Vector object.
113   @param vec2: A 3d vector, another point on the first line.
114   @type vec3: Vector object.
115   @param vec3: A 3d vector, one point on the second line.
116   @type vec4: Vector object.
117   @param vec4: A 3d vector, another point on the second line.
118   @rtype: (Vector object, Vector object)
119   @return: A tuple with the points on each line respectively closest to the other.
120   """
121
122 def CopyVec(vector):
123   """
124   Create a copy of the Vector object.
125   @attention: B{DEPRECATED} use vector.copy() instead.
126   @type vector: Vector object.
127   @param vector: A 2d,3d or 4d vector to be copied.
128   @rtype: Vector object.
129   @return: A new vector object which is a copy of the one passed in.
130   """
131
132 def CrossVecs(vec1, vec2):
133   """
134   Return the cross product of two vectors.
135   @attention: B{DEPRECATED} use vector.cross(other) instead.
136   @type vec1: Vector object.
137   @param vec1: A 3d vector.
138   @type vec2: Vector object.
139   @param vec2: A 3d vector.
140   @rtype: Vector object.
141   @return: A new vector representing the cross product of
142   the two vectors.
143   """
144
145 def DotVecs(vec1, vec2):
146   """
147   Return the dot product of two vectors.
148   @attention: B{DEPRECATED} use vector.dot(other) instead.
149   @type vec1: Vector object.
150   @param vec1: A 2d,3d or 4d vector.
151   @type vec2: Vector object.
152   @param vec2: A 2d,3d or 4d vector.
153   @rtype: float
154   @return: Return the scalar product of vector muliplication.
155   """
156
157 def AngleBetweenVecs(vec1, vec2):
158   """
159   Return the angle between two vectors. Zero length vectors raise an error.
160   @type vec1: Vector object.
161   @param vec1: A 2d or 3d vector.
162   @type vec2: Vector object.
163   @param vec2: A 2d or 3d vector.
164   @rtype: float
165   @return: The angle between the vectors in degrees.
166   @raise AttributeError: When there is a zero-length vector as an argument.
167   """
168
169 def MidpointVecs(vec1, vec2):
170   """
171   Return a vector to the midpoint between two vectors.
172   @type vec1: Vector object.
173   @param vec1: A 2d,3d or 4d vector.
174   @type vec2: Vector object.
175   @param vec2: A 2d,3d or 4d vector.
176   @rtype: Vector object
177   @return: The vector to the midpoint.
178   """
179
180 def VecMultMat(vec, mat):
181   """
182   Multiply a vector and matrix (pre-multiply)
183   Vector size and matrix column size must equal.
184   @type vec: Vector object.
185   @param vec: A 2d,3d or 4d vector.
186   @type mat: Matrix object.
187   @param mat: A 2d,3d or 4d matrix.
188   @rtype: Vector object
189   @return: The row vector that results from the muliplication.
190   @attention: B{DEPRECATED} You should now multiply vector * matrix direcly
191   Example::
192       result = myVector * myMatrix
193   """
194
195 def ProjectVecs(vec1, vec2):
196   """  
197   Return the projection of vec1 onto vec2.
198   @type vec1: Vector object.
199   @param vec1: A 2d,3d or 4d vector.
200   @type vec2: Vector object.
201   @param vec2: A 2d,3d or 4d vector.
202   @rtype: Vector object
203   @return: The parallel projection vector.
204   """
205
206 def RotationMatrix(angle, matSize, axisFlag, axis):
207   """  
208   Create a matrix representing a rotation.
209   @type angle: float
210   @param angle: The angle of rotation desired.
211   @type matSize: int
212   @param matSize: The size of the rotation matrix to construct.
213   Can be 2d, 3d, or 4d.
214   @type axisFlag: string (optional)
215   @param axisFlag: Possible values:
216        - "x - x-axis rotation"
217        - "y - y-axis rotation"
218        - "z - z-axis rotation"
219        - "r - arbitrary rotation around vector"
220   @type axis: Vector object. (optional)
221   @param axis: The arbitrary axis of rotation used with "R"
222   @rtype: Matrix object.
223   @return: A new rotation matrix.
224   """
225
226 def TranslationMatrix(vector):
227   """  
228   Create a matrix representing a translation
229   @type vector: Vector object
230   @param vector: The translation vector
231   @rtype: Matrix object.
232   @return: An identity matrix with a translation.
233   """
234
235 def ScaleMatrix(factor, matSize, axis):
236   """  
237   Create a matrix representing a scaling.
238   @type factor: float
239   @param factor: The factor of scaling to apply.
240   @type matSize: int
241   @param matSize: The size of the scale matrix to construct.
242   Can be 2d, 3d, or 4d.
243   @type axis: Vector object.  (optional)
244   @param axis: Direction to influence scale.
245   @rtype: Matrix object.
246   @return: A new scale matrix.
247   """
248
249 def OrthoProjectionMatrix(plane, matSize, axis):
250   """  
251   Create a matrix to represent an orthographic projection
252   @type plane: string
253   @param plane: Can be any of the following:
254        - "x - x projection (2D)"
255        - "y - y projection (2D)"
256        - "xy - xy projection"
257        - "xz - xz projection"
258        - "yz - yz projection"
259        - "r - arbitrary projection plane"
260   @type matSize: int
261   @param matSize: The size of the projection matrix to construct.
262   Can be 2d, 3d, or 4d.
263   @type axis: Vector object. (optional)
264   @param axis: Arbitrary perpendicular plane vector.
265   @rtype: Matrix object.
266   @return: A new projeciton matrix.
267   """
268
269 def ShearMatrix(plane, factor, matSize):
270   """  
271   Create a matrix to represent an orthographic projection
272   @type plane: string
273   @param plane: Can be any of the following:
274        - "x - x shear (2D)"
275        - "y - y shear (2D)"
276        - "xy - xy shear"
277        - "xz - xz shear"
278        - "yz - yz shear"
279   @type factor: float
280   @param factor: The factor of shear to apply.
281   @type matSize: int
282   @param matSize: The size of the projection matrix to construct.
283   Can be 2d, 3d, or 4d.
284   @rtype: Matrix object.
285   @return: A new shear matrix.
286   """
287
288 def CopyMat(matrix):
289   """
290   Create a copy of the Matrix object.
291   @type matrix: Matrix object.
292   @param matrix: A 2d,3d or 4d matrix to be copied.
293   @rtype: Matrix object.
294   @return: A new matrix object which is a copy of the one passed in.
295   @attention: B{DEPRECATED} Use the matrix copy funtion to make a copy.
296   Example::
297       newMat = myMat.copy()
298   """
299
300 def MatMultVec(mat, vec):
301   """
302   Multiply a matrix and a vector (post-multiply)
303   Vector size and matrix row size must equal.
304   @type vec: Vector object.
305   @param vec: A 2d,3d or 4d vector.
306   @type mat: Matrix object.
307   @param mat: A 2d,3d or 4d matrix.
308   @rtype: Vector object
309   @return: The column vector that results from the muliplication.
310   @attention: B{DEPRECATED} You should use direct muliplication on the arguments
311   Example::
312       result = myMatrix * myVector
313   """
314
315 def CopyQuat(quaternion):
316   """
317   Create a copy of the Quaternion object.
318   @type quaternion: Quaternion object.
319   @param quaternion: Quaternion to be copied.
320   @rtype: Quaternion object.
321   @return: A new quaternion object which is a copy of the one passed in.
322   @attention: B{DEPRECATED} You should use the Quaterion() constructor directly
323   to create copies of quaternions
324   Example::
325       newQuat = Quaternion(myQuat)
326   """
327
328 def CrossQuats(quat1, quat2):
329   """
330   Return the cross product of two quaternions.
331   @attention: B{DEPRECATED} use quat.cross(other) instead.
332   @type quat1: Quaternion object.
333   @param quat1: Quaternion.
334   @type quat2: Quaternion object.
335   @param quat2: Quaternion.
336   @rtype: Quaternion object.
337   @return: A new quaternion representing the cross product of
338   the two quaternions.
339   """
340
341 def DotQuats(quat1, quat2):
342   """
343   Return the dot product of two quaternions.
344   @attention: B{DEPRECATED} use quat.dot(other) instead.
345   @type quat1: Quaternion object.
346   @param quat1: Quaternion.
347   @type quat2: Quaternion object.
348   @param quat2: Quaternion.
349   @rtype: float
350   @return: Return the scalar product of quaternion muliplication.
351   """
352
353 def DifferenceQuats(quat1, quat2):
354   """
355   Returns a quaternion represting the rotational difference.
356   @type quat1: Quaternion object.
357   @param quat1: Quaternion.
358   @type quat2: Quaternion object.
359   @param quat2: Quaternion.
360   @rtype: Quaternion object
361   @return: Return a quaternion which which represents the rotational
362   difference between the two quat rotations.
363   """
364
365 def Slerp(quat1, quat2, factor):
366   """
367   Returns the interpolation of two quaternions.
368   @type quat1: Quaternion object.
369   @param quat1: Quaternion.
370   @type quat2: Quaternion object.
371   @param quat2: Quaternion.
372   @type factor: float
373   @param factor: The interpolation value
374   @rtype: Quaternion object
375   @return: The interpolated rotation.
376   """
377
378 def CopyEuler(euler):
379   """
380   Create a new euler object.
381   @type euler: Euler object
382   @param euler: The euler to copy
383   @rtype: Euler object
384   @return: A copy of the euler object passed in.
385   @attention: B{DEPRECATED} You should use the Euler constructor directly
386   to make copies of Euler objects
387   Example::
388       newEuler = Euler(myEuler)
389   """
390
391 def RotateEuler(euler, angle, axis):
392   """
393   Roatate a euler by an amount in degrees around an axis.
394   @type euler: Euler object
395   @param euler: Euler to rotate.
396   @type angle: float
397   @param angle: The amount of rotation in degrees
398   @type axis: string
399   @param axis: axis to rotate around:
400        - "x"
401        - "y"
402        - "z"
403   """
404
405 class Vector:
406   """
407   The Vector object
408   =================
409     This object gives access to Vectors in Blender.
410   @group Axises: x, y, z, w
411   @ivar x: The x value.
412   @ivar y: The y value.
413   @ivar z: The z value (if any).
414   @ivar w: The w value (if any).
415   @ivar length: The magnitude of the vector.
416   @ivar magnitude: This is a synonym for length.
417   @ivar wrapped: Whether or not this item is wrapped data
418   @note: Comparison operators can be done on Vector classes:
419       - >, >=, <, <= test the vector magnitude
420       - ==, != test vector values e.g. 1,2,3 != 1,2,4 even if they are the same length
421   @note: Math can be performed on Vector classes
422       - vec + vec
423       - vec - vec
424       - vec * float/int
425       - vec * matrix
426       - vec * vec
427       - vec * quat
428       - -vec
429   @note: You can access a vector object like a sequence
430       - x = vector[0]
431       - vec_a[:] vec_b
432       - vec2d[:] vec3d[:2]
433   @note: Vectors support 'swizzle' operations
434       - vec.xyz = vec.zyx
435       - vec.xy = vec.zw
436       - vec.xxy = vec.wzz
437       - vec.yzyz = vec.yxyx
438
439       See U{http://en.wikipedia.org/wiki/Swizzling_(computer_graphics)}
440   
441   @attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it
442   means that the object will give you direct access to the data inside of blender. Modification
443   of this object will directly change the data inside of blender. To copy a wrapped object
444   you need to use the object's constructor. If you copy and object by assignment you will not get
445   a second copy but a second reference to the same data. Only certain functions will return 
446   wrapped data. This will be indicated in the method description.
447   Example::
448       wrappedObject = Object.getAttribute() #this is wrapped data
449       print wrappedObject.wrapped #prints 'True'
450       copyOfObject = wrappedObject.copy() #creates a copy of the object
451       secondPointer = wrappedObject #creates a second pointer to the same data
452       print wrappedObject.attribute #prints '5'
453       secondPointer.attribute = 10
454       print wrappedObject.attribute #prints '10'
455       print copyOfObject.attribute #prints '5'
456   """
457
458   def __init__(list = None):
459     """
460     Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers.
461     @note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error.
462     
463
464     Example::
465       v = Vector(1,0,0)
466       v = Vector(myVec)
467       v = Vector(list)
468     @type list: PyList of float or int
469     @param list: The list of values for the Vector object. Can be a sequence or raw numbers.
470     Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w].
471     @rtype: Vector object.
472     @return: It depends wheter a parameter was passed:
473         - (list): Vector object initialized with the given values;
474         - ():     An empty 3 dimensional vector.
475     """
476
477   def copy():
478     """
479     Returns a copy of this vector
480     @return: a copy of itself
481     """
482
483   def zero():
484     """
485     Set all values to zero.
486     @return: an instance of itself
487     """
488
489   def normalize():
490     """
491     Normalize the vector, making the length of the vector always 1.0
492     @note: Normalize works for vectors of all sizes, however 4D Vectors w axis is left untouched.
493     @note: Normalizing a vector where all values are zero results in all axis having a nan value (not a number).
494     @return: an instance of itself
495     """
496
497   def negate():
498     """
499     Set all values to their negative.
500     @return: an instance of its self
501     """
502
503   def resize2D():
504     """
505     Resize the vector to 2d.
506     @return: an instance of itself
507     """
508
509   def resize3D():
510     """
511     Resize the vector to 3d. New axis will be 0.0.
512     @return: an instance of itself
513     """
514
515   def resize4D():
516     """
517     Resize the vector to 4d. New axis will be 0.0.
518     The last component will be 1.0, to make multiplying 3d vectors by 4x4 matrices easier.
519     @return: an instance of itself
520     """
521
522   def toTrackQuat(track, up):
523     """
524     Return a quaternion rotation from the vector and the track and up axis.
525     @type track: String.
526     @param track: Possible values:
527                    - "x - x-axis up"
528                    - "y - y-axis up"
529                    - "z - z-axis up"
530                    - "-x - negative x-axis up"
531                    - "-y - negative y-axis up"
532                    - "-z - negative z-axis up"
533     @type up: String.
534     @param up: Possible values:
535                    - "x - x-axis up"
536                    - "y - y-axis up"
537                    - "z - z-axis up"
538     @rtype: Quaternion
539     @return: Return a quaternion rotation from the vector and the track and up axis.
540     """
541
542   def reflect(mirror):
543     """
544     Return the reflection vector from the mirror vector argument.
545     @type mirror: Vector object
546     @param mirror: This vector could be a normal from the reflecting surface.
547     @rtype: Vector object matching the size of this vector.
548     @return: The reflected vector.
549     """
550
551   def cross(other):
552     """
553     Return the cross product of this vector and another.
554     @note: both vectors must be 3D.
555     @type other: Vector object
556     @param other: The other vector to perform the cross product with.
557     @rtype: Vector
558     @return: The cross product.
559     """
560
561   def dot(other):
562     """
563     Return the dot product of this vector and another.
564     @note: both vectors must be the same size.
565     @type other: Vector object
566     @param other: The other vector to perform the dot product with.
567     @rtype: float
568     @return: The dot product.
569     """
570
571 class Euler:
572   """
573   The Euler object
574   ================
575     This object gives access to Eulers in Blender.
576   @group Axises: x, y, z
577   @ivar x: The heading value in degrees.
578   @ivar y: The pitch value in degrees.
579   @ivar z: The roll value in degrees.
580   @ivar wrapped: Whether or not this object is wrapping data directly
581   @note: You can access a euler object like a sequence
582       - x = euler[0]
583   @note: Comparison operators can be done:
584       - ==, != test numeric values within epsilon
585   @attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it
586   means that the object will give you direct access to the data inside of blender. Modification
587   of this object will directly change the data inside of blender. To copy a wrapped object
588   you need to use the object's constructor. If you copy and object by assignment you will not get
589   a second copy but a second reference to the same data. Only certain functions will return 
590   wrapped data. This will be indicated in the method description.
591   Example::
592       wrappedObject = Object.getAttribute() #this is wrapped data
593       print wrappedObject.wrapped #prints 'True'
594       copyOfObject = wrappedObject.copy() #creates a copy of the object
595       secondPointer = wrappedObject #creates a second pointer to the same data
596       print wrappedObject.attribute #prints '5'
597       secondPointer.attribute = 10
598       print wrappedObject.attribute #prints '10'
599       print copyOfObject.attribute #prints '5'
600   """
601
602   def __init__(list = None):
603     """
604     Create a new euler object.
605
606     Example::
607       euler = Euler(45,0,0)
608       euler = Euler(myEuler)
609       euler = Euler(sequence)
610     @type list: PyList of float/int
611     @param list: 3d list to initialize euler
612     @rtype: Euler object
613     @return: Euler representing heading, pitch, bank.
614     @note: Values are in degrees.
615     """
616
617   def zero():
618     """
619     Set all values to zero.
620     @return: an instance of itself
621     """
622
623   def copy():
624     """
625     @return: a copy of this euler.
626     """
627
628   def unique():
629     """
630     Calculate a unique rotation for this euler. Avoids gimble lock.
631     @return: an instance of itself
632     """
633
634   def toMatrix():
635     """
636     Return a matrix representation of the euler.
637     @rtype: Matrix object
638     @return: A 3x3 roation matrix representation of the euler.
639     """
640
641   def toQuat():
642     """
643     Return a quaternion representation of the euler.
644     @rtype: Quaternion object
645     @return: Quaternion representation of the euler.
646     """
647   def makeCompatible(eul_compat):
648     """
649     Make this euler compatible with another, so interpolating between them works as expected.
650     @rtype: Euler object
651     @return: an instance of itself
652     """
653
654 class Quaternion:
655   """
656   The Quaternion object
657   =====================
658     This object gives access to Quaternions in Blender.
659   @group Axises: x, y, z, w
660   @ivar w: The w value.
661   @ivar x: The x value.
662   @ivar y: The y value.
663   @ivar z: The z value.
664   @ivar wrapped: Wether or not this object wraps data directly
665   @ivar magnitude: The magnitude of the quaternion.
666   @ivar axis: Vector representing the axis of rotation.
667   @ivar angle: A scalar representing the amount of rotation
668   in degrees.
669   @note: Comparison operators can be done:
670       - ==, != test numeric values within epsilon
671   @note: Math can be performed on Quaternion classes
672       - quat + quat
673       - quat - quat 
674       - quat * float/int
675       - quat * vec
676       - quat * quat
677   @note: You can access a quaternion object like a sequence
678       - x = quat[0]
679   @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
680   means that the object will give you direct access to the data inside of blender. Modification
681   of this object will directly change the data inside of blender. To copy a wrapped object
682   you need to use the object's constructor. If you copy and object by assignment you will not get
683   a second copy but a second reference to the same data. Only certain functions will return 
684   wrapped data. This will be indicated in the method description.
685   Example::
686       wrappedObject = Object.getAttribute() #this is wrapped data
687       print wrappedObject.wrapped #prints 'True'
688       copyOfObject = wrappedObject.copy() #creates a copy of the object
689       secondPointer = wrappedObject #creates a second pointer to the same data
690       print wrappedObject.attribute #prints '5'
691       secondPointer.attribute = 10
692       print wrappedObject.attribute #prints '10'
693       print copyOfObject.attribute #prints '5'
694   """
695
696   def __init__(list, angle = None):
697     """  
698     Create a new quaternion object from initialized values.
699
700     Example::
701       quat = Quaternion(1,2,3,4)
702       quat = Quaternion(axis, angle)
703     quat = Quaternion()
704     quat = Quaternion(180, list)
705
706     @type list: PyList of int/float
707     @param list: A 3d or 4d list to initialize quaternion.
708         4d if intializing [w,x,y,z], 3d if used as an axis of rotation.
709     @type angle: float (optional)
710     @param angle: An arbitrary rotation amount around 'list'.
711         List is used as an axis of rotation in this case.
712     @rtype: New quaternion object.
713     @return: It depends wheter a parameter was passed:
714         - (list/angle): Quaternion object initialized with the given values;
715         - ():     An identity 4 dimensional quaternion.
716     """
717
718   def identity():
719     """
720     Set the quaternion to the identity quaternion.
721     @return: an instance of itself
722     """
723
724   def copy():
725     """
726     make a copy of the quaternion.
727     @return: a copy of itself
728     """
729
730   def negate():
731     """
732     Set the quaternion to its negative.
733     @return: an instance of itself
734     """
735
736   def conjugate():
737     """
738     Set the quaternion to its conjugate.
739     @return: an instance of itself
740     """
741
742   def inverse():
743     """
744     Set the quaternion to its inverse
745     @return: an instance of itself
746     """
747
748   def normalize():
749     """
750     Normalize the quaternion.
751     @return: an instance of itself
752     """
753
754   def toEuler(eul_compat):
755     """
756     Return Euler representation of the quaternion.
757     @type eul_compat: L{Euler}
758     @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.
759     @rtype: Euler object
760     @return: Euler representation of the quaternion.
761     """
762   
763   def toMatrix():
764     """
765     Return a matrix representation of the quaternion.
766     @rtype: Matrix object
767     @return: A 3x3 rotation matrix representation of the quaternion.
768     """
769
770   def cross(other):
771     """
772     Return the cross product of this quaternion and another.
773     @type other: Quaterion object
774     @param other: The other quaternion to perform the cross product with.
775     @rtype: Vector
776     @return: The cross product.
777     """
778
779   def dot(other):
780     """
781     Return the dot product of this quaternion and another.
782     @type other: Quaterion object
783     @param other: The other quaternion to perform the dot product with.
784     @rtype: float
785     @return: The dot product.
786     """
787
788 class Matrix:
789   """
790   The Matrix Object
791   =================
792     This object gives access to Matrices in Blender.
793   @ivar rowSize: The row size of the matrix.
794   @ivar colSize: The column size of the matrix.
795   @ivar wrapped: Whether or not this object wrapps internal data
796   @note: Math can be performed on Matrix classes
797       - mat + mat 
798       - mat - mat 
799       - mat * float/int
800       - mat * vec
801       - mat * mat 
802   @note: Comparison operators can be done:
803       - ==, != test numeric values within epsilon
804   @note: You can access a quaternion object like a 2d sequence
805       - x = matrix[0][1]
806       - vector = matrix[2]
807   @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
808   means that the object will give you direct access to the data inside of blender. Modification
809   of this object will directly change the data inside of blender. To copy a wrapped object
810   you need to use the object's constructor. If you copy and object by assignment you will not get
811   a second copy but a second reference to the same data. Only certain functions will return 
812   wrapped data. This will be indicated in the method description.
813   Example::
814       wrappedObject = Object.getAttribute() #this is wrapped data
815       print wrappedObject.wrapped #prints 'True'
816       copyOfObject = wrappedObject.copy() #creates a copy of the object
817       secondPointer = wrappedObject #creates a second pointer to the same data
818       print wrappedObject.attribute #prints '5'
819       secondPointer.attribute = 10
820       print wrappedObject.attribute #prints '10'
821       print copyOfObject.attribute #prints '5'
822   """
823
824   def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
825     """  
826     Create a new matrix object from initialized values.
827
828     Example::
829       matrix = Matrix([1,1,1],[0,1,0],[1,0,0])
830       matrix = Matrix(mat)
831       matrix = Matrix(seq1, seq2, vector)
832
833     @type list1: PyList of int/float
834     @param list1: A 2d,3d or 4d list.
835     @type list2: PyList of int/float
836     @param list2: A 2d,3d or 4d list.
837     @type list3: PyList of int/float
838     @param list3: A 2d,3d or 4d list.
839     @type list4: PyList of int/float
840     @param list4: A 2d,3d or 4d list.
841     @rtype: New matrix object.
842     @return: It depends wheter a parameter was passed:
843         - (list1, etc.): Matrix object initialized with the given values;
844         - ():     An empty 3 dimensional matrix.
845     """
846
847   def zero():
848     """
849     Set all matrix values to 0.
850     @return: an instance of itself
851     """
852
853
854   def copy():
855     """
856     Returns a copy of this matrix
857     @return: a copy of itself
858     """
859
860   def identity():
861     """
862     Set the matrix to the identity matrix.
863     An object with zero location and rotation, a scale of 1, will have an identity matrix.
864
865     See U{http://en.wikipedia.org/wiki/Identity_matrix}
866     @return: an instance of itself
867     """
868
869   def transpose():
870     """
871     Set the matrix to its transpose.
872     
873     See U{http://en.wikipedia.org/wiki/Transpose}
874     @return: None
875     """
876
877   def determinant():
878     """
879     Return the determinant of a matrix.
880     
881     See U{http://en.wikipedia.org/wiki/Determinant}
882     @rtype: float
883     @return: Return a the determinant of a matrix.
884     """
885
886   def invert():
887     """
888     Set the matrix to its inverse.
889     
890     See U{http://en.wikipedia.org/wiki/Inverse_matrix}
891     @return: an instance of itself.
892     @raise ValueError: When matrix is singular.
893     """
894
895   def rotationPart():
896     """
897     Return the 3d submatrix corresponding to the linear term of the 
898     embedded affine transformation in 3d. This matrix represents rotation
899     and scale. Note that the (4,4) element of a matrix can be used for uniform
900     scaling, too.
901     @rtype: Matrix object.
902     @return: Return the 3d matrix for rotation and scale.
903     """
904
905   def translationPart():
906     """
907     Return a the translation part of a 4 row matrix.
908     @rtype: Vector object.
909     @return: Return a the translation of a matrix.
910     """
911
912   def scalePart():
913     """
914     Return a the scale part of a 3x3 or 4x4 matrix.
915     @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.
916     @rtype: Vector object.
917     @return: Return a the scale of a matrix.
918     """
919
920   def resize4x4():
921     """
922     Resize the matrix to by 4x4
923     @return: an instance of itself.
924     """
925   
926   def toEuler(eul_compat):
927     """
928     Return an Euler representation of the rotation matrix (3x3 or 4x4 matrix only).
929     @type eul_compat: L{Euler}
930     @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.
931     @rtype: Euler object
932     @return: Euler representation of the rotation matrix.
933     """
934
935   def toQuat():
936     """
937     Return a quaternion representation of the rotation matrix
938     @rtype: Quaternion object
939     @return: Quaternion representation of the rotation matrix
940     """
941