cc1b1647d50a1842c189ce60fb4306e087cade1e
[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