0023024: Update headers of OCCT files
[occt.git] / src / AppParCurves / AppParCurves_LeastSquare.cdl
1 -- Created on: 1991-07-25
2 -- Created by: Laurent PAINNOT
3 -- Copyright (c) 1991-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
23
24 generic class LeastSquare from AppParCurves
25                     (MultiLine   as any;
26                      ToolLine    as any)   -- as ToolLine(MultiLine)
27
28
29     ---Purpose: This class describes the least square fitting of a 
30     --          MultiLine using the Householder method from the
31     --          mathematical package.
32     --          The problem to solve is the following one:
33     --          minimizing the sum(|C(ui)- Qi|)2 where Qi are the points of
34     --          the MultiLine and C(ui) the points of the approximating 
35     --          curves.
36
37
38
39 uses  Matrix           from math,
40       Vector           from math,
41       IntegerVector    from math,
42       Constraint       from AppParCurves,
43       MultiCurve       from AppParCurves,
44       MultiBSpCurve    from AppParCurves,
45       Array1OfInteger  from TColStd,
46       Array1OfReal     from TColStd,
47       HArray1OfInteger from TColStd,
48       HArray1OfReal    from TColStd
49
50
51 raises NotDone        from StdFail, 
52        OutOfRange     from Standard,
53        DimensionError from Standard,
54        NoSuchObject   from Standard
55
56 is
57
58     Create(SSP: MultiLine; FirstPoint, LastPoint: Integer;
59            FirstCons, LastCons: Constraint; 
60            Parameters: Vector from math; NbPol: Integer)
61         ---Purpose: given a MultiLine, this algorithm computes the least 
62         --          square resolution using the Householder-QR method.
63         --          If the first and/or the last point is a constraint 
64         --          point, the value of the tangency or curvature is 
65         --          computed in the resolution.
66         --          NbPol is the number of control points wanted 
67         --          for the approximating curves. 
68         --          The system to solve is the following:
69         --          A X = B. 
70         --          Where A is the Bernstein matrix computed with the
71         --          parameters, B the points coordinates and X the poles 
72         --          solutions.
73         --          The matrix A is the same for each coordinate x, y and z
74         --          and is also the same for each MultiLine point because 
75         --          they are approximated in parallel(so with the same
76         --          parameter, only the vector B changes).
77
78     returns LeastSquare from AppParCurves
79     raises DimensionError from Standard;    
80
81
82     
83     Create(SSP: MultiLine; FirstPoint, LastPoint: Integer;
84            FirstCons, LastCons: Constraint; NbPol: Integer)
85         ---Purpose: Initializes the fields of the object.
86     
87     returns LeastSquare;
88
89
90     Create(SSP: MultiLine; Knots: Array1OfReal; Mults: Array1OfInteger;
91            FirstPoint, LastPoint: Integer;
92            FirstCons, LastCons: Constraint; 
93            Parameters: Vector from math; NbPol: Integer)
94         ---Purpose: given a MultiLine, this algorithm computes the least 
95         --          square resolution using the Householder-QR method.
96         --          If the first and/or the last point is a constraint 
97         --          point, the value of the tangency or curvature is 
98         --          computed in the resolution.
99         --          Deg is the degree wanted for the approximating curves. 
100         --          The system to solve is the following:
101         --          A X = B. 
102         --          Where A is the BSpline functions matrix computed with
103         --          <parameters>, B the points coordinates and X the poles 
104         --          solutions.
105         --          The matrix A is the same for each coordinate x, y and z
106         --          and is also the same for each MultiLine point because 
107         --          they are approximated in parallel(so with the same
108         --          parameter, only the vector B changes).
109
110     returns LeastSquare from AppParCurves
111     raises DimensionError from Standard;    
112
113
114     
115     Create(SSP: MultiLine; Knots: Array1OfReal; Mults: Array1OfInteger;
116            FirstPoint, LastPoint: Integer;
117            FirstCons, LastCons: Constraint; NbPol: Integer)
118         ---Purpose: Initializes the fields of the object.
119     
120     returns LeastSquare;
121
122
123
124     Init(me: in out; SSP: MultiLine; FirstPoint, LastPoint: Integer) 
125         ---Purpose: is used by the constuctors above.
126
127     is static protected;
128
129
130     Perform(me: in out; Parameters: Vector)
131         ---Purpose: Is used after having initialized the fields.
132         --          The case "CurvaturePoint" is not treated in this method.
133
134     is static;
135
136
137     Perform(me: in out; Parameters: Vector;
138             l1, l2: Real)
139         ---Purpose: Is used after having initialized the fields.
140     
141     is static;
142     
143
144     ----------------------------------------------------------------------
145     --   for the two following methods, vectors <V> must be constructed
146     --   as follow: 
147     --   V(v1x, v1y, v1z, ....., vnx, vny, vnz, v1x, v1y, ....., vmx, vmy)
148     --      3d curve               3d curve     2d curve          2d curve
149     --      
150     --   the length of V must be Nb3dpoints*3 + Nb2dpoints*2
151
152
153     Perform(me: in out; Parameters: Vector;
154             V1t, V2t: Vector;
155             l1, l2: Real)
156         ---Purpose: Is used after having initialized the fields.
157         --- <V1t> is the tangent vector at the first point.
158         --- <V2t> is the tangent vector at the last point.
159     is static;
160     
161     Perform(me: in out; Parameters: Vector;
162             V1t, V2t, V1c, V2c: Vector;
163             l1, l2: Real)
164         ---Purpose: Is used after having initialized the fields.
165         --- <V1t> is the tangent vector at the first point.
166         --- <V2t> is the tangent vector at the last point.
167         --- <V1c> is the tangent vector at the first point.
168         --- <V2c> is the tangent vector at the last point.
169     
170     is static;
171     
172     
173     -------------------------------
174     --- Result methods:
175     -------------------------------
176     
177
178     IsDone(me)
179         ---Purpose: returns True if all has been correctly done.
180
181     returns Boolean
182     is static;
183     
184     
185     BezierValue(me: in out)
186         ---Purpose: returns the result of the approximation, i.e. all the
187         --          Curves.
188         --          An exception is raised if NotDone.
189
190     returns MultiCurve from AppParCurves
191     raises NotDone from StdFail,
192     NoSuchObject   from Standard
193     is static;
194
195
196     BSplineValue(me: in out)
197         ---Purpose: returns the result of the approximation, i.e. all the
198         --          Curves.
199         --          An exception is raised if NotDone.
200         ---C++: return const &
201
202     returns MultiBSpCurve from AppParCurves
203     raises NotDone from StdFail,
204     NoSuchObject   from Standard
205     is static;
206
207
208     FunctionMatrix(me)
209         ---Purpose: returns the function matrix used to approximate the 
210         --          set.
211         ---C++: return const &
212
213     returns Matrix from math
214     raises NotDone from StdFail
215     is static;
216
217
218
219     DerivativeFunctionMatrix(me)
220         ---Purpose: returns the derivative function matrix used 
221         --          to approximate the set.
222         ---C++: return const &
223
224     returns Matrix from math
225     raises NotDone from StdFail
226     is static;
227
228
229     ErrorGradient(me: in out; Grad: in out Vector; 
230                   F: in out Real; MaxE3d, MaxE2d: in out Real) 
231         ---Purpose: returns the maximum errors between the MultiLine 
232         --          and the approximation curves. F is the sum of the square
233         --          distances. Grad is the derivative vector of the 
234         --          function F.
235             
236     is static;
237     
238     
239     Distance(me: in out)
240         ---Purpose: returns the distances between the points of the 
241         --          multiline and the approximation curves.
242         ---C++: return const&
243
244     returns Matrix from math
245     is static;
246     
247     
248     Error(me: in out; F: in out Real; 
249           MaxE3d, MaxE2d: in out Real)
250         ---Purpose: returns the maximum errors between the MultiLine 
251         --          and the approximation curves. F is the sum of the square
252         --          distances.
253     
254     is static;
255     
256
257     FirstLambda(me)
258         ---Purpose: returns the value (P2 - P1)/ V1 if the first point
259         --          was a tangency point.
260     
261     returns Real
262     is static;
263     
264
265     LastLambda(me)
266         ---Purpose: returns the value (PN - PN-1)/ VN if the last point
267         --          was a tangency point.
268     
269     returns Real
270     is static;
271
272     
273     Points(me)
274         ---Purpose: returns the matrix of points value.
275         ---C++: return const&
276
277     returns Matrix
278     is static;
279     
280
281     Poles(me)
282         ---Purpose: returns the matrix of resulting control points value.
283         ---C++: return const&
284
285     returns Matrix
286     is static;
287     
288     
289     KIndex(me)
290         ---Purpose: Returns the indexes of the first non null values of
291         --          A and DA.
292         --          The values are non null from Index(ieme point) +1
293         --          to Index(ieme point) + degree +1.
294         ---C++: return const&
295     
296     returns IntegerVector
297     is static;
298     
299     
300     
301     -------------------------------
302     --- internal methods:
303     -------------------------------
304     
305     NbBColumns(me; SSP: MultiLine)
306         ---Purpose: returns the number of second member columns. 
307         --          Is used internally to initialize the fields.
308     returns Integer
309     is static protected;
310
311
312     TheFirstPoint(me; FirstCons: Constraint; FirstPoint: Integer)
313         ---Purpose: returns the first point beeing fitted.
314     returns Integer
315     is static protected;
316
317
318     TheLastPoint(me; LastCons: Constraint; LastPoint: Integer)
319         ---Purpose: returns the last point beeing fitted.
320     returns Integer
321     is static protected;
322     
323
324     Affect(me: in out; SSP: MultiLine; Index: Integer;
325            Cons: in out Constraint; Vt, Vc: in out Vector)
326         ---Purpose: Affects the fields in the case of a constraint point.
327     is static protected;
328     
329
330     ComputeFunction(me: in out; Parameters: Vector)
331         ---Purpose:
332     is static protected;
333     
334
335     SearchIndex(me: in out; Index: in out IntegerVector)
336     is static protected;
337
338
339     MakeTAA(me: in out; TheA, TheB: in out Vector)
340         ---Purpose: computes internal matrixes for the resolution
341     is static protected;
342
343     MakeTAA(me: in out; TheA: in out Vector)
344         ---Purpose: computes internal matrixes for the resolution
345     is static protected;
346
347     MakeTAA(me: in out; TheA: in out Vector; TheB: in out Matrix)
348         ---Purpose: computes internal matrixes for the resolution
349     is static protected;
350
351 fields
352
353
354 FirstConstraint : Constraint       from AppParCurves;
355 LastConstraint :  Constraint       from AppParCurves;
356 SCU:              MultiBSpCurve    from AppParCurves;
357 myknots:          HArray1OfReal    from TColStd;
358 mymults:          HArray1OfInteger from TColStd;
359 mypoles:          Matrix           from math;
360 A:                Matrix           from math;
361 DA:               Matrix           from math;
362 B2:               Matrix           from math;
363 mypoints:         Matrix           from math;
364 Vflatknots:       Vector           from math;
365 Vec1t:            Vector           from math;
366 Vec1c:            Vector           from math;
367 Vec2t:            Vector           from math;
368 Vec2c:            Vector           from math;
369 theError:         Matrix           from math;
370 myindex:          IntegerVector    from math;
371
372 ERR3d:            Real;
373 ERR2d:            Real;
374 lambda1:          Real;
375 lambda2:          Real; 
376
377 FirstP:           Integer;
378 LastP:            Integer;
379 Nlignes:          Integer;
380 Ninc:             Integer;
381 NA:               Integer;
382 myfirstp:         Integer;
383 mylastp:          Integer;
384 resinit:          Integer;
385 resfin:           Integer;
386 nbP2d:            Integer;
387 nbP:              Integer; 
388
389 nbpoles:          Integer;
390 deg:              Integer; 
391
392 done:             Boolean; 
393 iscalculated  :   Boolean; 
394 isready       :   Boolean;
395 end LeastSquare;
396