0024023: Revamp the OCCT Handle -- ambiguity
[occt.git] / src / AppDef / AppDef_Variational.cdl
1 -- Created on: 1996-05-14
2 -- Created by: Philippe MANGIN / Jeannine PANCIATICI
3 -- Copyright (c) 1996-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 --              Igor  FEOKTISTOV  -  correction  14/12/98
18
19
20 class Variational from AppDef
21
22
23     ---Purpose: This class is used to smooth N points with constraints
24     --          by   minimization  of quadratic  criterium   but  also
25     --          variational criterium in order to obtain " fair Curve "
26     --          Computes the approximation of a Multiline by
27     --          Variational optimization.
28
29 uses Matrix                    from math,
30      Vector                    from math,
31      HArray1OfReal             from TColStd, 
32      Array1OfReal              from TColStd, 
33      HArray1OfInteger          from TColStd,
34      Shape                     from GeomAbs,       
35      HArray1OfConstraintCouple from AppParCurves,
36      MultiBSpCurve             from AppParCurves,  
37      SmoothCriterion           from AppDef, 
38      Curve                     from FEmTool,
39      Assembly                  from FEmTool, 
40      Base                      from PLib,
41      Constraint                from AppParCurves,
42      MultiLine                 from AppDef,
43      MyLineTool                from AppDef
44
45 raises OutOfRange from Standard,
46        DimensionError from Standard,
47        DomainError from Standard,
48        ConstructionError from Standard,
49        NotDone    from StdFail,
50        VectorWithNullMagnitude from gp
51
52
53 is
54     Create(SSP: MultiLine from AppDef; 
55            FirstPoint, LastPoint: Integer;
56            TheConstraints: HArray1OfConstraintCouple;
57            MaxDegree: Integer = 14;
58            MaxSegment: Integer = 100;
59            Continuity : Shape from GeomAbs = GeomAbs_C2;
60            WithMinMax : Boolean = Standard_False;
61            WithCutting: Boolean = Standard_True;
62            Tolerance : Real = 1.0;
63            NbIterations: Integer = 2)
64         ---Purpose: Constructor.   
65         --            Initialization of   the   fields.
66         --            warning :  Nc0 : number of PassagePoint consraints
67         --                       Nc2 : number  of  TangencyPoint constraints 
68         --                       Nc3 : number of    CurvaturePoint   constraints
69         --            if
70         --            ((MaxDegree-Continuity)*MaxSegment -Nc0  - 2*Nc1
71         --             -3*Nc2)
72         --            is  negative 
73         --            The problem is over-constrained.
74         --            
75         --            Limitation : The MultiLine from AppDef has to be composed by
76         --            only one Line ( Dimension 2 or 3).
77            
78     returns Variational from AppDef;
79     
80
81     Approximate(me : in out)
82       ---Purpose: Makes the approximation with the current fields.
83     raises NotDone from StdFail
84     is static;
85     
86
87     
88 --   ====================  The Selectors  =========================== 
89
90     IsCreated(me)
91         ---Purpose: returns True if the creation is done    
92         --          and correspond  to the current fields.
93     returns Boolean
94     is static;
95
96  
97     IsDone(me)
98         ---Purpose: returns True if the  approximation is ok    
99         --          and correspond  to the current fields.
100     returns Boolean
101     is static;
102     
103     IsOverConstrained(me)
104         ---Purpose: returns True if the problem is overconstrained
105         --          in this case, approximation cannot be done.
106     returns Boolean
107     is static;
108     
109     Value(me)
110         ---Purpose: returns all the BSpline curves approximating the
111         --          MultiLine from AppDef SSP after minimization of the parameter.
112
113     returns MultiBSpCurve from AppParCurves
114     raises NotDone from StdFail
115     is static;
116     
117     
118     MaxError(me)
119         ---Purpose: returns the maximum of the distances between 
120         --          the points of the multiline and the approximation 
121         --          curves.  
122     returns Real 
123     raises NotDone from StdFail
124     is static;
125     
126     MaxErrorIndex(me)
127         ---Purpose: returns the index of the MultiPoint of ErrorMax  
128     returns Integer 
129     
130     raises NotDone from StdFail
131     is static;
132
133     
134     QuadraticError(me)
135         ---Purpose: returns the quadratic average of the distances between 
136         --          the points of the multiline and the approximation 
137         --          curves.
138     returns Real
139     raises NotDone from StdFail
140         is static;
141     
142     Distance(me : in out ; mat : out Matrix from math)    
143         ---Purpose: returns the distances between the points of the 
144         --          multiline and the approximation curves.
145     raises NotDone from StdFail
146     is static;
147     
148     AverageError(me)
149        ---Purpose: returns the average error between          
150        --          the MultiLine from AppDef and the approximation.
151
152     returns Real
153     raises NotDone from StdFail
154     is static;
155     
156     Parameters(me)   
157         ---Purpose: returns the parameters uses to the approximations
158         ---C++: return const&
159
160     returns HArray1OfReal
161     raises NotDone from StdFail
162     is static;
163     
164     Knots(me)   
165         ---Purpose: returns the knots uses to the approximations
166         ---C++: return const&
167     returns HArray1OfReal
168     raises NotDone from StdFail
169     is static;
170     
171     Criterium(me; VFirstOrder,  
172                   VSecondOrder,  
173                   VThirdOrder : out Real) 
174     ---Purpose: returns the values of the quality criterium.      
175     raises NotDone from StdFail
176     is static;
177     
178     CriteriumWeight(me ; 
179                     Percent1,  Percent2, Percent3 : out Real)
180     ---Purpose: returns the Weights (as percent) associed  to the criterium used in
181     --          the  optimization.
182     is static;          
183     
184     MaxDegree(me)   
185     ---Purpose: returns the Maximum Degree used in the approximation 
186     returns Integer
187     is static;
188     
189     MaxSegment(me)
190      ---Purpose: returns the Maximum of segment used in the approximation 
191     returns Integer
192     is static;   
193     
194     Continuity(me)
195     ---Purpose: returns the Continuity used in the approximation 
196     returns Shape from GeomAbs
197     is static;   
198     
199     
200     WithMinMax(me)
201     ---Purpose: returns if the  approximation  search to  minimize the
202     --          maximum Error or not.
203     returns Boolean
204     is static;   
205     
206     WithCutting(me)
207     ---Purpose: returns if the  approximation can insert new Knots or not.
208     returns Boolean
209     is static;  
210
211     Tolerance(me)
212     ---Purpose: returns the tolerance used in the approximation.
213     returns Real
214     is static;
215     
216     NbIterations(me)  
217     ---Purpose: returns the number of iterations used in the approximation.
218     returns Integer
219     is static;
220     
221     Dump(me ; o : in out OStream)
222         ---Purpose: Prints on the stream o information on the current state 
223         --          of the object.
224         --          MaxError,MaxErrorIndex,AverageError,QuadraticError,Criterium
225         --          Distances,Degre,Nombre de poles, parametres, noeuds    
226     is static;
227
228     SetConstraints(me:in out; aConstrainst:HArray1OfConstraintCouple) 
229         ---Purpose: Define the constraints to approximate
230     --          If this value is incompatible with the others fields
231     --          this method modify nothing and returns false 
232     returns Boolean
233     is static;
234     
235     SetParameters(me:in out; param : HArray1OfReal)   
236         ---Purpose: Defines the parameters used by the approximations.  
237     raises DimensionError
238     is static;
239     
240     SetKnots(me:in out; knots : HArray1OfReal)   
241         ---Purpose: Defines the knots used by the approximations
242     --          If this value is incompatible with the others fields
243     --          this method modify nothing and returns false 
244     returns Boolean
245     raises DimensionError,
246            DomainError
247     is static;
248         
249     SetMaxDegree(me: in out; Degree : Integer)   
250     ---Purpose: Define the Maximum Degree used in the approximation
251     --          If this value is incompatible with the others fields
252     --          this method modify nothing and returns false 
253     returns Boolean
254     is static;
255     
256     SetMaxSegment(me: in out;  NbSegment : Integer)   
257     ---Purpose: Define the maximum number of segments used in the approximation
258     --          If this value is incompatible with the others fields
259     --          this method modify nothing and returns false 
260     returns Boolean
261     is static;   
262     
263     SetContinuity(me: in out; C : Shape from GeomAbs)
264     ---Purpose: Define the Continuity used in the approximation 
265     --          If this value is incompatible with the others fields
266     --          this method modify nothing and returns false 
267     returns Boolean         
268     raises ConstructionError from Standard
269     is static;   
270     
271     
272     SetWithMinMax(me: in out; MinMax : Boolean)
273     ---Purpose: Define if the  approximation  search to  minimize the
274     --          maximum Error or not.
275     is static;   
276     
277     SetWithCutting(me : in out; Cutting : Boolean )
278     ---Purpose: Define if the  approximation can insert new Knots or not.
279     --          If this value is incompatible with the others fields
280     --          this method modify nothing and returns false 
281     returns Boolean
282     is static;  
283
284     SetCriteriumWeight(me : in out; 
285                        Percent1,  Percent2, Percent3 : Real)
286     ---Purpose: define the Weights (as percent) associed to the criterium used in
287     --          the  optimization.
288     --          
289     raises DomainError -- if Percent <= 0
290     is static;                  
291                                                                         
292     SetCriteriumWeight(me : in out; 
293                        Order : Integer;
294                        Percent : Real)
295     ---Purpose: define the  Weight   (as  percent)  associed  to   the
296     --          criterium   Order used in   the optimization  : Others
297     --          weights are updated.           
298     raises DomainError,  -- if Percent < 0
299            OutOfRange   -- if Order < 1 or Order > 3     
300     is static;
301   
302     SetTolerance(me:in out; Tol : Real)
303     ---Purpose: define the tolerance used in the approximation.
304     is static;
305     
306     SetNbIterations(me:in out; Iter : Integer)  
307     ---Purpose: define the number of iterations used in the approximation.
308     raises DomainError  -- if Iter < 1
309     is static; 
310
311       
312 --   ====================== The Private methods ======================   
313        
314     TheMotor(me  :  in  out; 
315              J  :  in  out SmoothCriterion from AppDef; 
316              WQuadratic,  WQuality  :  Real;          
317              TheCurve : in  out  Curve from  FEmTool; 
318              Ecarts : out  Array1OfReal  from  TColStd)  is  private; 
319
320     Adjusting(me  :  in  out; 
321               J  :  in  out SmoothCriterion from AppDef; 
322               WQuadratic,  WQuality  :  in  out  Real;                
323               TheCurve : in  out  Curve from  FEmTool; 
324               Ecarts : out  Array1OfReal  from  TColStd)  is  private; 
325       
326     Optimization(me;   
327                  J  :  in  out SmoothCriterion from AppDef; 
328                  A  :  in  out Assembly  from  FEmTool; 
329                  ToAssemble  : in  Boolean;      
330                  EpsDeg  :  Real; 
331                  Curve  :  out  Curve  from  FEmTool; 
332                  Parameters  :  Array1OfReal  from  TColStd)  is  private;    
333
334     Project(me;  C  :  Curve from  FEmTool;   
335                  Ti  :  Array1OfReal  from  TColStd; 
336                  ProjTi    :  out  Array1OfReal from  TColStd;  
337                  Distance  :  out  Array1OfReal from  TColStd; 
338                  NumPoints  :  out  Integer; 
339                  MaxErr,  QuaErr,  AveErr  :  out  Real; 
340                  NbIterations: Integer=2)  is  private; 
341
342     ACR(me;  Curve : in  out  Curve from  FEmTool; 
343              Ti    : in  out  Array1OfReal from  TColStd; 
344              Decima: Integer)  is  private; 
345
346     SplitCurve(me;  InCurve :  Curve from  FEmTool; 
347                     Ti      :  Array1OfReal from  TColStd;  
348                     CurveTol:  Real;
349                     OutCurve:  out Curve from  FEmTool; 
350                     iscut   :  out Boolean)  is  private; 
351                                      
352     Init(me : in out) 
353     raises NotDone from StdFail,
354            ConstructionError from Standard,
355            DimensionError from Standard
356     is private; 
357      
358     InitSmoothCriterion(me  :  in  out)   
359     is  private; 
360      
361     InitParameters(me  :  in  out;  Length  :  out  Real) 
362     raises  ConstructionError from Standard
363     is  private; 
364        
365     InitCriterionEstimations(me;  Length  :  Real;  J1,  J2,  J3  :  out  Real) 
366     is  private; 
367      
368     EstTangent(me;  ipnt  :  Integer;  VTang  :  out  Vector  from  math) 
369     is  private;
370  
371     EstSecnd(me;  ipnt  :  Integer;  VTang1,  VTang2  :  Vector  from  math; 
372                   Length  :  Real;  VScnd  :  out  Vector  from  math) 
373     is  private;
374  
375     InitCutting(me;  aBase  :  Base  from  PLib; CurvTol  :  Real;  
376                      aCurve  :  out  Curve   from  FEmTool) 
377     raises  ConstructionError from Standard
378     is  private;  
379      
380     AssemblingConstraints(me;  Curve  :  Curve  from  FEmTool; 
381                               Parameters  :  Array1OfReal  from  TColStd; 
382                               CBLONG  :  Real  from  Standard; 
383                               A  :  out  Assembly  from  FEmTool) 
384     is  private;  
385     
386     InitTthetaF(me : in out;  ndimen  :  Integer  from  Standard;
387                               typcon  :  Constraint  from  AppParCurves;
388                               begin   :  Integer  from  Standard; 
389                               jndex   :  Integer  from  Standard)
390     returns  Boolean
391     is  private;
392                               
393
394 fields
395      -- Description of the points to smooth and the constraints
396 mySSP  :  MultiLine from AppDef;
397 myNbP3d  : Integer;
398 myNbP2d : Integer;
399 myDimension : Integer;
400 myFirstPoint : Integer;
401 myLastPoint : Integer;
402 myNbPoints : Integer;
403 myTabPoints : HArray1OfReal;
404 myConstraints : HArray1OfConstraintCouple;
405 myNbConstraints : Integer;
406 myTabConstraints : HArray1OfReal;
407 myNbPassPoints : Integer;
408 myNbTangPoints : Integer;
409 myNbCurvPoints : Integer;
410 myTypConstraints : HArray1OfInteger; 
411 myTtheta  :  HArray1OfReal; 
412 myTfthet  :  HArray1OfReal;
413
414      -- Context parameters
415 myMaxDegree  : Integer;
416 myMaxSegment : Integer;
417 myNbIterations: Integer;
418 myTolerance : Real; 
419
420      -- Options
421 myContinuity : Shape from GeomAbs;
422 myNivCont : Integer;
423 myWithMinMax : Boolean;
424 myWithCutting: Boolean;
425 myPercent    : Real[3];
426 myCriterium  : Real[4]; 
427 mySmoothCriterion  :  SmoothCriterion  from  AppDef; 
428
429      -- output
430 myParameters  : HArray1OfReal;
431 myKnots      : HArray1OfReal;
432 myMBSpCurve  : MultiBSpCurve;
433
434 myMaxError     : Real;
435 myMaxErrorIndex: Integer;
436 myAverageError : Real;
437 myIsCreated      : Boolean;
438 myIsDone         : Boolean;
439 myIsOverConstr : Boolean;
440
441 end Variational;