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