New scripts:
[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
9 This module provides access to matrices, eulers, quaternions and vectors.
10
11 Example::
12   import Blender
13   from Blender import Mathutils
14   from Blender.Mathutils import *
15
16   vec = Vector([1,2,3])
17   mat = RotationMatrix(90, 4, 'x')
18   matT = TranslationMatrix(vec)
19
20   matTotal = mat * matT
21   matTotal.invert()
22
23   mat3 = matTotal.rotationPart
24   quat1 = mat.toQuat()
25   quat2 = mat3.toQuat()
26
27   angle = DifferenceQuats(quat1, quat2)
28   print angle  
29 """
30
31 def Rand (high = 1, low = 0):
32   """
33   Return a random number within a range.
34   High and low represent the range from which the random
35   number must return its result.
36   @type high: float
37   @param high: The upper range.
38   @type low: float
39   @param low: The lower range.
40   """
41
42 def CopyVec(vector):
43   """
44   Create a copy of the Vector object.
45   @type vector: Vector object.
46   @param vector: A 2d,3d or 4d vector to be copied.
47   @rtype: Vector object.
48   @return: A new vector object which is a copy of the one passed in.
49   """
50
51 def CrossVecs(vec1, vec2):
52   """
53   Return the cross product of two vectors.
54   @type vec1: Vector object.
55   @param vec1: A 3d vector.
56   @type vec2: Vector object.
57   @param vec2: A 3d vector.
58   @rtype: Vector object.
59   @return: A new vector representing the cross product of
60   the two vectors.
61   """
62
63 def DotVecs(vec1, vec2):
64   """
65   Return the dot product of two vectors.
66   @type vec1: Vector object.
67   @param vec1: A 2d,3d or 4d vector.
68   @type vec2: Vector object.
69   @param vec2: A 2d,3d or 4d vector.
70   @rtype: float
71   @return: Return the scalar product of vector muliplication.
72   """
73
74 def AngleBetweenVecs(vec1, vec2):
75   """
76   Return the angle between two vectors.
77   @type vec1: Vector object.
78   @param vec1: A 2d or 3d vector.
79   @type vec2: Vector object.
80   @param vec2: A 2d or 3d vector.
81   @rtype: float
82   @return: The angle between the vectors in degrees.
83   """
84
85 def MidpointVecs(vec1, vec2):
86   """
87   Return a vector to the midpoint between two vectors.
88   @type vec1: Vector object.
89   @param vec1: A 2d,3d or 4d vector.
90   @type vec2: Vector object.
91   @param vec2: A 2d,3d or 4d vector.
92   @rtype: Vector object
93   @return: The vector to the midpoint.
94   """
95
96 def VecMultMat(vec, mat):
97   """
98   Multiply a vector and matrix (pre-multiply)
99   Vector size and matrix column size must equal.
100   @type vec: Vector object.
101   @param vec: A 2d,3d or 4d vector.
102   @type mat: Matrix object.
103   @param mat: A 2d,3d or 4d matrix.
104   @rtype: Vector object
105   @return: The row vector that results from the muliplication.
106   """
107
108 def ProjectVecs(vec1, vec2):
109   """  
110   Return the projection of vec1 onto vec2.
111   @type vec1: Vector object.
112   @param vec1: A 2d,3d or 4d vector.
113   @type vec2: Vector object.
114   @param vec2: A 2d,3d or 4d vector.
115   @rtype: Vector object
116   @return: The parallel projection vector.
117   """
118
119 def RotationMatrix(angle, matSize, axisFlag, axis):
120   """  
121   Create a matrix representing a rotation.
122   @type angle: float
123   @param angle: The angle of rotation desired.
124   @type matSize: int
125   @param matSize: The size of the rotation matrix to construct.
126   Can be 2d, 3d, or 4d.
127   @type axisFlag: string (optional)
128   @param axisFlag: Possible values:
129        - "x - x-axis rotation"
130        - "y - y-axis rotation"
131        - "z - z-axis rotation"
132        - "r - arbitrary rotation around vector"
133   @type axis: Vector object. (optional)
134   @param axis: The arbitrary axis of rotation used with "R"
135   @rtype: Matrix object.
136   @return: A new rotation matrix.
137   """
138
139 def TranslationMatrix(vector):
140   """  
141   Create a matrix representing a translation
142   @type vector: Vector object
143   @param vector: The translation vector
144   @rtype: Matrix object.
145   @return: An identity matrix with a translation.
146   """
147
148 def ScaleMatrix(factor, matSize, axis):
149   """  
150   Create a matrix representing a scaling.
151   @type factor: float
152   @param factor: The factor of scaling to apply.
153   @type matSize: int
154   @param matSize: The size of the scale matrix to construct.
155   Can be 2d, 3d, or 4d.
156   @type axis: Vector object.  (optional)
157   @param axis: Direction to influence scale.
158   @rtype: Matrix object.
159   @return: A new scale matrix.
160   """
161
162 def OrthoProjectionMatrix(plane, matSize, axis):
163   """  
164   Create a matrix to represent an orthographic projection
165   @type plane: string
166   @param plane: Can be any of the following:
167        - "x - x projection (2D)"
168        - "y - y projection (2D)"
169        - "xy - xy projection"
170        - "xz - xz projection"
171        - "yz - yz projection"
172        - "r - arbitrary projection plane"
173   @type matSize: int
174   @param matSize: The size of the projection matrix to construct.
175   Can be 2d, 3d, or 4d.
176   @type axis: Vector object. (optional)
177   @param axis: Arbitrary perpendicular plane vector.
178   @rtype: Matrix object.
179   @return: A new projeciton matrix.
180   """
181
182 def ShearMatrix(plane, factor, matSize):
183   """  
184   Create a matrix to represent an orthographic projection
185   @type plane: string
186   @param plane: Can be any of the following:
187        - "x - x shear (2D)"
188        - "y - y shear (2D)"
189        - "xy - xy shear"
190        - "xz - xz shear"
191        - "yz - yz shear"
192   @type factor: float
193   @param factor: The factor of shear to apply.
194   @type matSize: int
195   @param matSize: The size of the projection matrix to construct.
196   Can be 2d, 3d, or 4d.
197   @rtype: Matrix object.
198   @return: A new shear matrix.
199   """
200
201 def CopyMat(matrix):
202   """
203   Create a copy of the Matrix object.
204   @type matrix: Matrix object.
205   @param matrix: A 2d,3d or 4d matrix to be copied.
206   @rtype: Matrix object.
207   @return: A new matrix object which is a copy of the one passed in.
208   """
209
210 def MatMultVec(mat, vec):
211   """
212   Multiply a matrix and a vector (post-multiply)
213   Vector size and matrix row size must equal.
214   @type vec: Vector object.
215   @param vec: A 2d,3d or 4d vector.
216   @type mat: Matrix object.
217   @param mat: A 2d,3d or 4d matrix.
218   @rtype: Vector object
219   @return: The column vector that results from the muliplication.
220   """
221
222 def CopyQuat(quaternion):
223   """
224   Create a copy of the Quaternion object.
225   @type quaternion: Quaternion object.
226   @param quaternion: Quaternion to be copied.
227   @rtype: Quaternion object.
228   @return: A new quaternion object which is a copy of the one passed in.
229   """
230
231 def CrossQuats(quat1, quat2):
232   """
233   Return the cross product of two quaternions.
234   @type quat1: Quaternion object.
235   @param quat1: Quaternion.
236   @type quat2: Quaternion object.
237   @param quat2: Quaternion.
238   @rtype: Quaternion object.
239   @return: A new quaternion representing the cross product of
240   the two quaternions.
241   """
242
243 def DotQuats(quat1, quat2):
244   """
245   Return the dot product of two quaternions.
246   @type quat1: Quaternion object.
247   @param quat1: Quaternion.
248   @type quat2: Quaternion object.
249   @param quat2: Quaternion.
250   @rtype: float
251   @return: Return the scalar product of quaternion muliplication.
252   """
253
254 def DifferenceQuats(quat1, quat2):
255   """
256   Returns a quaternion represting the rotational difference.
257   @type quat1: Quaternion object.
258   @param quat1: Quaternion.
259   @type quat2: Quaternion object.
260   @param quat2: Quaternion.
261   @rtype: Quaternion object
262   @return: Return a quaternion which which represents the rotational
263   difference between the two quat rotations.
264   """
265
266 def Slerp(quat1, quat2, factor):
267   """
268   Returns the interpolation of two quaternions.
269   @type quat1: Quaternion object.
270   @param quat1: Quaternion.
271   @type quat2: Quaternion object.
272   @param quat2: Quaternion.
273   @type factor: float
274   @param factor: The interpolation value
275   @rtype: Quaternion object
276   @return: The interpolated rotation.
277   """
278
279 def CopyEuler(euler):
280   """
281   Create a new euler object.
282   @type euler: Euler object
283   @param euler: The euler to copy
284   @rtype: Euler object
285   @return: A copy of the euler object passed in.
286   """
287
288 def RotateEuler(euler, angle, axis):
289   """
290   Roatate a euler by an amount in degrees around an axis.
291   @type euler: Euler object
292   @param euler: Euler to rotate.
293   @type angle: float
294   @param angle: The amount of rotation in degrees
295   @type axis: string
296   @param axis: axis to rotate around:
297        - "x"
298        - "y"
299        - "z"
300   """
301
302 class Vector:
303   """
304   The Vector object
305   =================
306     This object gives access to Vectors in Blender.
307   @cvar x: The x value.
308   @cvar y: The y value.
309   @cvar z: The z value (if any).
310   @cvar w: The w value (if any).
311   @cvar length: The magnitude of the vector.
312   """
313
314   def __init__(list = None):
315     """
316     Create a new Vector object from a list.
317
318     Example::
319       v = Blender.Mathutils.Vector([1,0,0])
320     @type list: PyList of float or int
321     @param list: The list of values for the Vector object.
322     Must be 2, 3, or 4 values.
323     @rtype: Vector object.
324     @return: It depends wheter a parameter was passed:
325         - (list): Vector object initialized with the given values;
326         - ():     An empty 3 dimensional vector.
327     """
328
329   def zero():
330     """
331     Set all values to zero.
332     """
333
334   def normalize():
335     """
336     Normalize the vector.
337     """
338
339   def negate():
340     """
341     Set all values to their negative.
342     """
343
344   def resize2D():
345     """
346     Resize the vector to 2d.
347     """
348
349   def resize3D():
350     """
351     Resize the vector to 3d.
352     """
353
354   def resize4D():
355     """
356     Resize the vector to 4d.
357     """
358
359 class Euler:
360   """
361   The Euler object
362   ================
363     This object gives access to Eulers in Blender.
364   @cvar x: The heading value in degrees.
365   @cvar y: The pitch value in degrees.
366   @cvar z: The roll value in degrees.
367   """
368
369   def __init__(list = None):
370     """
371     Create a new euler object.
372
373     Example::
374       euler = Euler([45,0,0])
375     @type list: PyList of float/int
376     @param list: 3d list to initialize euler
377     @rtype: Euler object
378     @return: Euler representing heading, pitch, bank.
379     @note: Values are in degrees.
380     """
381
382   def zero():
383     """
384     Set all values to zero.
385     """
386
387   def unique():
388     """
389     Calculate a unique rotation for this euler.
390     """
391
392   def toMatrix():
393     """
394     Return a matrix representation of the euler.
395     @rtype: Matrix object
396     @return: A roation matrix representation of the euler.
397
398     """
399
400   def toQuat():
401     """
402     Return a quaternion representation of the euler.
403     @rtype: Quaternion object
404     @return: Quaternion representation of the euler.
405
406     """
407
408 class Quaternion:
409   """
410   The Quaternion object
411   =====================
412     This object gives access to Quaternions in Blender.
413   @cvar w: The w value.
414   @cvar x: The x value.
415   @cvar y: The y value.
416   @cvar z: The z value.
417   @cvar magnitude: The magnitude of the quaternion.
418   @cvar axis: Vector representing the axis of rotation.
419   @cvar angle: A scalar representing the amount of rotation
420   in degrees.
421   """
422
423   def __init__(list = None, angle = None):
424     """  
425     Create a new quaternion object from initialized values.
426
427     Example::
428       quat = Mathutils.Quaternion()
429
430     @type list: PyList of int/float
431     @param list: A 3d or 4d list to initialize quaternion.
432         4d if intializing, 3d if will be used as an axis of rotation.
433     @type angle: float (optional)
434     @param angle: An arbitrary rotation amount around 'list'.
435         List is used as an axis of rotation in this case.
436     @rtype: New quaternion object.
437     @return: It depends wheter a parameter was passed:
438         - (list/angle): Quaternion object initialized with the given values;
439         - ():     An identity 4 dimensional quaternion.
440     """
441
442   def identity():
443     """
444     Set the quaternion to the identity quaternion.
445     """
446
447   def negate():
448     """
449     Set the quaternion to it's negative.
450     """
451
452   def conjugate():
453     """
454     Set the quaternion to it's conjugate.
455     """
456
457   def inverse():
458     """
459     Set the quaternion to it's inverse
460     """
461
462   def normalize():
463     """
464     Normalize the quaternion.
465     """
466
467   def toEuler():
468     """
469     Return Euler representation of the quaternion.
470     @rtype: Euler object
471     @return: Euler representation of the quaternion.
472
473     """
474   
475   def toMatrix():
476     """
477     Return a matrix representation of the quaternion.
478     @rtype: Matrix object
479     @return: A rotation matrix representation of the quaternion.
480
481     """
482
483 class Matrix:
484   """
485   The Matrix Object
486   =================
487     This object gives access to Matrices in Blender.
488   @cvar rowsize: The row size of the matrix.
489   @cvar colsize: The column size of the matrix.
490   """
491
492   def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
493     """  
494     Create a new matrix object from initialized values.
495
496     Example::
497       matrix = Mathutils.Matrix([1,1,1],[0,1,0],[1,0,0])
498
499     @type list1: PyList of int/float
500     @param list1: A 2d,3d or 4d list.
501     @type list2: PyList of int/float
502     @param list2: A 2d,3d or 4d list.
503     @type list3: PyList of int/float
504     @param list3: A 2d,3d or 4d list.
505     @type list4: PyList of int/float
506     @param list4: A 2d,3d or 4d list.
507     @rtype: New matrix object.
508     @return: It depends wheter a parameter was passed:
509         - (list1, etc.): Matrix object initialized with the given values;
510         - ():     An empty 3 dimensional matrix.
511     """
512
513   def zero():
514     """
515     Set all matrix values to 0.
516     """
517
518   def identity():
519     """
520     Set the matrix to the identity matrix.
521     """
522
523   def transpose():
524     """
525     Set the matrix to it's transpose.
526     """
527
528   def determinant():
529     """
530     Return a the determinant of a matrix.
531     @rtype: int
532     @return: Return a the determinant of a matrix.
533
534     """
535
536   def inverse():
537     """
538     Set the matrix to it's inverse.
539     """
540
541   def rotationPart():
542     """
543     Return the 3d rotation matrix.
544     @rtype: Matrix object.
545     @return: Return the 3d rotation matrix.
546
547     """
548
549   def translationPart():
550     """
551     Return a the translation part of a 4 row matrix.
552     @rtype: Vector object.
553     @return: Return a the translation of a matrix.
554
555     """
556
557   def resize4x4():
558     """
559     Resize the matrix to by 4x4
560     """
561   
562   def toEuler():
563     """
564     Return a euler representing the rotation matrix.
565     @rtype: Euler object
566     @return: Return a euler representing the rotation matrix.
567
568     """
569
570   def toQuat():
571     """
572     Return a quaternion representation the rotation matrix
573     @rtype: Quaternion object
574     @return: Quaternion representation the rotation matrix
575
576     """
577