0022939: Make B-Spline internal cache thread-safe to be used in multy-threaded mode
[occt.git] / src / Geom2d / Geom2d_BSplineCurve.cdl
1 -- Created on: 1993-03-24
2 -- Created by: JCV
3 -- Copyright (c) 1993-1999 Matra Datavision
4 -- Copyright (c) 1999-2012 OPEN CASCADE SAS
5 --
6 -- The content of this file is subject to the Open CASCADE Technology Public
7 -- License Version 6.5 (the "License"). You may not use the content of this file
8 -- except in compliance with the License. Please obtain a copy of the License
9 -- at http://www.opencascade.org and read it completely before using this file.
10 --
11 -- The Initial Developer of the Original Code is Open CASCADE S.A.S., having its
12 -- main offices at: 1, place des Freres Montgolfier, 78280 Guyancourt, France.
13 --
14 -- The Original Code and all software distributed under the License is
15 -- distributed on an "AS IS" basis, without warranty of any kind, and the
16 -- Initial Developer hereby disclaims all such warranties, including without
17 -- limitation, any warranties of merchantability, fitness for a particular
18 -- purpose or non-infringement. Please see the License for the specific terms
19 -- and conditions governing the rights and limitations under the License.
20
21
22 -- xab : modified 15-Mar-95 : added cache mecanism to speed up
23 -- evaluation
24
25
26 class BSplineCurve from Geom2d inherits BoundedCurve from Geom2d
27
28         --- Purpose : Describes a BSpline curve.
29         -- A BSpline curve can be:
30         -- - uniform or non-uniform,
31         -- - rational or non-rational,
32         -- - periodic or non-periodic.
33         -- A BSpline curve is defined by:
34         -- - its degree; the degree for a
35         --   Geom2d_BSplineCurve is limited to a value (25)
36         --   which is defined and controlled by the system. This
37         --   value is returned by the function MaxDegree;
38         -- - its periodic or non-periodic nature;
39         -- - a table of poles (also called control points), with
40         --   their associated weights if the BSpline curve is
41         --   rational. The poles of the curve are "control points"
42         --   used to deform the curve. If the curve is
43         --   non-periodic, the first pole is the start point of the
44         --   curve, and the last pole is the end point of the
45         --   curve. The segment, which joins the first pole to the
46         --   second pole, is the tangent to the curve at its start
47         --   point, and the segment, which joins the last pole to
48         --   the second-from-last pole, is the tangent to the
49         --   curve at its end point. If the curve is periodic, these
50         --   geometric properties are not verified. It is more
51         --   difficult to give a geometric signification to the
52         --   weights but they are useful for providing exact
53         --   representations of the arcs of a circle or ellipse.
54         --   Moreover, if the weights of all the poles are equal,
55         --   the curve has a polynomial equation; it is
56         --   therefore a non-rational curve.
57         -- - a table of knots with their multiplicities. For a
58         --   Geom2d_BSplineCurve, the table of knots is an
59         --   increasing sequence of reals without repetition; the
60         --   multiplicities define the repetition of the knots. A
61         --   BSpline curve is a piecewise polynomial or rational
62         --   curve. The knots are the parameters of junction
63         --   points between two pieces. The multiplicity
64         --   Mult(i) of the knot Knot(i) of the BSpline
65         --   curve is related to the degree of continuity of the
66         --   curve at the knot Knot(i), which is equal to
67         --   Degree - Mult(i) where Degree is the
68         --   degree of the BSpline curve.
69         -- If the knots are regularly spaced (i.e. the difference
70         -- between two consecutive knots is a constant), three
71         -- specific and frequently used cases of knot distribution
72         -- can be identified:
73         -- - "uniform" if all multiplicities are equal to 1,
74         -- - "quasi-uniform" if all multiplicities are equal to 1,
75         --   except the first and the last knot which have a
76         --   multiplicity of Degree + 1, where Degree is
77         --   the degree of the BSpline curve,
78         -- - "Piecewise Bezier" if all multiplicities are equal to
79         --  Degree except the first and last knot which have
80         --   a multiplicity of Degree + 1, where Degree is
81         --   the degree of the BSpline curve. A curve of this
82         --   type is a concatenation of arcs of Bezier curves.
83         -- If the BSpline curve is not periodic:
84         -- - the bounds of the Poles and Weights tables are 1
85         --   and NbPoles, where NbPoles is the number of
86         --   poles of the BSpline curve,
87         -- - the bounds of the Knots and Multiplicities tables are
88         --   1 and NbKnots, where NbKnots is the number
89         --   of knots of the BSpline curve.
90         -- If the BSpline curve is periodic, and if there are k
91         -- periodic knots and p periodic poles, the period is:
92         -- period = Knot(k + 1) - Knot(1)
93         -- and the poles and knots tables can be considered as
94         -- infinite tables, such that:
95         -- - Knot(i+k) = Knot(i) + period
96         -- - Pole(i+p) = Pole(i)
97         -- Note: data structures of a periodic BSpline curve are
98         -- more complex than those of a non-periodic one.
99         -- Warnings :
100         --  In this class we consider that a weight value is zero if
101         --  Weight <= Resolution from package gp.
102         --  For two parametric values (or two knot values) U1, U2 we 
103         --  consider that U1 = U2 if Abs (U2 - U1) <= Epsilon (U1).
104         --  For two weights values W1, W2 we consider that W1 = W2 if
105         --  Abs (W2 - W1) <= Epsilon (W1).  The method Epsilon is
106         --  defined in the class Real from package Standard.
107         --  
108         -- References :
109         --  . A survey of curve and surface methods in CADG Wolfgang BOHM
110         --    CAGD 1 (1984)
111         --  . On de Boor-like algorithms and blossoming Wolfgang BOEHM
112         --    cagd 5 (1988)
113         --  . Blossoming and knot insertion algorithms for B-spline curves
114         --    Ronald N. GOLDMAN
115         --  . Modelisation des surfaces en CAO, Henri GIAUME Peugeot SA   
116         --  . Curves and Surfaces for Computer Aided Geometric Design,
117         --    a practical guide Gerald Farin
118
119
120 uses  Array1OfInteger      from TColStd,
121       Array1OfReal         from TColStd,
122       HArray1OfInteger     from TColStd,
123       HArray1OfReal        from TColStd,
124       Array1OfPnt2d        from TColgp,
125       Ax2d                 from gp, 
126       Pnt2d                from gp,
127       HArray1OfPnt2d       from TColgp,
128       Trsf2d               from gp,
129       Vec2d                from gp,
130       BSplKnotDistribution from GeomAbs,
131       Geometry             from Geom2d,
132       Shape                from GeomAbs,
133       Mutex                from Standard
134
135 raises ConstructionError   from Standard,
136        DimensionError      from Standard,
137        DomainError         from Standard,
138        OutOfRange          from Standard,
139        RangeError          from Standard,
140        NoSuchObject        from Standard,
141        UndefinedDerivative from Geom2d
142
143 is
144
145
146
147   Create (Poles          : Array1OfPnt2d   from TColgp; 
148           Knots          : Array1OfReal    from TColStd; 
149           Multiplicities : Array1OfInteger from TColStd; 
150           Degree         : Integer;
151           Periodic       : Boolean = Standard_False)
152           
153   returns mutable BSplineCurve from Geom2d
154
155         ---Purpose :  Creates a  non-rational B_spline curve   on  the
156         --         basis <Knots, Multiplicities> of degree <Degree>.
157         -- The following conditions must be verified.
158         --  0 < Degree <= MaxDegree.
159         --  
160         --  Knots.Length() == Mults.Length() >= 2
161         --  
162         --  Knots(i) < Knots(i+1) (Knots are increasing)
163         --  
164         --  1 <= Mults(i) <= Degree
165         --  
166         --   On a non periodic curve the first and last multiplicities
167         --   may be Degree+1 (this is even recommanded if you want the
168         --   curve to start and finish on the first and last pole).
169         --   
170         --   On a periodic  curve the first  and  the last multicities
171         --   must be the same.
172         --   
173         --   on non-periodic curves
174         --   
175         --     Poles.Length() == Sum(Mults(i)) - Degree - 1 >= 2
176         --     
177         --   on periodic curves 
178         --   
179         --     Poles.Length() == Sum(Mults(i)) except the first or last
180
181   raises ConstructionError;
182
183         
184
185   Create (Poles          : Array1OfPnt2d   from TColgp; 
186           Weights        : Array1OfReal    from TColStd;
187           Knots          : Array1OfReal    from TColStd; 
188           Multiplicities : Array1OfInteger from TColStd; 
189           Degree         : Integer;
190           Periodic       : Boolean = Standard_False)
191           
192   returns mutable BSplineCurve from Geom2d
193
194         ---Purpose : Creates  a rational B_spline  curve  on the basis
195         --         <Knots, Multiplicities> of degree <Degree>.
196         -- The following conditions must be verified.
197         --  0 < Degree <= MaxDegree.
198         --  
199         --  Knots.Length() == Mults.Length() >= 2
200         --  
201         --  Knots(i) < Knots(i+1) (Knots are increasing)
202         --  
203         --  1 <= Mults(i) <= Degree
204         --  
205         --   On a non periodic curve the first and last multiplicities
206         --   may be Degree+1 (this is even recommanded if you want the
207         --   curve to start and finish on the first and last pole).
208         --   
209         --   On a periodic  curve the first  and  the last multicities
210         --   must be the same.
211         --   
212         --   on non-periodic curves
213         --   
214         --     Poles.Length() == Sum(Mults(i)) - Degree - 1 >= 2
215         --     
216         --   on periodic curves 
217         --   
218         --     Poles.Length() == Sum(Mults(i)) except the first or last
219
220   raises ConstructionError;
221
222    
223   IncreaseDegree (me : mutable; Degree : Integer)
224   
225         ---Purpose: Increases the degree of this BSpline curve to
226         -- Degree. As a result, the poles, weights and
227         -- multiplicities tables are modified; the knots table is
228         -- not changed. Nothing is done if Degree is less than
229         -- or equal to the current degree.
230         -- Exceptions
231         -- Standard_ConstructionError if Degree is greater than
232         -- Geom2d_BSplineCurve::MaxDegree().
233   raises ConstructionError;
234        
235
236  IncreaseMultiplicity (me : mutable; Index : Integer; M : Integer)
237  
238         ---Purpose :Increases the multiplicity  of the knot <Index> to
239         --         <M>.   
240         --         
241         --         If   <M>   is   lower   or  equal   to  the current
242         --         multiplicity nothing is done. If <M> is higher than
243         --         the degree the degree is used.
244
245  raises OutOfRange;
246         
247         ---Purpose: If <Index> is not in [FirstUKnotIndex, LastUKnotIndex]
248
249
250   IncreaseMultiplicity (me : mutable; I1, I2 : Integer; M : Integer) 
251   
252         ---Purpose :Increases  the  multiplicities   of  the knots  in
253         --         [I1,I2] to <M>.
254         --         
255         --         For each knot if  <M>  is  lower  or equal  to  the
256         --         current multiplicity  nothing  is  done. If <M>  is
257         --         higher than the degree the degree is used.
258         -- As a result, the poles and weights tables of this curve are modified.
259         -- Warning
260         -- It is forbidden to modify the multiplicity of the first or
261         -- last knot of a non-periodic curve. Be careful as
262         -- Geom2d does not protect against this.
263         -- Exceptions
264         -- Standard_OutOfRange if either Index, I1 or I2 is
265         -- outside the bounds of the knots table.
266  raises OutOfRange;
267         
268
269   IncrementMultiplicity (me : mutable; I1, I2 : Integer; M : Integer) 
270   
271         ---Purpose : Increases by M the multiplicity of the knots of indexes
272         -- I1 to I2 in the knots table of this BSpline curve. For
273         -- each knot, the resulting multiplicity is limited to the
274         -- degree of this curve. If M is negative, nothing is done.
275         -- As a result, the poles and weights tables of this
276         -- BSpline curve are modified.
277         -- Warning
278         -- It is forbidden to modify the multiplicity of the first or
279         -- last knot of a non-periodic curve. Be careful as
280         -- Geom2d does not protect against this.
281         -- Exceptions
282         -- Standard_OutOfRange if I1 or I2 is outside the
283         -- bounds of the knots table.
284
285  raises OutOfRange;
286         
287
288   InsertKnot (me : mutable; 
289               U : Real; 
290               M : Integer = 1; 
291               ParametricTolerance : Real = 0.0); 
292   
293         ---Purpose: Inserts a knot value in the sequence of knots.  If
294         --          <U>  is an  existing knot     the multiplicity  is
295         --          increased by <M>.
296         --          
297         --          If U  is  not  on the parameter  range  nothing is
298         --          done.
299         --          
300         --          If the multiplicity is negative or null nothing is
301         --          done. The  new   multiplicity  is limited  to  the
302         --          degree.
303         --          
304         --          The  tolerance criterion  for  knots  equality  is
305         --          the max of Epsilon(U) and ParametricTolerance.
306         -- Warning
307         -- - If U is less than the first parameter or greater than
308         --   the last parameter of this BSpline curve, nothing is done.
309         -- - If M is negative or null, nothing is done.
310         -- - The multiplicity of a knot is limited to the degree of
311         --   this BSpline curve.
312   
313
314   InsertKnots (me : mutable; Knots : Array1OfReal    from TColStd; 
315                              Mults : Array1OfInteger from TColStd;
316                              ParametricTolerance : Real = 0.0;
317                              Add : Boolean = Standard_False);
318                              
319         ---Purpose: Inserts the values of the array Knots, with the
320         -- respective multiplicities given by the array Mults, into
321         -- the knots table of this BSpline curve.
322         -- If a value of the array Knots is an existing knot, its multiplicity is:
323         -- - increased by M, if Add is true, or
324         -- - increased to M, if Add is false (default value).
325         -- The tolerance criterion used for knot equality is the
326         -- larger of the values ParametricTolerance (defaulted
327         -- to 0.) and Standard_Real::Epsilon(U),
328         -- where U is the current knot value.
329         -- Warning
330         -- - For a value of the array Knots which is less than
331         --   the first parameter or greater than the last
332         --   parameter of this BSpline curve, nothing is done.
333         -- - For a value of the array Mults which is negative or
334         --   null, nothing is done.
335         -- - The multiplicity of a knot is limited to the degree of
336         --   this BSpline curve.
337                              
338
339
340   RemoveKnot(me : mutable; Index     : Integer; 
341                            M         : Integer;
342                            Tolerance : Real) returns Boolean
343                            
344         ---Purpose : Reduces the multiplicity of the knot of index Index
345         -- to M. If M is equal to 0, the knot is removed.
346         -- With a modification of this type, the array of poles is also modified.
347         -- Two different algorithms are systematically used to
348         -- compute the new poles of the curve. If, for each
349         -- pole, the distance between the pole calculated
350         -- using the first algorithm and the same pole
351         -- calculated using the second algorithm, is less than
352         -- Tolerance, this ensures that the curve is not
353         -- modified by more than Tolerance. Under these
354         -- conditions, true is returned; otherwise, false is returned.
355         -- A low tolerance is used to prevent modification of
356         -- the curve. A high tolerance is used to "smooth" the curve.
357         -- Exceptions
358         -- Standard_OutOfRange if Index is outside the
359         -- bounds of the knots table.
360      raises OutOfRange;
361      
362
363   InsertPoleAfter (me : mutable; Index : Integer; P : Pnt2d;
364                    Weight : Real = 1.0)
365         --- Purpose :
366         --  The new pole is inserted after the pole of range Index.
367         --  If the curve was non rational it can become rational.
368      raises ConstructionError,
369         --- Purpose :
370         --  Raised if the B-spline is NonUniform or PiecewiseBezier or if
371         --  Weight <= 0.0
372             OutOfRange;
373         --- Purpose : Raised if Index is not in the range [1, Number of Poles]
374
375
376   InsertPoleBefore (me : mutable; Index : Integer; P : Pnt2d; 
377                     Weight : Real  =  1.0)
378         --- Purpose :
379         --  The new pole is inserted before the pole of range Index.
380         --  If the curve was non rational it can become rational.
381      raises ConstructionError,
382         --- Purpose :
383         --  Raised if the B-spline is NonUniform or PiecewiseBezier or if
384         --  Weight <= 0.0
385             OutOfRange;
386         --- Purpose : Raised if Index is not in the range [1, Number of Poles]
387
388
389   RemovePole (me : mutable; Index : Integer)
390         --- Purpose :
391         --  Removes the pole of range Index
392         --  If the curve was rational it can become non rational.
393      raises ConstructionError,
394         --- Purpose :
395         --  Raised if the B-spline is NonUniform or PiecewiseBezier.
396         --  Raised if the number of poles of the B-spline curve is lower or 
397         --  equal to 2 before removing.
398             OutOfRange;
399         --- Purpose : Raised if Index is not in the range [1, Number of Poles]
400
401   Reverse (me : mutable);
402         --- Purpose : Reverses the orientation of this BSpline curve. As a result
403         -- - the knots and poles tables are modified;
404         -- - the start point of the initial curve becomes the end
405         --   point of the reversed curve;
406         -- - the end point of the initial curve becomes the start
407         --   point of the reversed curve.
408         
409
410   ReversedParameter(me; U : Real) returns Real;
411         ---Purpose: Computes the parameter on the reversed curve for
412         -- the point of parameter U on this BSpline curve.
413         -- The returned value is: UFirst + ULast - U,
414         -- where UFirst and ULast are the values of the
415         -- first and last parameters of this BSpline curve.
416
417
418   Segment (me : mutable; U1, U2 : Real)
419         ---Purpose : Modifies this BSpline curve by segmenting it
420         -- between U1 and U2. Either of these values can be
421         -- outside the bounds of the curve, but U2 must be greater than U1.
422         -- All data structure tables of this BSpline curve are
423         -- modified, but the knots located between U1 and U2
424         -- are retained. The degree of the curve is not modified.
425         -- Warnings :
426         --  Even if <me> is not closed it can become closed after the 
427         --  segmentation for example if U1 or U2 are out of the bounds 
428         --  of the curve <me> or if the curve makes loop.
429         --  After the segmentation the length of a curve can be null.
430         --        - The segmentation of a periodic curve over an
431         ---   interval corresponding to its period generates a
432         --  non-periodic curve with equivalent geometry.
433         --  Exceptions
434         -- Standard_DomainError if U2 is less than U1.
435     raises DomainError from Standard;
436         ---Purpose: raises if U2 < U1.
437
438
439   SetKnot (me : mutable; Index : Integer; K : Real)
440         --- Purpose :  Modifies this BSpline curve by assigning the value K
441         -- to the knot of index Index in the knots table. This is a
442         -- relatively local modification because K must be such that:
443         -- Knots(Index - 1) < K < Knots(Index + 1)
444         -- Exceptions
445         -- Standard_ConstructionError if:
446         -- - K is not such that:
447         -- Knots(Index - 1) < K < Knots(Index + 1)
448         -- - M is greater than the degree of this BSpline curve
449         --   or lower than the previous multiplicity of knot of
450         --   index Index in the knots table.
451         -- Standard_OutOfRange if Index is outside the bounds of the knots table.
452      raises ConstructionError,
453                     OutOfRange;
454
455
456   SetKnots (me : mutable; K : Array1OfReal from TColStd)
457         --- Purpose :  Modifies this BSpline curve by assigning the array
458         -- K to its knots table. The multiplicity of the knots is not modified.
459         -- Exceptions
460         -- Standard_ConstructionError if the values in the
461         -- array K are not in ascending order.
462         -- Standard_OutOfRange if the bounds of the array
463         -- K are not respectively 1 and the number of knots of this BSpline curve.
464      raises ConstructionError,
465                     OutOfRange;
466       
467
468   SetKnot (me : mutable; Index : Integer; K : Real; M : Integer)
469         --- Purpose : Modifies this BSpline curve by assigning the value K
470         -- to the knot of index Index in the knots table. This is a
471         -- relatively local modification because K must be such that:
472         -- Knots(Index - 1) < K < Knots(Index + 1)
473         -- The second syntax allows you also to increase the
474         -- multiplicity of the knot to M (but it is not possible to
475         -- decrease the multiplicity of the knot with this function).
476         -- Exceptions
477         -- Standard_ConstructionError if:
478         -- - K is not such that:
479         -- Knots(Index - 1) < K < Knots(Index + 1)
480         -- - M is greater than the degree of this BSpline curve
481         --   or lower than the previous multiplicity of knot of
482         --   index Index in the knots table.
483         -- Standard_OutOfRange if Index is outside the bounds of the knots table.
484      raises ConstructionError,
485                     OutOfRange;
486
487   PeriodicNormalization(me ;  U : in out Real) ; 
488        
489         ---Purpose : Computes the parameter normalized within the
490         -- "first" period of this BSpline curve, if it is periodic:
491         -- the returned value is in the range Param1 and
492         -- Param1 + Period, where:
493         -- - Param1 is the "first parameter", and
494         -- - Period the period of this BSpline curve.
495         --  Note: If this curve is not periodic, U is not modified.
496                  
497   SetPeriodic (me : mutable)
498         --- Purpose :Changes this BSpline curve into a periodic curve.
499         -- To become periodic, the curve must first be closed.
500         -- Next, the knot sequence must be periodic. For this,
501         -- FirstUKnotIndex and LastUKnotIndex are used to
502         -- compute I1 and I2, the indexes in the knots array
503         -- of the knots corresponding to the first and last
504         -- parameters of this BSpline curve.
505         -- The period is therefore Knot(I2) - Knot(I1).
506         -- Consequently, the knots and poles tables are modified.
507         -- Exceptions
508         -- Standard_ConstructionError if this BSpline curve is not closed.
509      raises ConstructionError;
510
511
512   SetOrigin (me : mutable; Index : Integer)
513         ---Purpose: Assigns the knot of index Index in the knots table as
514         -- the origin of this periodic BSpline curve. As a
515         -- consequence, the knots and poles tables are modified.
516         -- Exceptions
517         -- Standard_NoSuchObject if this curve is not periodic.
518         -- Standard_DomainError if Index is outside the
519         -- bounds of the knots table.
520     raises NoSuchObject,
521            DomainError;
522         
523
524   SetNotPeriodic (me : mutable);
525         --- Purpose : Changes this BSpline curve into a non-periodic
526         -- curve. If this curve is already non-periodic, it is not modified.
527         -- Note that the poles and knots tables are modified.
528         -- Warning
529         -- If this curve is periodic, as the multiplicity of the first
530         -- and last knots is not modified, and is not equal to
531         -- Degree + 1, where Degree is the degree of
532         -- this BSpline curve, the start and end points of the
533         -- curve are not its first and last poles.
534                 
535  
536   SetPole (me : mutable; Index : Integer; P : Pnt2d)
537         --- Purpose : Modifies this BSpline curve by assigning P to the
538         -- pole of index Index in the poles table.
539         -- Exceptions
540         -- Standard_OutOfRange if Index is outside the
541         -- bounds of the poles table.
542         -- Standard_ConstructionError if Weight is negative or null.
543      raises OutOfRange;
544       
545
546   SetPole (me : mutable; Index : Integer; P : Pnt2d; Weight : Real)
547         --- Purpose : Modifies this BSpline curve by assigning P to the
548         -- pole of index Index in the poles table.
549         -- The second syntax also allows you to modify the
550         -- weight of the modified pole, which becomes Weight.
551         -- In this case, if this BSpline curve is non-rational, it
552         -- can become rational and vice versa.
553         -- Exceptions
554         -- Standard_OutOfRange if Index is outside the
555         -- bounds of the poles table.
556         -- Standard_ConstructionError if Weight is negative or null.
557      raises OutOfRange,
558                   ConstructionError;
559         
560   SetWeight (me : mutable; Index : Integer; Weight : Real)
561         --- Purpose : Assigns the weight Weight to the pole of index Index of the poles table.
562         --  If the curve was non rational it can become rational.
563         --  If the curve was rational it can become non rational.
564         -- Exceptions
565         -- Standard_OutOfRange if Index is outside the
566         -- bounds of the poles table.
567         -- Standard_ConstructionError if Weight is negative or null.
568     raises OutOfRange,
569                   ConstructionError;
570
571   MovePoint (me : mutable; U: Real; P: Pnt2d; Index1, Index2: Integer;
572              FirstModifiedPole, LastModifiedPole: out Integer)
573         ---Purpose : Moves the point of parameter U of this BSpline
574         -- curve to P. Index1 and Index2 are the indexes in the
575         -- table of poles of this BSpline curve of the first and
576         -- last poles designated to be moved.
577         -- FirstModifiedPole and LastModifiedPole are the
578         -- indexes of the first and last poles, which are
579         -- effectively modified.
580         -- In the event of incompatibility between Index1,
581         -- Index2 and the value U:
582         -- - no change is made to this BSpline curve, and
583         -- - the FirstModifiedPole and LastModifiedPole are returned null.
584         -- Exceptions
585         -- Standard_OutOfRange if:
586         -- - Index1 is greater than or equal to Index2, or
587         -- - Index1 or Index2 is less than 1 or greater than the
588         --   number of poles of this BSpline curve.
589      raises OutOfRange;
590        
591
592     MovePointAndTangent (me : mutable; 
593                        U                 : Real; 
594                        P                 : Pnt2d; 
595                        Tangent           : Vec2d ;
596                        Tolerance         : Real ; 
597                        StartingCondition, 
598                        EndingCondition   : Integer; 
599                        ErrorStatus       : out Integer) 
600
601         ---Purpose : Move a point with parameter U to P.
602         -- and makes it tangent at U be Tangent.
603         -- StartingCondition = -1 means first can move
604         -- EndingCondition   = -1 means last point can move
605         -- StartingCondition = 0 means the first point cannot move
606         -- EndingCondition   = 0 means the last point cannot move
607         -- StartingCondition = 1 means the first point and tangent cannot move
608         -- EndingCondition   = 1 means the last point and tangent cannot move  
609         -- and so forth
610         -- ErrorStatus != 0 means that there are not enought degree of freedom
611         -- with the constrain to deform the curve accordingly
612         
613      raises OutOfRange;
614      
615     
616   IsCN (me; N : Integer)   returns Boolean
617         --- Purpose : Returns true if the degree of continuity of this
618         -- BSpline curve is at least N. A BSpline curve is at least GeomAbs_C0.
619         -- Exceptions Standard_RangeError if N is negative.
620           raises RangeError;
621       
622
623   IsClosed (me)  returns Boolean;
624         --- Purpose :
625         --  Returns true if the distance between the first point and the 
626         --  last point of the curve is lower or equal to Resolution 
627         --  from package gp.
628         --  Warnings :
629         --  The first and the last point can be different from the first
630         --  pole and the last pole of the curve.
631
632
633   IsPeriodic (me)  returns Boolean;
634         --- Purpose : Returns True if the curve is periodic.
635
636
637   IsRational (me)  returns Boolean;
638         --- Purpose :
639         --  Returns True if the weights are not identical.
640         --  The tolerance criterion is Epsilon of the class Real.
641     
642   IsCacheValid(me;  Parameter : Real) returns Boolean
643   
644         ---Purpose :
645         --           Tells whether the Cache is valid for the
646         --           given parameter 
647         -- Warnings : the parameter must be normalized within
648         -- the period if the curve is periodic. Otherwise
649         -- the answer will be false
650         -- 
651         is static private;
652   
653   Continuity (me)  returns Shape from GeomAbs;
654         --- Purpose :
655         --  Returns the global continuity of the curve :
656         --  C0 : only geometric continuity,
657         --  C1 : continuity of the first derivative all along the Curve,
658         --  C2 : continuity of the second derivative all along the Curve,
659         --  C3 : continuity of the third derivative all along the Curve,
660         --  CN : the order of continuity is infinite.
661         --  For a B-spline curve of degree d if a knot Ui has a
662         --  multiplicity p the B-spline curve is only Cd-p continuous 
663         --  at Ui. So the global continuity of the curve can't be greater 
664         --  than Cd-p where p is the maximum multiplicity of the interior
665         --  Knots. In the interior of a knot span the curve is infinitely
666         --  continuously differentiable.
667
668
669   Degree (me)  returns Integer;
670         --- Purpose : Returns the degree of this BSpline curve.
671         --  In this class the degree of the basis normalized B-spline
672         --  functions cannot be greater than "MaxDegree"
673
674
675         --- Purpose : Computation of value and derivatives
676
677   D0 (me; U : Real; P : out Pnt2d);
678
679
680   D1 (me; U : Real; P : out Pnt2d; V1 : out Vec2d)
681      raises UndefinedDerivative;
682         --- Purpose : Raised if the continuity of the curve is not C1.
683
684
685   D2 (me; U : Real; P : out Pnt2d; V1, V2 : out Vec2d)
686      raises UndefinedDerivative;
687         --- Purpose : Raised if the continuity of the curve is not C2.
688
689
690   D3 (me; U : Real; P : out Pnt2d; V1, V2, V3 : out Vec2d)
691      raises UndefinedDerivative;
692         --- Purpose:  For this BSpline curve, computes
693         -- - the point P of parameter U, or
694         -- - the point P and one or more of the following values:
695         --   - V1, the first derivative vector,
696         --   - V2, the second derivative vector,
697         --   - V3, the third derivative vector.
698         -- Warning
699         -- On a point where the continuity of the curve is not the
700         -- one requested, these functions impact the part
701         -- defined by the parameter with a value greater than U,
702         -- i.e. the part of the curve to the "right" of the singularity.
703         --   Raises UndefinedDerivative if the continuity of the curve is not C3.
704     
705   DN (me; U : Real; N : Integer)  returns Vec2d
706         --- Purpose: For the point of parameter U of this BSpline curve,
707         -- computes the vector corresponding to the Nth derivative.
708         -- Warning
709         -- On a point where the continuity of the curve is not the
710         -- one requested, this function impacts the part defined
711         -- by the parameter with a value greater than U, i.e. the
712         -- part of the curve to the "right" of the singularity.
713         --    Raises  UndefinedDerivative if the continuity of the curve is not CN.
714         --   RangeError if N < 1.
715      raises  UndefinedDerivative,
716                   RangeError;
717
718         --- Purpose: The following functions computes the point of parameter U 
719         --  and the derivatives at this point on the B-spline curve 
720         --  arc defined between the knot FromK1 and the knot ToK2. 
721         --  U can be out of bounds [Knot (FromK1),  Knot (ToK2)] but
722         --  for the computation we only use the definition of the curve
723         --  between these two knots. This method is useful to compute 
724         --  local derivative, if the order of continuity of the whole 
725         --  curve is not greater enough.    Inside the parametric
726         --  domain Knot (FromK1), Knot (ToK2) the evaluations are
727         --  the same as if we consider the whole definition of the
728         --  curve. Of course the evaluations are different outside
729         --  this parametric domain.
730
731
732   LocalValue (me; U : Real; FromK1, ToK2 : Integer)   returns Pnt2d
733      raises DomainError,
734         --- Purpose : Raised if FromK1 = ToK2.
735             OutOfRange;
736         --- Purpose :
737         --  Raised if FromK1 and ToK2 are not in the range 
738         --  [FirstUKnotIndex, LastUKnotIndex].
739
740
741   LocalD0 (me; U : Real; FromK1, ToK2 : Integer; 
742            P : out Pnt2d)
743      raises UndefinedDerivative, OutOfRange;
744      
745      
746   LocalD1 (me; U : Real; FromK1, ToK2 : Integer; 
747            P : out Pnt2d; V1 : out Vec2d)
748      raises UndefinedDerivative,
749         --- Purpose :
750         --  Raised if the local continuity of the curve is not C1 
751         --  between the knot K1 and the knot K2. 
752             DomainError,
753         --- Purpose : Raised if FromK1 = ToK2.
754             OutOfRange;
755         --- Purpose :
756         --  Raised if FromK1 and ToK2 are not in the range 
757         --  [FirstUKnotIndex, LastUKnotIndex].
758
759
760   LocalD2 (me; U : Real; FromK1, ToK2 : Integer;
761            P : out Pnt2d; V1, V2 : out Vec2d)
762      raises UndefinedDerivative,
763         --- Purpose :
764         --  Raised if the local continuity of the curve is not C2 
765         --  between the knot K1 and the knot K2. 
766             DomainError,
767         --- Purpose : Raised if FromK1 = ToK2.
768             OutOfRange;
769         --- Purpose :
770         --  Raised if FromK1 and ToK2 are not in the range 
771         --  [FirstUKnotIndex, LastUKnotIndex].
772
773
774
775   LocalD3 (me; U : Real;  FromK1, ToK2 : Integer;
776            P : out Pnt2d; V1, V2, V3 : out Vec2d)
777      raises UndefinedDerivative,
778         --- Purpose :
779         --  Raised if the local continuity of the curve is not C3
780         --  between the knot K1 and the knot K2. 
781             DomainError,
782         --- Purpose : Raised if FromK1 = ToK2.
783             OutOfRange;
784         --- Purpose :
785         --  Raised if FromK1 and ToK2 are not in the range
786         --  [FirstUKnotIndex, LastUKnotIndex].
787
788
789   LocalDN (me; U : Real;  FromK1, ToK2 : Integer; N : Integer)  returns Vec2d
790      raises  UndefinedDerivative,
791         --- Purpose :
792         --  Raised if the local continuity of the curve is not CN
793         --  between the knot K1 and the knot K2. 
794             DomainError,
795         --- Purpose : Raised if FromK1 = ToK2.
796              RangeError,
797         --- Purpose : Raised if N < 1.
798              OutOfRange;
799         --- Purpose :
800         --  Raises if FromK1 and ToK2 are not in the range 
801         --  [FirstUKnotIndex, LastUKnotIndex].
802
803
804   EndPoint (me)   returns Pnt2d;
805         --- Purpose :
806         --  Returns the last point of the curve.
807         -- Warnings :
808         --  The last point of the curve is different from the last 
809         --  pole of the curve if the multiplicity of the last knot
810         --  is lower than Degree.
811
812
813   FirstUKnotIndex (me)   returns Integer;
814         --- Purpose :
815         --  For a B-spline curve the first parameter (which gives the start
816         --  point of the curve) is a knot value but if the multiplicity of
817         --  the first knot index is lower than Degree + 1 it is not the 
818         --  first knot of the curve. This method computes the index of the
819         --  knot corresponding to the first parameter.
820
821
822   FirstParameter (me)   returns Real;
823         --- Purpose :
824         --  Computes the parametric value of the start point of the curve.
825         --  It is a knot value.
826
827
828   Knot (me; Index : Integer)   returns Real
829         --- Purpose :
830         --  Returns the knot of range Index. When there is a knot 
831         --  with a multiplicity greater than 1 the knot is not repeated.
832         --  The method Multiplicity can be used to get the multiplicity 
833         --  of the Knot.
834      raises OutOfRange;
835         --- Purpose : Raised if Index < 1 or Index > NbKnots
836
837
838   Knots (me; K : out Array1OfReal from TColStd)
839         --- Purpose : returns the knot values of the B-spline curve;
840      raises DimensionError;
841         --- Purpose :
842         --  Raised if the length of K is not equal to the number of knots.
843
844
845   KnotSequence (me; K : out Array1OfReal from TColStd)
846         --- Purpose : Returns the knots sequence.
847         --  In this sequence the knots with a multiplicity greater than 1
848         --  are repeated. 
849         -- Example :
850         --  K = {k1, k1, k1, k2, k3, k3, k4, k4, k4}
851      raises DimensionError;
852         --- Purpose :
853         --  Raised if the length of K is not equal to NbPoles + Degree + 1
854
855
856
857   KnotDistribution (me) returns BSplKnotDistribution from GeomAbs;
858         --- Purpose :
859         --  Returns NonUniform or Uniform or QuasiUniform or PiecewiseBezier.
860         --  If all the knots differ by a positive constant from the 
861         --  preceding knot the BSpline Curve can be :
862         --  - Uniform if all the knots are of multiplicity 1,
863         --  - QuasiUniform if all the knots are of multiplicity 1 except for
864         --    the first and last knot which are of multiplicity Degree + 1,
865         --  - PiecewiseBezier if the first and last knots have multiplicity
866         --    Degree + 1 and if interior knots have multiplicity Degree
867         --    A piecewise Bezier with only two knots is a BezierCurve. 
868         --  else the curve is non uniform.
869         --  The tolerance criterion is Epsilon from class Real.
870
871
872   LastUKnotIndex (me)  returns Integer;
873         --- Purpose :
874         --  For a BSpline curve the last parameter (which gives the 
875         --  end point of the curve) is a knot value but if the 
876         --  multiplicity of the last knot index is lower than 
877         --  Degree + 1 it is not the last knot of the curve. This
878         --  method computes the index of the knot corresponding to
879         --  the last parameter.
880
881
882   LastParameter (me)   returns Real;
883         --- Purpose :
884         --  Computes the parametric value of the end point of the curve.
885         --  It is a knot value.
886
887
888   LocateU (me;
889            U                   : Real; 
890            ParametricTolerance : Real; 
891            I1, I2              : in out Integer;
892            WithKnotRepetition  : Boolean = Standard_False);
893         --- Purpose :
894         --  Locates the parametric value U in the sequence of knots.
895         --  If "WithKnotRepetition" is True we consider the knot's
896         --  representation with repetition of multiple knot value,
897         --  otherwise  we consider the knot's representation with
898         --  no repetition of multiple knot values.
899         --  Knots (I1) <= U <= Knots (I2)
900         --  . if I1 = I2  U is a knot value (the tolerance criterion 
901         --    ParametricTolerance is used).
902         --  . if I1 < 1  => U < Knots (1) - Abs(ParametricTolerance)
903         --  . if I2 > NbKnots => U > Knots (NbKnots) + Abs(ParametricTolerance)
904
905
906   Multiplicity (me; Index : Integer)   returns Integer
907         --- Purpose :
908         --  Returns the multiplicity of the knots of range Index.
909      raises OutOfRange;
910         --- Purpose : Raised if Index < 1 or Index > NbKnots
911
912
913   Multiplicities (me; M : out Array1OfInteger from TColStd)
914         --- Purpose :
915         --  Returns the multiplicity of the knots of the curve.
916      raises DimensionError;
917         --- Purpose :
918         --  Raised if the length of M is not equal to NbKnots.
919
920
921   NbKnots (me)  returns Integer;
922         --- Purpose :
923         --  Returns the number of knots. This method returns the number of 
924         --  knot without repetition of multiple knots.
925
926
927   NbPoles (me)  returns Integer;
928         --- Purpose : Returns the number of poles
929
930
931   Pole (me; Index : Integer)   returns Pnt2d
932         --- Purpose : Returns the pole of range Index.
933      raises OutOfRange;
934         --- Purpose : Raised if Index < 1 or Index > NbPoles.
935
936
937   Poles (me; P : out Array1OfPnt2d)
938         --- Purpose : Returns the poles of the B-spline curve;
939      raises DimensionError;
940         --- Purpose : 
941         --  Raised if the length of P is not equal to the number of poles.
942
943
944   StartPoint (me)  returns Pnt2d;
945         --- Purpose :
946         --  Returns the start point of the curve.
947         -- Warnings :
948         --  This point is different from the first pole of the curve if the
949         --  multiplicity of the first knot is lower than Degree.
950
951
952   Weight (me; Index : Integer)  returns Real  
953         --- Purpose : Returns the weight of the pole of range Index .
954      raises OutOfRange;
955         --- Purpose : Raised if Index < 1 or Index > NbPoles.
956
957
958   Weights (me; W : out Array1OfReal from TColStd)
959         --- Purpose : Returns the weights of the B-spline curve;
960      raises DimensionError;
961         --- Purpose :
962         --  Raised if the length of W is not equal to NbPoles.
963
964
965
966
967
968
969   Transform (me : mutable; T : Trsf2d);
970 ---Purpose: Applies the transformation T to this BSpline curve.
971
972   MaxDegree (myclass)  returns Integer;
973         --- Purpose :
974         --  Returns the value of the maximum degree of the normalized 
975         --  B-spline basis functions in this package.
976
977
978   Resolution(me          : mutable; 
979              ToleranceUV : Real;
980              UTolerance  : out Real); 
981         ---Purpose:  Computes for this BSpline curve the parametric
982         -- tolerance UTolerance for a given tolerance
983         -- Tolerance3D (relative to dimensions in the plane).
984         -- If f(t) is the equation of this BSpline curve,
985         -- UTolerance ensures that:
986         --           | t1 - t0| < Utolerance ===> 
987         --           |f(t1) - f(t0)| < ToleranceUV
988
989
990   Copy (me)  returns mutable like me;
991         ---Purpose: Creates a new object which is a copy of this BSpline curve.  
992     
993   UpdateKnots(me : mutable)
994         ---Purpose: Recompute  the  flatknots,  the knotsdistribution, the continuity.
995   is static private;
996   
997   InvalidateCache(me : mutable)
998         ---Purpose : Invalidates the cache. This has to be private this has to be private
999       is static private;
1000
1001   
1002   ValidateCache(me : mutable ; Parameter : Real) 
1003   
1004     is static private;
1005         ---Purpose : updates the cache and validates it
1006              
1007 fields
1008
1009   rational  : Boolean;
1010   periodic  : Boolean;
1011   knotSet   : BSplKnotDistribution from GeomAbs; 
1012   smooth    : Shape from GeomAbs;
1013   deg       : Integer;
1014   poles     : HArray1OfPnt2d from TColgp;
1015   weights   : HArray1OfReal from TColStd;
1016   flatknots : HArray1OfReal from TColStd;
1017   knots     : HArray1OfReal from TColStd;
1018   mults     : HArray1OfInteger from TColStd;
1019   cachepoles      : HArray1OfPnt2d     from TColgp;
1020   -- Taylor expansion of the poles function, in homogeneous
1021   -- form if the curve is rational. The taylor expansion
1022   -- is normalized so that the span corresponds to
1023   -- [0 1] see below
1024   cacheweights    : HArray1OfReal    from TColStd;
1025   -- Taylor expansion of the poles function, in homogeneous
1026   -- form if the curve is rational. The taylor expansion
1027   -- is normalized so that the span corresponds to
1028   -- [0 1] see below
1029   validcache      : Integer;
1030   -- = 1 the cache is valid 
1031   -- = 0 the cache is invalid
1032   parametercache    : Real;
1033   -- Parameter at which the Taylor expension is stored in 
1034   -- the cache
1035   spanlenghtcache   : Real;
1036   -- Since the Taylor expansion is normalized in the 
1037   -- cache to evaluate the cache one has to use
1038   -- (Parameter - refcache) * normcache 
1039   spanindexcache : Integer;
1040   -- the span for which the cache is valid if 
1041   -- validcache is 1 
1042
1043   -- usefull to evaluate the parametric resolution
1044   maxderivinv   : Real from Standard;
1045   maxderivinvok : Boolean from Standard;
1046
1047   myMutex       : Mutex from Standard;
1048   -- protected bspline-cache
1049
1050 end;