added id_attributes.py, this containes ID doc strings, all datablocks that have use...
[blender.git] / source / blender / python / api2_2x / doc / Curve.py
1 # Blender.Curve module and the Curve PyType object
2
3 """
4 The Blender.Curve submodule.
5
6 Curve Data
7 ==========
8
9 This module provides access to B{Curve Data} objects in Blender.
10
11 A Blender Curve Data consists of multiple L{CurNurb}(s). Try converting a Text object to a Curve to see an example of this.   Each curve is of
12 type Bezier or Nurb.  The underlying L{CurNurb}(s) can be accessed with
13 the [] operator.  Operator [] returns an object of type L{CurNurb}.
14
15 Note that L{CurNurb} can be used to acces a curve of any type (Poly, Bezier or Nurb)
16
17 The Curve module also supports the Python iterator interface.  This means you
18 can access the L{CurNurb}(s) in a Curve and the control points in a L{CurNurb} using a
19 Python B{for} statement.
20
21
22 Add a Curve to a Scene Example::
23         from Blender import Curve, Object, Scene
24         cu = Curve.New()             # create new  curve data
25         scn = Scene.GetCurrent()    # get current scene
26         ob = scn.objects.new(cu)     # make a new curve from the curve data
27
28 Iterator Example::
29         from Blender import Curve, Object, Scene
30         scn = Scene.GetCurrent()    # get current scene
31         ob = scn.objects.active
32         curvedata = ob.data
33         for curnurb in curvedata:
34                 print type( curnurb ), curnurb
35                 for point in curnurb:
36                         print type( point ), point
37
38 Creating a Curve from a list of Vec triples Examples::
39         from Blender import *
40         def bezList2Curve(bezier_vecs):
41                 '''
42                 Take a list or vector triples and converts them into a bezier curve object
43                 '''
44                 
45                 def bezFromVecs(vecs):
46                         '''
47                         Bezier triple from 3 vecs, shortcut functon
48                         '''
49                         bt= BezTriple.New(\
50                         vecs[0].x, vecs[0].y, vecs[0].z,\
51                         vecs[1].x, vecs[1].y, vecs[1].z,\
52                         vecs[2].x, vecs[2].y, vecs[2].z)
53                         
54                         bt.handleTypes= (BezTriple.HandleTypes.FREE, BezTriple.HandleTypes.FREE)
55                         
56                         return bt
57                 
58                 # Create the curve data with one point
59                 cu= Curve.New()
60                 cu.appendNurb(bezFromVecs(bezier_vecs[0])) # We must add with a point to start with
61                 cu_nurb= cu[0] # Get the first curve just added in the CurveData
62                 
63                 
64                 i= 1 # skip first vec triple because it was used to init the curve
65                 while i<len(bezier_vecs):
66                         bt_vec_triple= bezier_vecs[i]
67                         bt= bezFromVecs(bt_vec_triple)
68                         cu_nurb.append(bt)
69                         i+=1
70                 
71                 # Add the Curve into the scene
72                 scn= Scene.GetCurrent()
73                 ob = scn.objects.new(cu)
74                 return ob
75 """
76
77 def New ( name):
78                 """
79         Create a new Curve Data object.
80         @type name: string
81         @param name: The Curve Data name.
82         @rtype: Blender Curve
83         @return: The created Curve Data object.
84         """
85
86 def Get (name = None):
87         """
88         Get the Curve Data object(s) from Blender.
89         @type name: string
90         @param name: The name of the Curve Data.
91         @rtype: Blender Curve or a list of Blender Curves
92         @return: It depends on the 'name' parameter:
93                                 - (name): The Curve Data object with the given name;
94                                 - ():     A list with all Curve Data objects in the current scene.
95         """
96
97 class Curve:
98         """
99         The Curve Data object
100         =====================
101         This object gives access to Curve and Surface data linked from Blender Objects.
102         
103         @ivar name: The Curve Data name.
104         @type name: string
105         @ivar pathlen: The Curve Data path length, used to set the number of frames for an animation (not the physical length).
106         @type pathlen: int
107         @ivar totcol: The Curve Data maximal number of linked materials. Read-only.
108         @type totcol: int
109         @ivar flag: The Curve Data flag value; see L{getFlag()} for the semantics.
110         @ivar bevresol: The Curve Data bevel resolution. [0 - 32]
111         @type bevresol: int
112         @ivar resolu: The Curve Data U-resolution (used for curve and surface resolution) [0 - 1024].
113         @type resolu: int
114         @ivar resolv: The Curve Data V-resolution (used for surface resolution) [0 - 1024].
115         @type resolv: int
116         @ivar width: The Curve Data width [0 - 2].
117         @type width: float
118         @ivar ext1: The Curve Data extent1 (for bevels).
119         @type ext1: float
120         @ivar ext2: The Curve Data extent2 (for bevels).
121         @type ext2: float
122         @ivar loc: The Curve Data location(from the center).
123         @type loc: list of 3 floats
124         @ivar rot: The Curve Data rotation(from the center).
125         @type rot: list of 3 floats
126         @ivar size: The Curve Data size(from the center).
127         @type size: list of 3 floats
128         @ivar bevob: The Curve Bevel Object
129         @type bevob: Blender L{Object<Object.Object>} or None
130         @ivar key: The Key object associated with this Curve, if any.
131         @type key: Blender L{Key<Key.Key>}
132         @ivar materials: The curves's materials.  Each curve can reference up to
133                 16 materials.  Empty slots in the curve's list are represented by B{None}.
134                 B{Note}: L{Object.colbits<Object.Object.colbits>} needs to be set correctly
135                 for each object in order for these materials to be used instead of
136                 the object's materials.
137                 B{Note}: The list that's returned is I{not} linked to the original curve.
138                 curve.materials.append(material) won't do anything.
139                 Use curve.materials += [material] instead.
140         @type materials: list of L{Material}s
141         """
142
143         def getName():
144                 """
145                 Get the name of this Curve Data object.
146                 @rtype: string
147                 """
148
149         def setName(name):
150                 """
151                 Set the name of this Curve Data object.
152                 @rtype: None
153                 @type name: string
154                 @param name: The new name.
155                 """
156
157         def getPathLen():
158                 """
159                 Get this Curve's path frame length, used for an animated path.
160                 @rtype: int
161                 @return: the path length.
162                 """
163
164         def setPathLen(len):
165                 """
166                 Set this Curve's path length.
167                 @rtype: None
168                 @type len: int
169                 @param len: the new curve's length.
170                 """
171
172         def getTotcol():
173                 """
174                 Get the number of materials linked to the Curve.
175                 @rtype: int
176                 @return: number of materials linked.
177                 """
178
179         def setTotcol(totcol):
180                 """
181                 Set the number of materials linked to the Curve.  B{Note}: this method
182                 will probably be deprecated in the future.
183                 @rtype: None
184                 @type totcol: int
185                 @param totcol: number of materials linked.
186                 @warn: It is not advisable to use this method unless you know what you
187                 are doing; it's possible to
188                 corrupt a .blend file if you don't know what you're doing.  If you want
189                 to change the number of materials, use the L{materials} attribute.
190                 """
191
192         def getFlag():
193                 """
194                 Get the Curve flag value.   
195                 This item is a bitfield whose value is a combination of the following parameters.
196                         - Bit 0 :  "3D" is set
197                         - Bit 1 :  "Front" is set
198                         - Bit 2 :  "Back" is set
199                         - Bit 3 :  "CurvePath" is set.
200                         - Bit 4 :  "CurveFollow" is set.
201                         
202                 @rtype: integer bitfield
203                 """
204
205         def setFlag(val):
206                 """
207                 Set the Curve flag value.  The flag corresponds to the Blender settings for 3D, Front, Back, CurvePath and CurveFollow.  This parameter is a bitfield.
208                 @rtype: None
209                 @type val: integer bitfield
210                 @param val : The Curve's flag bits.  See L{getFlag} for the meaning of the individual bits.
211                 """
212
213         def getBevresol():
214                 """
215                 Get the Curve's bevel resolution value.
216                 @rtype: float
217                 """
218
219         def setBevresol(bevelresol):
220                 """
221                 Set the Curve's bevel resolution value.
222                 @rtype: None
223                 @type bevelresol: float
224                 @param bevelresol: The new Curve's bevel resolution value.
225                 """
226
227         def getResolu():
228                 """
229                 Get the Curve's U-resolution value.
230                 @rtype: float
231                 """
232
233         def setResolu(resolu):
234                 """
235                 Set the Curve's U-resolution value. [0 - 1024]
236                 This is used for surfaces and curves.
237                 @rtype: None
238                 @type resolu: float
239                 @param resolu: The new Curve's U-resolution value.
240                 """
241
242         def getResolv():
243                 """
244                 Get the Curve's V-resolution value.
245                 @rtype: float
246                 """
247
248         def setResolv(resolv):
249                 """
250                 Set the Curve's V-resolution value. [0 - 1024].
251                 This is used for surfaces only.
252                 @rtype: None
253                 @type resolv: float
254                 @param resolv: The new Curve's V-resolution value.
255                 """
256
257         def getWidth():
258                 """
259                 Get the Curve's width value.
260                 @rtype: float
261                 """
262
263         def setWidth(width):
264                 """
265                 Set the Curve's width value. 
266                 @rtype: None
267                 @type width: float
268                 @param width: The new Curve's width value. 
269                 """
270
271         def getExt1():
272                 """
273                 Get the Curve's ext1 value.
274                 @rtype: float
275                 """
276
277         def setExt1(ext1):
278                 """
279                 Set the Curve's ext1 value. 
280                 @rtype: None
281                 @type ext1: float
282                 @param ext1: The new Curve's ext1 value. 
283                 """
284
285         def getExt2():
286                 """
287                 Get the Curve's ext2 value.
288                 @rtype: float
289                 """
290
291         def setExt2(ext2):
292                 """
293                 Set the Curve's ext2 value.
294                 @rtype: None 
295                 @type ext2: float
296                 @param ext2: The new Curve's ext2 value. 
297                 """
298
299         def getControlPoint(numcurve,numpoint):
300                 """
301                 Get the curve's control point value (B{deprecated}).  The numpoint arg
302                 is an index into the list of points and starts with 0.  B{Note}: new
303                 scripts should use the [] operator on Curves and CurNurbs.  Example::
304                         curve = Blender.Curve.Get('Curve')
305                         p0 = curve[0][0]    # get first point from first nurb
306                                                 # -- OR --
307                         nurb = curve[0]     # get first nurb
308                         p0 = nurb[0]        # get nurb's first point
309
310                 @type numcurve: int
311                 @type numpoint: int
312                 @rtype: list of floats
313                 @return: depends upon the curve's type.
314                         - type Bezier : a list of nine floats.  Values are x, y, z for handle-1, vertex and handle-2 
315                         - type Nurb : a list of 4 floats.  Values are x, y, z, w.
316
317                 """
318
319         def setControlPoint( numcurve, numpoint, controlpoint):
320                 """
321                 Set the Curve's controlpoint value.   The numpoint arg is an index into the list of points and starts with 0.
322                 @rtype: None
323                 @type numcurve: int
324                 @type numpoint: int
325                 @type controlpoint: list
326                 @param numcurve: index for spline in Curve, starting from 0
327                 @param numpoint: index for point in spline, starting from 0
328                 @param controlpoint: The new controlpoint value.
329                 See L{getControlPoint} for the length of the list.
330                 """
331
332         def appendPoint( numcurve, new_control_point ):
333                 """
334                 Add a new control point to the indicated curve (B{deprecated}).
335                 New scripts should use L{CurNurb.append()}.
336                 @rtype: None
337                 @type numcurve: int
338                 @type new_control_point: list of floats or BezTriple
339                 @param numcurve:  index for spline in Curve, starting from 0
340                 @param new_control_point: depends on curve's type.
341                         - type Bezier: a BezTriple 
342                         - type Nurb: a list of four or five floats for the xyzw values
343                 @raise AttributeError:  throws exception if numcurve is out of range.
344                 """
345
346         def appendNurb( new_point ):
347                 """
348                 add a new curve to this Curve.  The new point is added to the new curve.  Blender does not support a curve with zero points.  The new curve is added to the end of the list of curves in the Curve.
349                 @rtype: CurNurb
350                 @return: the newly added spline
351                 @type new_point: BezTriple or list of xyzw coordinates for a Nurb curve.
352                 @param new_point: see L{CurNurb.append} for description of parameter.
353                 """
354
355         def getLoc():
356                 """
357                 Get the curve's location value.
358                 @rtype: a list of 3 floats.
359                 """
360
361         def setLoc(location):
362                 """
363                 Set the curve's location value.
364                 @rtype: None 
365                 @type location: list[3]
366                 @param location: The new Curve's location values. 
367                 """
368
369         def getRot():
370                 """
371                 Get the curve's rotation value.
372                 @rtype: a list of 3 floats.
373                 """
374
375         def setRot(rotation):
376                 """
377                 Set the Curve's rotation value. 
378                 @rtype: None
379                 @type rotation: list[3]
380                 @param rotation: The new Curve's rotation values. 
381                 """
382
383         def getSize():
384                 """
385                 Get the curve's size value.
386                 @rtype: a list of 3 floats.
387                 """
388
389         def setSize(size):
390                 """
391                 Set the curve size value.
392                 @rtype: None 
393                 @type size: list[3]
394                 @param size: The new Curve's size values. 
395                 """
396
397         def getMaterials():
398                 """
399                 Returns a list of materials assigned to the Curve.
400                 @rtype: list of Material Objects
401                 @return: list of Material Objects assigned to the Curve.
402                 """
403
404         def getBevOb():
405                 """
406                 Returns the Bevel Object (BevOb) assigned to the Curve.
407                 @rtype: Blender Object or None
408                 @return: Bevel Object (BevOb) assigned to the Curve.
409                 """
410
411         def setBevOb( object ):
412                 """
413                 Assign a Bevel Object (BevOb) to the Curve.  Passing None as the object parameter removes the bevel.
414                 @rtype: None
415                 @return: None
416                 @type object: Curve type Blender Object
417                 @param object: Blender Object to assign as Bevel Object (BevOb)
418                 @raise TypeError: throws exception if the parameter is not a Curve type Blender Object or None
419                 """
420
421         def getTaperOb():
422                 """
423                 Returns the Taper Object (TaperOb) assigned to the Curve.
424                 @rtype: Blender Object or None
425                 @return: Taper Object (TaperOb) assigned to the Curve.
426                 """
427
428         def setTaperOb( object ):
429                 """
430                 Assign a Taper Object (TaperOb) to the Curve.  Passing None as the object parameter removes the taper.
431                 @rtype: None
432                 @return: None
433                 @type object: Curve type Blender Object
434                 @param object: Blender Object to assign as Taper Object (TaperOb)
435                 @raise TypeError: throws exception if the parameter is not a Curve type Blender Object or None
436                 """
437
438         def update():
439                 """
440                 Updates display list for a Curve.
441                 Used after making changes to control points.
442                 You B{must} use this if you want to see your changes!
443                 @rtype: None
444                 @return: None
445                 """
446
447         def isNurb( curve_num ):
448                 """
449                 Tells type of a CurNurb (B{deprecated}).
450                 New scripts should use L{CurNurb.isNurb()}.
451
452                 @rtype: integer
453                 @return:  Zero if curve is type Bezier, one if curve is of type Nurb.
454                 @type curve_num: integer
455                 @param curve_num: zero-based index into list of curves in this Curve.
456                 @raise AttributeError:  throws exception if curve_num is out of range.
457                 """
458
459         def isCyclic( curve_num ):
460                 """
461                 Tells whether or not a CurNurb is cyclic (closed) (B{deprecated}).
462                 New scripts should use L{CurNurb.isCyclic()}.
463
464                 @rtype: boolean
465                 @return: True if is cyclic, False if not
466                 @type curve_num: integer
467                 @param curve_num: zero-based index into list of curves in this Curve
468                 @raise AttributeError:  throws exception if curve_num is out of range.
469                 """
470
471         def switchDirection( ):
472                 """
473                 Reverse the direction of a curve.
474                 @return: None
475
476                 I{B{Example:}}
477                 # This example switches the direction of all curves on the active object.
478                 from Blender import *
479                 scn = Scene.GetCurrent()
480                 ob = scn.objects.active # must be a curve
481                 data = ob.data
482                 for cu in data: cu.switchDirection()
483                 """
484
485         def getNumCurves():
486                 """
487                 Get the number of curves in this Curve Data object.
488                 @rtype: integer
489                 """
490
491         def getNumPoints( curve_num ):
492                 """
493                 Get the number of control points in the curve (B{deprecated}).
494                 New scripts should use the len operator (I{len(curve)}).
495                 @type curve_num: integer
496                 @param curve_num: zero-based index into list of curves in this Curve
497                 @rtype: integer
498                 """
499
500         def getKey():
501                 """
502                 Return the L{Key<Key.Key>} object containing the keyframes for this
503                 curve, if any.
504                 @rtype: L{Key<Key.Key>} object or None
505                 """
506
507         def recalc():
508                 """
509                 Recalculate control point handles after a curve has been changed.
510                 @rtype: None
511                 """
512
513         def __copy__ ():
514                 """
515                 Make a copy of this curve
516                 @rtype: Curve
517                 @return:  a copy of this curve
518                 """
519
520 class CurNurb:
521         """
522         The CurNurb Object
523         ==================
524         This object provides access to the control points of the curves that make up a Blender Curve ObData.
525
526         The CurNurb supports the python iterator protocol which means you can use a python for statement to access the points in a curve.
527
528         The CurNurb also supports the sequence protocol which means you can access the control points of a CurNurb using the [] operator.
529
530         Note that CurNurb is used for accesing poly, bezier and nurbs type curves.
531
532         @ivar flagU: The CurNurb knot flag U.  See L{setFlagU} for description.
533         @type flagU: int
534         @ivar flagV: The CurNurb knot flag V.  See L{setFlagU} for description.
535         @type flagV: int
536         @ivar type: The type of the curve (Poly: 0, Bezier: 1, NURBS: 4)
537         @type type: int
538         """
539
540         def __setitem__( n, point ):
541                 """
542                 Replace the Nth point in the curve. The type of the argument must match the type of the curve. List of 4 floats (optional 5th float is the tilt value in radians) for Nurbs or BezTriple for Bezier.
543                 @rtype: None
544                 @return: None
545                 @type n: integer
546                 @param n: the index of the element to replace
547                 @type point: BezTriple or list of 4 floats (optional 5th float is the tilt value in radians)
548                 @param point: the point that will replace the one in the curve.  The point can be either a BezTriple type or a list of 4 floats in x,y,z,w (optionally tilt in radians as 5th value) format for a Nurb curve.
549                 """
550
551         def __getitem__( n ):
552                 """
553                 Get the Nth element in the curve. For Bezier curves, that element is a BezTriple. For the rest (Poly and Nurbs), it is a list of 5 floats: x, y, z, weight, tilt (in radians). NOTE 1: This element is independent on the curve, modifying it will not affect the curve. NOTE 2: Each successive call returns a new object.
554                 @rtype: BezTriple (Bezier Curve) or List of 5 floats [x, y, z, w, t] for Poly or Nurbs
555                 @return: The Nth element in the curve
556                 @type n: integer
557                 @param n: the index of the element to return
558                 """
559
560         def append( new_point ):
561                 """
562                 Appends a new point to a curve.  This method appends points to both Bezier and Nurb curves. The type of the argument must match the type of the curve. List of 4 floats (optional 5th float is the tilt value in radians) for Nurbs or BezTriple for Bezier.
563                 @rtype: None
564                 @return: None
565                 @type new_point: BezTriple or list of 4 floats (optional 5th float is the tilt value in radians)
566                 @param new_point: the new point to be appended to the curve.  The new point can be either a BezTriple type or a list of 4 floats in x,y,z,w (optionally tilt in radians as 5th value) format for a Nurb curve.
567                 """
568
569         def setMatIndex( index ):
570                 """
571                 Sets the Material index for this CurNurb.
572                 @rtype: None
573                 @return: None
574                 @type index:  integer
575                 @param index: the new value for the Material number of this CurNurb.  No range checking is done.
576                 """
577
578         def getMatIndex():
579                 """
580                 Returns the Material index for this CurNurb.
581                 @rtype: integer
582                 @return: integer
583                 """
584
585         def isNurb():
586                 """
587                 Boolean method used to determine whether a CurNurb is of type Bezier or of type Nurb.
588                 @rtype: boolean
589                 @return:  True or False
590                 """
591
592         def isCyclic():
593                 """
594                 Boolean method checks whether a CurNurb is cyclic (a closed curve) or not.
595                 @rtype: boolean
596                 @return: True or False
597                 """
598
599         def getFlagU():
600                 """
601                 Get the CurNurb knot flag U.  
602                 @rtype: integer
603                 @return: See L{setFlagU} for description of return value.
604                 """
605
606         def setFlagU( flag ):
607                 """
608                 Set the entire CurNurb knot flag U (knots are recalculated automatically).
609                 The flag can be one of six values:
610                                  - 0 or 1: uniform knots
611                                  - 2 or 3: endpoints knots
612                                  - 4 or 5: bezier knots
613                 Bit 0 controls whether or not the curve is cyclic (1 = cyclic).
614                 @type flag: integer
615                 @param flag: CurNurb knot flag
616                 @rtype: None
617                 @return: None
618                 """
619
620         def getFlagV():
621                 """
622                 Get the CurNurb knot flag V.
623                 @rtype: integer
624                 @return: See L{setFlagU} for description of return value.
625                 """
626
627         def setFlagV( value ):
628                 """
629                 Set the CurNurb knot flag V (knots are recalculated automatically).
630                 @type value: integer
631                 @param value: See L{setFlagU} for description of return.
632                 @rtype: None
633                 @return: None
634                 """
635
636         def getType():
637                 """
638                 Get the type of the curve.
639                 @rtype: integer
640                 @return:  0 - Poly, 1 - Bezier, 4 - NURBS
641                 """
642
643         def setType( value ):
644                 """
645                 Set the type of the curve and converts the curve to its new type if needed
646                 @type value: integer
647                 @param value: CurNurb type flag (0 - Poly, 1 - Bezier, 4 - NURBS)
648                 @rtype: None
649                 @return: None
650                 """
651
652 class SurfNurb:
653         """
654         The SurfNurb Object
655         ===================
656         This object provides access to the control points of the surfaces that make
657         up a Blender Curve.
658
659         The SurfNurb supports the Python iterator and sequence protocols which
660         means you can use a python B{for} statement or [] operator to access the
661         points in a surface.  Points are accessed linearly; for a N-by-M UV surface,
662         the first N control points correspond to V=0, then second N to V=1, and so
663         on.
664
665         @ivar flagU: The knot flag U.  Changing the knot type automatically
666         recalculates the knots.  The flag can be one of three values:
667                                          - 0 : uniform knots
668                                          - 1 : endpoints knots
669                                          - 2 : bezier knots
670         @type flagU: int
671         @ivar flagV: The knot flag V.  See L{flagU} for description.
672         @type flagV: int
673         @ivar pointsU: The number of control points in the U direction (read only).
674         @type pointsU: int
675         @ivar pointsV: The number of control points in the V direction (read only).
676         @type pointsV: int
677         @ivar cyclicU: The cyclic setting for the U direction (True = cyclic).
678         @type cyclicU: boolean
679         @ivar cyclicV: The cyclic setting for the V direction (True = cyclic).
680         @type cyclicV: boolean
681         @ivar orderU: The order setting for the U direction.  Values are clamped
682         to the range [2:6] and not greater than the U dimension.
683         @type orderU: int
684         @ivar orderV: The order setting for the V direction.  Values are clamped
685         to the range [2:6] and not greater than the V dimension.
686         @type orderV: int
687         """
688
689         def __setitem__( n, point ):
690                 """
691                 Set the Nth control point in the surface. 
692                 @rtype: None
693                 @return: None
694                 @type n: integer
695                 @param n: the index of the point to replace
696                 @type point: list of 4 floats (optional 5th float is the tilt value
697                 in radians)
698                 @param point: the point that will replace the one in the curve.  The
699                 point is  list of 4 floats in x,y,z,w (optionally tilt in radians as
700                 5th value) format.
701                 """
702
703         def __getitem__( n ):
704                 """
705                 Get the Nth control point in the surface. 
706                 @rtype: List of 5 floats [x, y, z, w, t] for Poly or Nurbs
707                 @return: The Nth point in the curve
708                 @type n: integer
709                 @param n: the index of the point to return
710                 @note: This returned value is independent on the curve; modifying it will not affect the curve. 
711                 @note: Each successive call returns a new object.
712                 """
713