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