← Back to branch summary

~siretart/ubuntu/utopic/blender/libav10

« back to all changes in this revision

Viewing changes to source/blender/python/api2_2x/doc/Curve.py

Tags: upstream-2.43
Import upstream version 2.43

Show diffs side-by-side

added added

removed removed

Lines of Context:
source/blender/python/api2_2x/doc/Curve.py
8
8
 
9
9
This module provides access to B{Curve Data} objects in Blender.
10
10
 
11
 
A Blender Curve can consist of multiple curves. 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 curves can be accessed with
13
 
the [] operator.  Operator [] returns an object of type CurNurb.
 
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)
14
16
 
15
17
The Curve module also supports the Python iterator interface.  This means you
16
 
can access the curves in a Curve and the control points in a CurNurb using a
 
18
can access the L{CurNurb}(s) in a Curve and the control points in a L{CurNurb} using a
17
19
Python B{for} statement.
18
20
 
19
21
 
20
22
Add a Curve to a Scene Example::
21
23
  from Blender import Curve, Object, Scene
22
 
  c = Curve.New()             # create new  curve data
23
 
  cur = Scene.getCurrent()    # get current scene
24
 
  ob = Object.New('Curve')    # make curve object
25
 
  ob.link(c)                  # link curve data with this object
26
 
  cur.link(ob)                # link object into 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
27
 
28
28
Iterator Example::
29
 
  ob = Object.GetSelected()[0]
30
 
  curve = ob.getData()
31
 
  for cur in curve:
32
 
    print type( cur ), cur
33
 
    for point in cur:
 
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:
34
36
      print type( point ), point
35
37
 
36
 
 
 
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
37
75
"""
38
76
 
39
77
def New ( name):
60
98
  """
61
99
  The Curve Data object
62
100
  =====================
63
 
  This object gives access to Curve-specific data in Blender.
 
101
  This object gives access to Curve and Surface data linked from Blender Objects.
64
102
  
65
103
  @ivar name: The Curve Data name.
66
104
  @type name: string
67
 
  @ivar pathlen: The Curve Data path length.
 
105
  @ivar pathlen: The Curve Data path length, used to set the number of frames for an animation (not the physical length).
68
106
  @type pathlen: int
69
 
  @ivar totcol: The Curve Data maximal number of linked materials.
 
107
  @ivar totcol: The Curve Data maximal number of linked materials. Read-only.
70
108
  @type totcol: int
71
109
  @ivar flag: The Curve Data flag value; see L{getFlag()} for the semantics.
72
 
  @ivar bevresol: The Curve Data bevel resolution.
73
 
  @type bevresol: float
74
 
  @ivar resolu: The Curve Data U-resolution.
75
 
  @type resolu: float
76
 
  @ivar resolv: The Curve Data V-resolution.
77
 
  @type resolv: float
78
 
  @ivar width: The Curve Data width.
 
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].
79
117
  @type width: float
80
 
  @ivar ext1: The Curve Data extent 1(for bevels).
 
118
  @ivar ext1: The Curve Data extent1 (for bevels).
81
119
  @type ext1: float
82
120
  @ivar ext2: The Curve Data extent2 (for bevels).
83
121
  @type ext2: float
91
129
  @type bevob: Blender L{Object<Object.Object>} or None
92
130
  @ivar key: The Key object associated with this Curve, if any.
93
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
94
141
  """
95
142
 
96
143
  def getName():
109
156
 
110
157
  def getPathLen():
111
158
    """
112
 
    Get this Curve's path length.
 
159
    Get this Curve's path frame length, used for an animated path.
113
160
    @rtype: int
114
161
    @return: the path length.
115
162
    """
131
178
 
132
179
  def setTotcol(totcol):
133
180
    """
134
 
    Set the number of materials linked to the Curve.
 
181
    Set the number of materials linked to the Curve.  B{Note}: this method
 
182
    will probably be deprecated in the future.
135
183
    @rtype: None
136
184
    @type totcol: int
137
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.
138
190
    """
139
191
 
140
192
  def getFlag():
180
232
 
181
233
  def setResolu(resolu):
182
234
    """
183
 
    Set the Curve's U-resolution value.
 
235
    Set the Curve's U-resolution value. [0 - 1024]
 
236
    This is used for surfaces and curves.
184
237
    @rtype: None
185
238
    @type resolu: float
186
239
    @param resolu: The new Curve's U-resolution value.
194
247
 
195
248
  def setResolv(resolv):
196
249
    """
197
 
    Set the Curve's V-resolution value.
 
250
    Set the Curve's V-resolution value. [0 - 1024].
 
251
    This is used for surfaces only.
198
252
    @rtype: None
199
253
    @type resolv: float
200
254
    @param resolv: The new Curve's V-resolution value.
414
468
      @raise AttributeError:  throws exception if curve_num is out of range.
415
469
      """
416
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
 
417
485
  def getNumCurves():
418
486
      """
419
487
      Get the number of curves in this Curve Data object.
436
504
      @rtype: L{Key<Key.Key>} object or None
437
505
      """
438
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
    """
439
519
 
440
520
class CurNurb:
441
521
    """
442
522
    The CurNurb Object
443
523
    ==================
444
 
    This object provides access to the control points of the curves that make up a Blender Curve.
 
524
    This object provides access to the control points of the curves that make up a Blender Curve ObData.
445
525
 
446
526
    The CurNurb supports the python iterator protocol which means you can use a python for statement to access the points in a curve.
447
527
 
448
528
    The CurNurb also supports the sequence protocol which means you can access the control points of a CurNurb using the [] operator.
449
529
 
 
530
    Note that CurNurb is used for accesing poly, bezier and nurbs type curves.
 
531
 
450
532
    @ivar flagU: The CurNurb knot flag U.  See L{setFlagU} for description.
451
533
    @type flagU: int
452
534
    @ivar flagV: The CurNurb knot flag V.  See L{setFlagU} for description.
454
536
    @ivar type: The type of the curve (Poly: 0, Bezier: 1, NURBS: 4)
455
537
    @type type: int
456
538
    """
457
 
        
 
539
 
458
540
    def __setitem__( n, point ):
459
541
      """
460
 
          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.
 
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.
461
543
      @rtype: None
462
544
      @return: None
463
545
      @type n: integer
468
550
 
469
551
    def __getitem__( n ):
470
552
      """
471
 
          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 element is independant on the curve, modifying it will not affect the curve. NOTE 2: Each successive call returns a new object.
 
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.
472
554
      @rtype: BezTriple (Bezier Curve) or List of 5 floats [x, y, z, w, t] for Poly or Nurbs
473
555
      @return: The Nth element in the curve
474
556
      @type n: integer
512
594
      Boolean method checks whether a CurNurb is cyclic (a closed curve) or not.
513
595
      @rtype: boolean
514
596
      @return: True or False
515
 
          """
 
597
      """
516
598
 
517
599
    def getFlagU():
518
600
      """
566
648
      @rtype: None
567
649
      @return: None
568
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