cleanup epydoc errors
[blender.git] / source / blender / python / api2_2x / doc / IpoCurve.py
1 # Blender.IpoCurve module and the IpoCurve PyType object
2
3 """
4 The Blender.IpoCurve submodule
5
6 B{New}: 
7   -  IpoCurves supports the operator [], which accesses the value of 
8      curves at a given time. 
9
10 This module provides access to the IpoCurve data in Blender.  An Ipo is 
11 composed of several IpoCurves, and an IpoCurve are composed of several 
12 BezTriples.
13
14 @warning: Ipo curves store euler rotations as degrees/10.0 so 180.0 would be 18.0
15
16 Example::
17   import Blender
18   ipo = Blender.Ipo.Get('ObIpo')  # retrieves an Ipo object
19   ipo.name = 'ipo1'                 # change the Ipo's name
20   icu = ipo[Blender.Ipo.OB_LOCX] # request X Location Ipo curve object
21   if icu != None and len(icu.bezierPoints) > 0: # if curve exists and has BezTriple points
22      val = icu[2.5]              # get the curve's value at time 2.5
23   
24 @type ExtendTypes: readonly dictionary
25 @var ExtendTypes: The available IpoCurve extend types.
26     - CONST - curve is constant beyond first and last knots
27     - EXTRAP - curve maintains same slope beyond first and last knots
28     - CYCLIC - curve values repeat beyond first and last knots
29     - CYCLIC_EXTRAP - curve values repeat beyond first and last knots,
30     but while retaining continuity
31
32 @type InterpTypes: readonly dictionary
33 @var InterpTypes: The available IpoCurve interpolation types.
34     - CONST - curve remains constant from current BezTriple knot
35     - LINEAR - curve is linearly interpolated between adjacent knots
36     - BEZIER - curve is interpolated by a Bezier curve between adjacent knots
37 """
38
39 class IpoCurve:
40   """
41   The IpoCurve object
42   ===================
43   This object gives access to generic data from all Ipo curves objects
44   in Blender.
45
46   Important Notes for Rotation Ipo Curves:\n
47   For the rotation Ipo curves, the y values for points are in units of 10
48   degrees.  For example, 45.0 degrees is stored as 4.50 degrees.  These are the
49   same numbers you see in the Transform Properties pop-up menu ( NKey ) in
50   the IPO Curve Editor window.  Positive rotations are in a counter-clockwise
51   direction, following the standard convention.
52   
53   @ivar driver:  Status of the driver.  1= on, 0= object, 2= python expression.
54   @type driver:  int
55   @ivar driverObject:  Object used to drive the Ipo curve.
56   @type driverObject:  Blender Object or None
57   @ivar driverExpression:  Python expression used to drive the Ipo curve. [0 - 127 chars]
58   @type driverExpression:  string
59   @ivar sel:  The selection state of this curve.
60   @type sel:  bool
61   @ivar driverChannel:  Object channel used to drive the Ipo curve.
62   Use module constants: IpoCurve.LOC_X, IpoCurve.LOC_Y, IpoCurve.LOC_Z,
63   IpoCurve.ROT_X, IpoCurve.ROT_Y, IpoCurve.ROT_Z, IpoCurve.SIZE_X,
64   IpoCurve.SIZE_Y, IpoCurve.SIZE_Z
65   @type driverChannel:  int 
66   @ivar name: The IpoCurve data name.
67   @type name: string
68   @ivar bezierPoints: The list of the curve's bezier points.
69   @type bezierPoints: list of BezTriples.
70   @ivar interpolation: The curve's interpolation mode.  See L{InterpTypes} for
71   values.
72   @type interpolation: int
73   @ivar extend: The curve's extend mode. See L{ExtendTypes} for values.
74
75   B{Note}: Cyclic Ipo curves never reach the end value.  If the first and
76   last bezier points do not have the same y coordinate, the value of the
77   curve when it "cycles" is that of the first point.  If a user wants to
78   get the value of the final curve point, read the final point from the
79   curve::
80
81         ipo = Blender.Object.Get('Cube').ipo
82         icu = ipo['LocX']
83         endtime,endvalue = icu.bezierPoints[-1].pt
84   @type extend: int
85   """
86
87   def __getitem__ (time):
88     """
89     Returns the value of the curve at a particular time.
90     @type time: float
91     @param time: time (Vertex X) on the curve
92     @rtype: float
93     @return: value (Vertex Y) corresponding to the given time
94     """
95
96   def __setitem__ (time):
97     """
98     Sets the value (Vertex Y) of the curve at a particular time.
99     @type time: float
100     @param time: time (Vertex X) on the curve
101     """
102
103   def setExtrapolation(extendmode):
104     """
105     Sets the extend mode of the curve (B{deprecated}).  B{Note}: new scripts
106     should use the L{extend} attribute instead.
107     @type extendmode: string
108     @param extendmode: the extend mode of the curve.
109         Can be Constant, Extrapolation, Cyclic or Cyclic_extrapolation.
110     @rtype: None
111     @return: None
112     """
113
114   def getExtrapolation():
115     """
116     Gets the extend mode of the curve (B{deprecated}).  B{Note}: new scripts
117     should use the L{extend} attribute instead.
118     @rtype: string
119     @return: the extend mode of the curve. Can be Constant, Extrapolation, Cyclic or Cyclic_extrapolation.
120     """
121
122   def setInterpolation(interpolationtype):
123     """
124     Sets the interpolation type of the curve (B{deprecated}).  B{Note}: 
125     new scripts should use the L{interpolation} attribute instead.
126     @type interpolationtype: string
127     @param interpolationtype: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
128     @rtype: None
129     @return: None
130     """
131
132   def getInterpolation():
133     """
134     Gets the interpolation type of the curve (B{deprecated}).  B{Note}:
135     new scripts should use the L{interpolation} attribute instead.
136     @rtype: string
137     @return: the interpolation type of the curve. Can be Constant, Bezier, or Linear.
138     """
139     
140   def append(point):
141     """
142     Adds a Bezier point to a IpoCurve.
143     @type point: BezTriple or tuple of 2 floats 
144     @param point: Can either be a BezTriple, or the x and y coordinates of
145     the Bezier knot point.
146     @rtype: None
147     @return: None
148     """
149  
150   def addBezier(coordlist):
151     """
152     Adds a Bezier point to a curve B{deprecated}). B{Note}: new scripts
153     should use L{append} instead.
154     @type coordlist: tuple of (at least) 2 floats
155     @param coordlist: the x and y coordinates of the new Bezier point.
156     @rtype: None
157     @return: None
158     """
159
160   def delBezier(index):
161     """
162     Deletes a Bezier point from a curve.
163     @type index: integer
164     @param index: the index of the Bezier point.  Negative values index from the end of the list.
165     @rtype: None
166     @return: None
167     """
168
169   def recalc():
170     """
171     Recomputes the curve after changes to control points.
172     @rtype: None
173     @return: None
174     """
175
176   def getName():
177     """
178     Returns the name of the Ipo curve (B{deprecated}). B{Note}:
179     new scripts should use the L{name} attribute instead.
180     The name can be:
181       1. Camera Ipo:  Lens, ClSta, ClEnd, Apert, FDist.
182       2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref,
183       Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu,
184       RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY,
185       OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var,
186       Disp.
187       3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ,
188       dRotX, dRotY, dRotZ, SizeX, SizeY, SizeZ, dSizeX, dSizeY, dSizeZ,
189       Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping,
190       RDamp, Perm.
191       4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt.
192       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
193       MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ,
194       SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var.
195       5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi,
196       MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i
197       SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var.
198       6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4,
199       MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct,
200       MgOff, MgGain, NBase1, NBase2.
201       7. Curve Ipo: Speed.
202       8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY,
203       QuatZ, QuatW.
204       9. Sequence Ipo: Fac.
205       10. Constraint Ipo: Inf.
206
207     @rtype: string
208     @return: the name of the Ipo curve.
209     """
210
211   def getPoints():
212     """
213     Returns all the points of the IpoCurve (B{deprecated}).
214     B{Note}: new scripts should use the L{bezierPoints} attribute instead.
215     @rtype: list of BezTriples
216     @return: the points of the Ipo curve.
217     """
218
219   def clean( thresh=0.0000001 ):
220     """
221     Calls the IPO-curve cleaning function on this IpoCurve. 
222     There is no need to recalculate curve manually.
223     @type thresh: float
224     @param thresh: The threshold to used to determine if two values are identical. 
225     By default, the IPO-editor tool's value is used.
226     @rtype: None
227     @return: None
228     """
229
230   def evaluate( time ):
231     """
232     Compute the value of the Ipo curve at a particular time (B{deprecated}).
233     B{Note}: new scripts should use L{icu[time]<__getitem__>} instead.
234     @type time: float
235     @param time: value along the X axis
236     @rtype: float
237     @return: the Y value of the curve at the given time
238     """
239