Module Ipo
[hide private]
[frames] | no frames]

Source Code for Module Ipo

  1  # Blender.Ipo module and the Ipo PyType object 
  2   
  3  """ 
  4  The Blender.Ipo submodule 
  5   
  6  B{New}:  
  7          -  Ipo updates to both the program and Bpython access. 
  8          -  access to Blender's new Ipo driver capabilities. 
  9          -  Ipo now supports the mapping operator [] to access IpoCurves 
 10   
 11  This module provides access to the Ipo Data in Blender. An Ipo is composed of 
 12  several IpoCurves, and an IpoCurve is composed of several BezTriples. 
 13   
 14  Example:: 
 15          from Blender import Ipo 
 16   
 17          ipo = Ipo.Get('ObIpo')                          # retrieves an Ipo object 
 18          ipo.name = 'ipo1'                                       # change the Ipo's name 
 19          icu = ipo[Ipo.OB_LOCX]                          # request X Location Ipo curve 
 20          if icu != None and len(icu.bezierPoints) > 0: # if curve exists and has BezTriple points 
 21                  val = icu[2.5]                                  # get the curve's value at time 2.5 
 22                  ipo[Ipo.OB_LOCX] = None                 # delete the Ipo curve 
 23           
 24  Each type of Ipo has different types Ipocurves.  With the exception of Shape 
 25  Key Ipos, constants are used to specify all Ipocurves.  There are two ways 
 26  to tell which Ipo curves go with which Ipo type: 
 27          - all constants start with a two-character identifier for their Ipo type; 
 28          for example, "OB_LOCX" is the LocX curve for an Object Ipo 
 29          - each Ipo now has a read-only attribute L{Ipo.curveConsts}, which returns  
 30          the valid Ipo curve types for that specific Ipo 
 31   
 32  The valid IpoCurve constants are: 
 33                          1. Material Ipo: MA_R, MA_G, MA_B, MA_SPECR, MA_SPECG, MA_SPECB, 
 34                          MA_MIRR, MA_MIRG, MA_MIRB, MA_REF, MA_ALPHA, MA_EMIT, MA_AMB, 
 35                          MA_SPEC, MA_HARD, MA_SPTRA, MA_IOR, MA_MODE, MA_HASIZE, MA_TRANSLU, 
 36                          MA_RAYMIR, MA_FRESMIR, MA_FRESMIRI, MA_FRESTRA, MA_FRESTRAI, 
 37                          MA_TRAGLOW, MA_OFSX, MA_OFSY, MA_OFSZ, MA_SIZEX, MA_SIZEY, MA_SIZEZ, 
 38                          MA_TEXR, MA_TEXG, MA_TEXB, MA_DEFVAR, MA_COL, MA_NOR, MA_VAR, MA_DISP 
 39                          2. Lamp Ipo: LA_ENERG, LA_R, LA_G, LA_B, LA_DIST, LA_SPOSI, LA_SPOBL, 
 40                          LA_QUAD1, LA_QUAD2, LA_HAINT, LA_OFSX, LA_OFSY, LA_OFSZ, LA_SIZEX, 
 41                          LA_SIZEY, LA_SIZEZ, LA_TEXR, LA_TEXG, LA_TEXB, LA_DEFVAR, LA_COL 
 42                          3. World Ipo: WO_HORR, WO_HORG, WO_HORB, WO_ZENR, WO_ZENG, WO_ZENB, 
 43                          WO_EXPOS, WO_MISI, WO_MISDI, WO_MISSTA, WO_MISHI, WO_STARR, 
 44                          WO_STARB, WO_STARG, WO_STARDI, WO_STARSI, WO_OFSX, WO_OFSY, 
 45                          WO_OFSZ, WO_SIZEX, WO_SIZEY, WO_SIZEZ, WO_TEXR, WO_TEXG, 
 46                          WO_TEXB, WO_DEFVAR, WO_COL, WO_NOR, WO_VAR 
 47                          4. Camera Ipo: CA_LENS, CA_CLSTA, CA_CLEND, CA_APERT, CA_FDIST 
 48                          5. Object Ipo: OB_LOCX, OB_LOCY, OB_LOCZ, OB_DLOCX, OB_DLOCY, OB_DLOCZ, 
 49                          OB_ROTX, OB_ROTY, OB_ROTZ, OB_DROTX, OB_DROTY, OB_DROTZ, 
 50                          OB_SCALEX, OB_SCALEY, OB_SCALEZ, OB_DSCALEX, OB_DSCALEY, OB_DSCALEZ, 
 51                          OB_LAYER, OB_TIME, OB_COLR, OB_COLG, OB_COLB, OB_COLA, 
 52                          OB_FSTRENG, OB_FFALL, OB_RDAMP, OB_DAMPING, OB_PERM 
 53                          6. Curve Ipo: CU_SPEED 
 54                          7. Constraint Ipo: CO_INF 
 55                          8. Texture Ipo: TE_NSIZE, TE_NDEPTH, TE_NTYPE, TE_TURB, TE_VNW1, TE_VNW2, 
 56                          TE_VNW3, TE_VNW4, TE_MINKMEXP, TE_DISTM, TE_COLT, TE_ISCALE, 
 57                          TE_DISTA, TE_MGTYPE, TE_MGH, TE_LACU, TE_OCT, TE_MGOFF, 
 58                          TE_MGGAIN, TE_NBASE1, TE_NBASE2, TE_COLR, TE_COLG, TE_COLB, 
 59                          TE_BRIGHT, TE_CONTRAS 
 60                          9. Pose/Action Ipo: PO_LOCX, PO_LOCY, PO_LOCZ, PO_SCALEX, PO_SCALEY, 
 61                          PO_SCALEZ, PO_QUATW, PO_QUATX, PO_QUATY, PO_QUATZ 
 62                          10. Sequence Ipo: SQ_FAC 
 63   
 64  Shape Key Ipos are handled differently from other Ipos.  The user can rename 
 65  the curves, so string are used to access them instead of constants.  The 
 66  L{Ipo.curveConsts} attribute for Shape Key Ipos returns a list of all defined 
 67  key names. 
 68  """ 
 69   
70 -def New (type, name):
71 """ 72 Creates a new Ipo. 73 @type type: string 74 @type name: string 75 @param type: The Ipo's blocktype. Depends on the object the Ipo will be 76 linked to. Currently supported types are Object, Camera, World, 77 Material, Texture, Lamp, Action, Constraint, Sequence, Curve, Key. 78 @param name: The name for this Ipo. 79 @rtype: Blender Ipo 80 @return: The created Ipo. 81 """
82
83 -def Get (name = None):
84 """ 85 Get the Ipo from Blender. 86 @type name: string 87 @param name: The name of the requested Ipo, or nothing. 88 @rtype: Blender Ipo or a list of Blender Ipos 89 @return: It depends on the 'name' parameter: 90 - (name): The Ipo with the given name; 91 - (): A list with all Ipos in the current scene. 92 """
93
94 -class Ipo:
95 """ 96 The Ipo object 97 ============== 98 This object gives access to Ipo data from all objects in Blender. 99 @Note: Blender Materials, Lamps and Worlds have I{texture channels} which 100 allow the user to assign textures to them. The Blender Ipo Window allows 101 the user to access the IpoCurves for these channels by specifying a number 102 between 0 and 9 (the number appears next to the Ipo type in the window 103 header). Prior to Version 2.42, the BPy API did not allow users to access 104 these texture channels in a predictable manner. A new attribute named 105 L{channel} was added to the API in Version 2.42 to correct this problem. 106 107 The current channel setting has an effect on the operators B{[]}, B{len()} 108 and others. For example, suppose a Material has three IpoCurves 109 (R, G, and B), and two texture channels (numbered 0 and 1), and furthermore 110 channel 0 has one Ipocurve (Col). The IpoCurve Col can only be 111 "seen" through the API when B{ipo.channel} is 0. Setting B{ipo.channel} to 112 1 will cause this curve to be ignored by B{len(ipo)}:: 113 114 from Blender import Ipo 115 116 ipo = Ipo.Get('MatIpo') 117 for channel in xrange(2): 118 ipo.channel = channel 119 print 'channel is',channel 120 print ' len is',len(ipo) 121 names = dict([(x[1],x[0]) for x in ipo.curveConsts.items()]) 122 for curve in [Ipo.MA_R,Ipo.MA_COL]: 123 print ' ',names[curve],'is',curve in ipo 124 125 will output:: 126 channel is 0 127 len is 4 128 MA_R is True 129 MA_COL is True 130 channel is 1 131 len is 3 132 MA_R is True 133 MA_COL is False 134 135 @ivar curves: Ipo curves currently defined for the Ipo. 136 @type curves: list of Ipocurves. 137 @ivar curveConsts: The valid Ipo curves for this Ipo. These can be used 138 by the [] mapping operator. The value 139 depends on the Ipo curve type. If the Ipo is any type other than a Key or 140 Shape Ipo, this attribute returns a set of constants that can be 141 used to specify a particular curve. For Key or Shape Ipos, the attribute 142 returns a list of all defined keys by name. 143 @type curveConsts: constant or list of strings. Read-only. 144 @ivar channel: the current texture channel for Blender object which support 145 textures (materials, lamps and worlds). Returns None if the Ipo does 146 not support texture channels. Value must be in the range [0,9]. 147 @type channel: int or None 148 """ 149
150 - def __contains__():
151 """ 152 The "in" operator for Ipos. It returns B{True} if the specified 153 IpoCurve exists for the Ipo. This operator B{should not} be used to 154 test for whether a curve constant is valid for a particular Ipo type. 155 Many constants for different Ipo types have the same value, and it is 156 the constant's value used internally. 157 No exceptions are raised if the argument is not a valid curve constant or 158 or string, nor does the operator return B{True} when the curve 159 constant is valid but does not currently exist. As such, it should only be 160 used to test for specific curves when the Ipo type is known:: 161 ipo = Object.Get('Cube').ipo # get Object-type Ipo 162 if ipo: 163 print Ipo.OB_LOCX in ipo # prints "True" if 'LocX' curve exists 164 print Ipo.MA_R in ipo # also prints "True" since MA_R and OB_LOCX are have the same value 165 print 'hiccup' in ipo # always prints "False" since argument is not a constant 166 167 @return: see above. 168 @rtype: Boolean 169 """
170
171 - def __getitem__():
172 """ 173 This operator is similar to the Python dictionary mapping operator [], 174 except that the user cannot assign arbitrary keys. Each Ipo type has 175 a pre-defined set of IpoCurves which may or may not exist at a given time. This operator 176 will either return an IpoCurve object if the specified curve exists, 177 return None if the curve does not exists, or throws a KeyError exception 178 if the curve is not valid for this Ipo type. 179 @return: an IpoCurve object if it exists 180 @rtype: IpoCurve or None 181 @raise KeyError: an undefined IpoCurve was specified for the Ipo 182 """
183
184 - def __iter__():
185 """ 186 Iterator for Ipos. It returns all the defined IpoCurve objects associated 187 with the Ipo. For example:: 188 from Blender import Ipo 189 190 ipo = Ipo.Get() 191 if len(ipo) > 0: 192 ipo = ipo[0] 193 print 'ipo name is',ipo.name 194 for icu in ipo: 195 print ' curve name is',icu.name 196 might result in:: 197 ipo name is ObIpo 198 curve name is LocX 199 curve name is LocY 200 curve name is LocZ 201 202 @return: an IpoCurve object 203 @rtype: IpoCurve 204 """
205
206 - def __len__():
207 """ 208 Returns the number of curves defined for the Ipo. 209 @return: number of defined IpoCurves 210 @rtype: int 211 """
212
213 - def getName():
214 """ 215 Gets the name of the Ipo (B{deprecated}). See the L{name} attribute. 216 @rtype: string 217 @return: the name of the Ipo. 218 """
219
220 - def setName(newname):
221 """ 222 Sets the name of the Ipo (B{deprecated}). See the L{name} attribute. 223 @type newname: string 224 @rtype: None 225 @return: None 226 """
227
228 - def getCurves():
229 """ 230 Gets all the IpoCurves of the Ipo (B{deprecated}). Use the 231 L{iterator operator []<__iter__>} instead. 232 @rtype: list of IpoCurves 233 @return: A list (possibly empty) containing all the IpoCurves associated 234 to the Ipo object. 235 """
236
237 - def getCurve(curve):
238 """ 239 Return the specified IpoCurve (B{deprecated}). Use the L{mapping 240 operator B{[]}<__getitem__>} instead. 241 If the curve does not exist in the Ipo, 242 None is returned. I{curve} can be either a string or an integer, 243 denoting either the name of the Ipo curve or its internal adrcode. 244 The possible Ipo curve names are: 245 246 1. Camera Ipo: Lens, ClSta, ClEnd, Apert, FDist. 247 2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref, 248 Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu, 249 RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY, 250 OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var, 251 Disp. 252 3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ, 253 dRotX, dRotY, dRotZ, ScaleX, ScaleY, ScaleZ, dScaleX, dScaleY, dScaleZ, 254 Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping, 255 RDamp, Perm. 256 4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt. 257 5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi, 258 MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ, 259 SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var. 260 5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi, 261 MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i 262 SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var. 263 6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4, 264 MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct, 265 MgOff, MgGain, NBase1, NBase2. 266 7. Curve Ipo: Speed. 267 8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY, 268 QuatZ, QuatW. 269 9. Sequence Ipo: Fac. 270 10. Constraint Ipo: Inf. 271 272 The adrcode for the Ipo curve can also be given; this is useful for 273 accessing curves for Shape Key Ipos. The adrcodes for Shape Key Ipo are 274 numbered consecutively starting at 0. 275 @type curve : string or int 276 @rtype: IpoCurve object 277 @return: the corresponding IpoCurve, or None. 278 @raise ValueError: I{curve} is not a valid name or adrcode for this Ipo 279 type. 280 """
281
282 - def addCurve(curvename):
283 """ 284 Add a new curve to the Ipo object. The possible values for I{curvename} are: 285 1. Camera Ipo: Lens, ClSta, ClEnd, Apert, FDist. 286 2. Material Ipo: R, G, B, SpecR, SpecG, SpecB, MirR, MirG, MirB, Ref, 287 Alpha, Emit, Amb, Spec, Hard, SpTra, Ior, Mode, HaSize, Translu, 288 RayMir, FresMir, FresMirI, FresTra, FresTraI, TraGlow, OfsX, OfsY, 289 OfsZ, SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var, 290 Disp. 291 3. Object Ipo: LocX, LocY, LocZ, dLocX, dLocY, dLocZ, RotX, RotY, RotZ, 292 dRotX, dRotY, dRotZ, ScaleX, ScaleY, ScaleZ, dScaleX, dScaleY, dScaleZ, 293 Layer, Time, ColR, ColG, ColB, ColA, FStreng, FFall, Damping, 294 RDamp, Perm. 295 4. Lamp Ipo: Energ, R, G, B, Dist, SpoSi, SpoBl, Quad1, Quad2, HaInt. 296 5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi, 297 MisSta, MisHi, StaR, StaG, StaB, StarDi, StarSi, OfsX, OfsY, OfsZ, 298 SizeX, SizeY, SizeZ, TexR, TexG, TexB, DefVar, Col, Nor, Var. 299 5. World Ipo: HorR, HorG, HorB, ZenR, ZenG, ZenB, Expos, Misi, MisDi, 300 MisSta, MisHi, StarR, StarB, StarG, StarDi, StarSi, OfsX, OfsY, OfsZ,i 301 SizeX, SizeY, SizeZ, texR, texG, texB, DefVar, Col, Nor, Var. 302 6. Texture Ipo: NSize, NDepth, NType, Turb, Vnw1, Vnw2, Vnw3, Vnw4, 303 MinkMExp, DistM, ColT, iScale, DistA, MgType, MgH, Lacu, Oct, 304 MgOff, MgGain, NBase1, NBase2. 305 7. Curve Ipo: Speed. 306 8. Action Ipo: LocX, LocY, LocZ, SizeX, SizeY, SizeZ, QuatX, QuatY, 307 QuatZ, QuatW. 308 9. Sequence Ipo: Fac. 309 10. Constraint Ipo: Inf. 310 311 For Key IPOs, the name must be an existing KeyBlock name. Use 312 L{curveConsts} to determine the set of valid names. 313 314 @type curvename : string 315 @rtype: IpoCurve object 316 @return: the corresponding IpoCurve, or None. 317 @raise ValueError: I{curvename} is not valid or already exists 318 """
319
320 - def delCurve(curvename):
321 """ 322 Delete an existing curve from the Ipo object (B{deprecated}). 323 Use the L{mapping operator B{[]}<__getitem__>} instead:: 324 from Blender import Ipo 325 326 ipo = Ipo.Get('ObIpo') 327 ipo[Ipo.LOCX] = None 328 329 @type curvename : string 330 @rtype: None 331 @return: None. 332 """
333
334 - def getBlocktype():
335 """ 336 Gets the blocktype of the Ipo. 337 @rtype: int 338 @return: the blocktype of the Ipo. 339 """
340
341 - def setBlocktype(newblocktype):
342 """ 343 Sets the blocktype of the Ipo. 344 @type newblocktype: int 345 @rtype: None 346 @return: None 347 @warn: 'newblocktype' should not be changed unless you really know what 348 you are doing ... 349 """
350
351 - def getRctf():
352 """ 353 Gets the rctf of the Ipo. 354 Kind of bounding box... 355 @rtype: list of floats 356 @return: the rctf of the Ipo. 357 """
358
359 - def setRctf(newrctf):
360 """ 361 Sets the rctf of the Ipo. 362 @type newrctf: four floats. 363 @rtype: None 364 @return: None 365 @warn: rctf should not be changed unless you really know what you are 366 doing ... 367 """
368
369 - def getNcurves():
370 """ 371 Gets the number of curves of the Ipo (B{deprecated}). Use 372 L{len(ipo)<__len__>} instead. 373 @rtype: int 374 @return: the number of curve of the Ipo. 375 """
376
377 - def getCurveBP(curvepos):
378 """ 379 This method is unsupported. BPoint Ipo curves are not implemented. 380 Calling this method throws a NotImplementedError exception. 381 @raise NotImplementedError: this method B{always} raises an exception 382 """
383
384 - def getBeztriple(curvepos,pointpos):
385 """ 386 Gets a beztriple of the Ipo (B{deprecated}). B{Note}: 387 Use L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} instead. 388 @type curvepos: int 389 @param curvepos: the position of the curve in the Ipo. 390 @type pointpos: int 391 @param pointpos: the position of the point in the curve. 392 @rtype: list of 9 floats 393 @return: the beztriple of the Ipo, or an error is raised. 394 """
395
396 - def setBeztriple(curvepos,pointpos,newbeztriple):
397 """ 398 Sets the beztriple of the Ipo (B{deprecated}). B{Note}: use 399 L{IpoCurve.bezierPoints<IpoCurve.IpoCurve.bezierPoints>} to get a 400 BezTriple point, then use the 401 L{BezTriple} API to set the point's attributes. 402 @type curvepos: int 403 @param curvepos: the position of the curve in the Ipo. 404 @type pointpos: int 405 @param pointpos: the position of the point in the curve. 406 @type newbeztriple: list of 9 floats 407 @param newbeztriple: the new value for the point 408 @rtype: None 409 @return: None 410 """
411
412 - def getCurveCurval(curvepos):
413 """ 414 Gets the current value of a curve of the Ipo (B{deprecated}). B{Note}: 415 new scripts should use L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}. 416 @type curvepos: int or string 417 @param curvepos: the position of the curve in the Ipo or the name of the 418 curve 419 @rtype: float 420 @return: the current value of the selected curve of the Ipo. 421 """
422
423 - def EvaluateCurveOn(curvepos,time):
424 """ 425 Gets the value at a specific time of a curve of the Ipo (B{deprecated}). 426 B{Note}: new scripts should use 427 L{IpoCurve.evaluate()<IpoCurve.IpoCurve.evaluate>}. 428 @type curvepos: int 429 @param curvepos: the position of the curve in the Ipo. 430 @type time: float 431 @param time: the desired time. 432 @rtype: float 433 @return: the current value of the selected curve of the Ipo at the given 434 time. 435 """
436 import id_generics 437 Ipo.__doc__ += id_generics.attributes 438