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. The list is mapped to the parameters as [x,y,z,w].
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, angle = None):
424     """  
425     Create a new quaternion object from initialized values.
426
427     Example::
428       quat = Mathutils.Quaternion([1.0,0.0,0.0])
429
430     @type list: PyList of int/float
431     @param list: A 3d or 4d list to initialize quaternion.
432         4d if intializing [w,x,y,z], 3d if 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 the determinant of a matrix.
531     @rtype: int
532     @return: Return a the determinant of a matrix.
533
534     """
535
536   def invert():
537     """
538     Set the matrix to it's inverse.
539     """
540
541   def rotationPart():
542     """
543     Return the 3d submatrix corresponding to the linear term of the 
544     embedded affine transformation in 3d. This matrix represents rotation
545     and scale. Note that the (4,4) element of a matrix can be used for uniform
546     scaling, too.
547     @rtype: Matrix object.
548     @return: Return the 3d matrix for rotation and scale.
549
550     """
551
552   def translationPart():
553     """
554     Return a the translation part of a 4 row matrix.
555     @rtype: Vector object.
556     @return: Return a the translation of a matrix.
557
558     """
559
560   def resize4x4():
561     """
562     Resize the matrix to by 4x4
563     """
564   
565   def toEuler():
566     """
567     Return an Euler representation of the rotation matrix.
568     @rtype: Euler object
569     @return: Euler representation of the rotation matrix.
570
571     """
572
573   def toQuat():
574     """
575     Return a quaternion representation of the rotation matrix
576     @rtype: Quaternion object
577     @return: Quaternion representation of the rotation matrix
578
579     """
580