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