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