== console ==
[blender-staging.git] / doc / python_api / epy / Mathutils.py
1 # Blender.mathutils module and its subtypes
2
3
4
5 class Vector:
6   """
7   
8   @attention: Vector data can be wrapped or non-wrapped. When a object is wrapped it
9   means that the object will give you direct access to the data inside of blender. Modification
10   of this object will directly change the data inside of blender. To copy a wrapped object
11   you need to use the object's constructor. If you copy and object by assignment you will not get
12   a second copy but a second reference to the same data. Only certain functions will return 
13   wrapped data. This will be indicated in the method description.
14   """
15
16   def __init__(list = None):
17     """
18     Create a new 2d, 3d, or 4d Vector object from a list of floating point numbers.
19     @note: that python uses higher precission floating point numbers, so values assigned to a vector may have some rounding error.
20     
21
22     Example::
23       v = Vector(1,0,0)
24       v = Vector(myVec)
25       v = Vector(list)
26     @type list: PyList of float or int
27     @param list: The list of values for the Vector object. Can be a sequence or raw numbers.
28     Must be 2, 3, or 4 values. The list is mapped to the parameters as [x,y,z,w].
29     @rtype: Vector object.
30     @return: It depends wheter a parameter was passed:
31         - (list): Vector object initialized with the given values;
32         - ():     An empty 3 dimensional vector.
33     """
34
35 class Euler:
36   """
37   The Euler object
38   ================
39     This object gives access to Eulers in Blender.
40   @note: You can access a euler object like a sequence
41       - x = euler[0]
42   @note: Comparison operators can be done:
43       - ==, != test numeric values within epsilon
44   @attention: Euler data can be wrapped or non-wrapped. When a object is wrapped it
45   means that the object will give you direct access to the data inside of blender. Modification
46   of this object will directly change the data inside of blender. To copy a wrapped object
47   you need to use the object's constructor. If you copy and object by assignment you will not get
48   a second copy but a second reference to the same data. Only certain functions will return 
49   wrapped data. This will be indicated in the method description.
50   """
51
52   def __init__(list = None):
53     """
54     Create a new euler object.
55
56     Example::
57       euler = Euler(45,0,0)
58       euler = Euler(myEuler)
59       euler = Euler(sequence)
60     @type list: PyList of float/int
61     @param list: 3d list to initialize euler
62     @rtype: Euler object
63     @return: Euler representing heading, pitch, bank.
64     @note: Values are in degrees.
65     """
66
67 class Quaternion:
68   """
69   The Quaternion object
70   =====================
71     This object gives access to Quaternions in Blender.
72   @note: Comparison operators can be done:
73       - ==, != test numeric values within epsilon
74   @note: Math can be performed on Quaternion classes
75       - quat + quat
76       - quat - quat 
77       - quat * float/int
78       - quat * vec
79       - quat * quat
80   @note: You can access a quaternion object like a sequence
81       - x = quat[0]
82   @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
83   means that the object will give you direct access to the data inside of blender. Modification
84   of this object will directly change the data inside of blender. To copy a wrapped object
85   you need to use the object's constructor. If you copy and object by assignment you will not get
86   a second copy but a second reference to the same data. Only certain functions will return 
87   wrapped data. This will be indicated in the method description.
88   """
89
90   def __init__(list, angle = None):
91     """  
92     Create a new quaternion object from initialized values.
93
94     Example::
95       quat = Quaternion(1,2,3,4)
96       quat = Quaternion(axis, angle)
97     quat = Quaternion()
98     quat = Quaternion(180, list)
99
100     @type list: PyList of int/float
101     @param list: A 3d or 4d list to initialize quaternion.
102         4d if intializing [w,x,y,z], 3d if used as an axis of rotation.
103     @type angle: float (optional)
104     @param angle: An arbitrary rotation amount around 'list'.
105         List is used as an axis of rotation in this case.
106     @rtype: New quaternion object.
107     @return: It depends wheter a parameter was passed:
108         - (list/angle): Quaternion object initialized with the given values;
109         - ():     An identity 4 dimensional quaternion.
110     """
111
112 class Matrix:
113   """
114   The Matrix Object
115   =================
116   @note: Math can be performed on Matrix classes
117       - mat + mat 
118       - mat - mat 
119       - mat * float/int
120       - mat * vec
121       - mat * mat 
122   @note: Comparison operators can be done:
123       - ==, != test numeric values within epsilon
124   @note: You can access a quaternion object like a 2d sequence
125       - x = matrix[0][1]
126       - vector = matrix[2]
127   @attention: Quaternion data can be wrapped or non-wrapped. When a object is wrapped it
128   means that the object will give you direct access to the data inside of blender. Modification
129   of this object will directly change the data inside of blender. To copy a wrapped object
130   you need to use the object's constructor. If you copy and object by assignment you will not get
131   a second copy but a second reference to the same data. Only certain functions will return 
132   wrapped data. This will be indicated in the method description.
133   """
134
135   def __init__(list1 = None, list2 = None, list3 = None, list4 = None):
136     """  
137     Create a new matrix object from initialized values.
138
139     Example::
140       matrix = Matrix([1,1,1],[0,1,0],[1,0,0])
141       matrix = Matrix(mat)
142       matrix = Matrix(seq1, seq2, vector)
143
144     @type list1: PyList of int/float
145     @param list1: A 2d,3d or 4d list.
146     @type list2: PyList of int/float
147     @param list2: A 2d,3d or 4d list.
148     @type list3: PyList of int/float
149     @param list3: A 2d,3d or 4d list.
150     @type list4: PyList of int/float
151     @param list4: A 2d,3d or 4d list.
152     @rtype: New matrix object.
153     @return: It depends wheter a parameter was passed:
154         - (list1, etc.): Matrix object initialized with the given values;
155         - ():     An empty 3 dimensional matrix.
156     """