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