fbac889c177b99236cd44344d60fddf19f202539
[occt.git] / src / GProp / GProp_VGPropsGK.cdl
1 -- Created on: 2005-12-21
2 -- Created by: Sergey KHROMOV
3 -- Copyright (c) 2005-2014 OPEN CASCADE SAS
4 --
5 -- This file is part of Open CASCADE Technology software library.
6 --
7 -- This library is free software; you can redistribute it and/or modify it under
8 -- the terms of the GNU Lesser General Public License version 2.1 as published
9 -- by the Free Software Foundation, with special exception defined in the file
10 -- OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 -- distribution for complete text of the license and disclaimer of any warranty.
12 --
13 -- Alternatively, this file may be used under the terms of Open CASCADE
14 -- commercial license or contractual agreement.
15
16 generic class VGPropsGK from GProp (Arc as any;
17                                   Face as any;
18                                   Domain as any)
19 inherits GProps from GProp
20
21         ---Purpose: Computes the global properties of a geometric solid 
22         --          (3D closed region of space) delimited with :
23         --            -  a point and a surface
24         --            -  a plane and a surface
25         --  
26         --          The surface can be :
27         --            -  a surface limited with its parametric values U-V, 
28         --               (naturally restricted)
29         --            -  a surface limited in U-V space with its boundary 
30         --               curves.
31         --  
32         --          The surface's requirements to evaluate the global 
33         --          properties are defined in the template FaceTool class from 
34         --          the package GProp. 
35         --  
36         --          The adaptive 2D algorithm of Gauss-Kronrod integration of 
37         --          double integral is used. 
38         --  
39         --          The inner integral is computed along U parameter of 
40         --          surface. The integrand function is encapsulated in the 
41         --          support class UFunction that is defined below. 
42         --  
43         --          The outer integral is computed along T parameter of a 
44         --          bounding curve. The integrand function is encapsulated in 
45         --          the support class TFunction that is defined below.
46
47 uses 
48  
49     Pnt     from gp, 
50     XYZ     from gp, 
51     Pln     from gp, 
52     Address from Standard, 
53     Boolean from Standard, 
54     Real    from Standard 
55
56
57 --  Template class functions. Used for integration. Begin
58
59     class UFunction from GProp inherits Function from math 
60         ---Purpose: This class represents the integrand function for 
61         --          computation of an inner integral. The returned value 
62         --          depends on the value type and the flag IsByPoint. 
63         --  
64         --          The type of returned value is the one of the following 
65         --          values: 
66         --            -  GProp_Mass - volume computation. 
67         --            -  GProp_CenterMassX, GProp_CenterMassY, 
68         --               GProp_CenterMassZ - X, Y and Z coordinates of center 
69         --                                   of mass computation. 
70         --            -  GProp_InertiaXX, GProp_InertiaYY, GProp_InertiaZZ, 
71         --               GProp_InertiaXY, GProp_InertiaXZ, GProp_InertiaYZ 
72         --                                 - moments of inertia computation. 
73         --  
74         --          If the flag IsByPoint is set to Standard_True, the value is 
75         --          returned for the region of space that is delimited by a 
76         --          surface and a point. Otherwise all computations are 
77         --          performed for the region of space delimited by a surface 
78         --          and a plane.
79      
80     uses 
81      
82         Pnt       from gp, 
83         XYZ       from gp, 
84         Address   from Standard, 
85         Boolean   from Standard, 
86         Real      from Standard, 
87         ValueType from GProp
88     
89     is 
90      
91         Create(theSurface: Face; 
92                theVertex : Pnt     from gp; 
93                IsByPoint : Boolean from Standard; 
94                theCoeffs : Address from Standard) 
95         ---Purpose: Constructor. Initializes the function with the face, the 
96         --          location point, the flag IsByPoint and the coefficients 
97         --          theCoeff that have different meaning depending on the value 
98         --          of IsByPoint. 
99         --          If IsByPoint is equal to Standard_True, the number of the 
100         --          coefficients is equal to 3 and they represent X, Y and Z 
101         --          coordinates (theCoeff[0], theCoeff[1] and theCoeff[2] 
102         --          correspondingly) of the shift, if the inertia is computed 
103         --          with respect to the point different then the location. 
104         --          If IsByPoint is equal to Standard_False, the number of the 
105         --          coefficients is 4 and they represent the combination of 
106         --          plane parameters and shift values.
107         returns UFunction from GProp;  
108      
109         SetValueType(me: in out; theType: ValueType from GProp); 
110         ---Purpose: Setting the type of the value to be returned. 
111         ---C++: inline 
112      
113         SetVParam(me: in out; theVParam: Real from Standard);
114         ---Purpose: Setting the V parameter that is constant during the 
115         --          integral computation.
116         ---C++: inline 
117      
118         Value(me: in out; X:     Real from Standard; 
119                           F: out Real from Standard) 
120         ---Purpose: Returns a value of the function.
121         returns Boolean from Standard 
122         is redefined; 
123      
124         -----------------------
125         --  Private methods  --
126         -----------------------
127
128         VolumeValue(me: in out; X      :     Real from Standard; 
129                                 thePMP0: out XYZ  from gp; 
130                                 theS   : out Real from Standard; 
131                                 theD1  : out Real from Standard) 
132         ---Purpose: Private method. Returns the value for volume computation. 
133         --          Other returned values are: 
134         --            -  thePMP0 - PSurf(X,Y) minus Location. 
135         --            -  theS and theD1 coeffitients that are computed and used 
136         --               for computation of center of mass and inertia values 
137         --               by plane.
138         returns Real from Standard 
139         is private; 
140      
141         CenterMassValue(me: in out; X:     Real from Standard; 
142                                     F: out Real from Standard) 
143         ---Purpose: Private method. Returns a value for the center of mass 
144         --          computation. If the value type other then GProp_CenterMassX,
145         --          GProp_CenterMassY or GProp_CenterMassZ this method returns 
146         --          Standard_False. Returns Standard_True in case of successful 
147         --          computation of a value.
148         returns Boolean from Standard 
149         is private; 
150      
151         InertiaValue(me: in out; X:     Real from Standard; 
152                                  F: out Real from Standard) 
153         ---Purpose: Private method. Computes the value of intertia. The type of 
154         --          a value returned is defined by the value type. If it is 
155         --          other then GProp_InertiaXX, GProp_InertiaYY, 
156         --          GProp_InertiaZZ, GProp_InertiaXY, GProp_InertiaXZ or 
157         --          GProp_InertiaYZ, the method returns Standard_False. Returns 
158         --          Standard_True in case of successful computation of a value.
159         returns Boolean from Standard 
160         is private; 
161      
162     fields 
163      
164         mySurface  : Face; 
165         myVertex   : Pnt       from gp; 
166         myCoeffs   : Address   from Standard; 
167         myVParam   : Real      from Standard; 
168         myValueType: ValueType from GProp;
169         myIsByPoint: Boolean   from Standard; 
170      
171     end UFunction;
172
173
174     --  Class  TFunction.
175
176     class TFunction from GProp inherits Function from math
177         ---Purpose: This class represents the integrand function for the outer 
178         --          integral computation. The returned value represents the 
179         --          integral of UFunction. It depends on the value type and the 
180         --          flag IsByPoint. 
181      
182     uses 
183      
184         Pnt       from gp, 
185         Address   from Standard, 
186         Boolean   from Standard, 
187         Integer   from Standard, 
188         Real      from Standard, 
189         ValueType from GProp
190     
191     is 
192      
193         Create(theSurface  : Face; 
194                theVertex   : Pnt     from gp; 
195                IsByPoint   : Boolean from Standard; 
196                theCoeffs   : Address from Standard; 
197                theUMin     : Real    from Standard; 
198                theTolerance: Real    from Standard) 
199         ---Purpose: Constructor. Initializes the function with the face, the 
200         --          location point, the flag IsByPoint, the coefficients 
201         --          theCoeff that have different meaning depending on the value 
202         --          of IsByPoint. The last two parameters are theUMin - the 
203         --          lower bound of the inner integral. This value is fixed for 
204         --          any integral. And the value of tolerance of inner integral 
205         --          computation.
206         --          If IsByPoint is equal to Standard_True, the number of the 
207         --          coefficients is equal to 3 and they represent X, Y and Z 
208         --          coordinates (theCoeff[0], theCoeff[1] and theCoeff[2] 
209         --          correspondingly) of the shift if the inertia is computed 
210         --          with respect to the point different then the location. 
211         --          If IsByPoint is equal to Standard_False, the number of the 
212         --          coefficients is 4 and they represent the compbination of 
213         --          plane parameters and shift values.
214         returns TFunction from GProp;   
215          
216         Init(me: in out);
217       
218         SetNbKronrodPoints(me: in out; theNbPoints: Integer from Standard);
219         ---Purpose: Setting the expected number of Kronrod points for the outer 
220         --          integral computation. This number is required for 
221         --          computation of a value of tolerance for inner integral 
222         --          computation. After GetStateNumber method call, this number 
223         --          is recomputed by the same law as in 
224         --          math_KronrodSingleIntegration, i.e. next number of points 
225         --          is equal to the current number plus a square root of the 
226         --          current number. If the law in math_KronrodSingleIntegration
227         --          is changed, the modification algo should be modified 
228         --          accordingly.
229         ---C++: inline 
230      
231         SetValueType(me: in out; aType: ValueType from GProp);
232         ---Purpose: Setting the type of the value to be returned. This 
233         --          parameter is directly passed to the UFunction. 
234         ---C++: inline 
235
236         SetTolerance(me: in out; aTol: Real from Standard);
237         ---Purpose: Setting the tolerance  for  inner integration
238         ---C++: inline 
239      
240         ErrorReached(me) 
241         ---Purpose: Returns the relative reached error of all values computation since 
242         --          the last call of GetStateNumber method.
243         ---C++: inline 
244         returns Real from Standard;
245
246         AbsolutError(me) 
247         ---Purpose: Returns the absolut reached error of all values computation since 
248         --          the last call of GetStateNumber method.
249         ---C++: inline 
250         returns Real from Standard;
251      
252         Value(me: in out; X:     Real from Standard; 
253                           F: out Real from Standard) 
254         ---Purpose: Returns a value of the function. The value represents an 
255         --          integral of UFunction. It is computed with the predefined 
256         --          tolerance using the adaptive Gauss-Kronrod method.
257         returns Boolean from Standard 
258         is redefined; 
259      
260         GetStateNumber(me: in out) 
261         ---Purpose:  Redefined  method. Remembers the error reached during 
262         --           computation of integral values since the object creation 
263         --           or the last call of GetStateNumber. It is invoked in each 
264         --           algorithm from the package math. Particularly in the 
265         --           algorithm math_KronrodSingleIntegration that is used to 
266         --           compute the integral of TFunction.
267         returns Integer
268         is redefined;
269      
270     fields 
271      
272         mySurface   : Face; 
273         myUFunction : UFunction; 
274         myUMin      : Real      from Standard; 
275         myTolerance : Real      from Standard; 
276         myTolReached: Real      from Standard; 
277         myErrReached: Real      from Standard; 
278         myAbsError  : Real      from Standard; 
279         myValueType : ValueType from GProp; 
280         myIsByPoint : Boolean   from Standard; 
281         myNbPntOuter: Integer   from Standard;
282     
283     end TFunction;
284
285 --  Template class functions. Used for integration. End
286
287 is
288  
289     Create
290         ---Purpose: Empty constructor. 
291         ---C++: inline 
292     returns VGPropsGK; 
293
294     Create(theSurface  : in out Face; 
295            theLocation :        Pnt  from gp; 
296            theTolerance:        Real from Standard = 0.001; 
297            theCGFlag: Boolean from Standard = Standard_False;  
298            theIFlag: Boolean from Standard = Standard_False)
299         ---Purpose: Constructor. Computes the global properties of a region of 
300         --          3D space delimited with the naturally restricted surface 
301         --          and the point VLocation.
302     returns VGPropsGK; 
303
304     Create(theSurface  : in out Face; 
305            thePoint    :        Pnt  from gp;
306            theLocation :        Pnt  from gp; 
307            theTolerance:        Real from Standard = 0.001; 
308            theCGFlag: Boolean from Standard = Standard_False;  
309            theIFlag: Boolean from Standard = Standard_False)
310
311         ---Purpose: Constructor. Computes the global properties of a region of 
312         --          3D space delimited with the naturally restricted surface 
313         --          and the point VLocation. The inertia is computed with 
314         --          respect to thePoint.
315     returns VGPropsGK; 
316
317     Create(theSurface  : in out Face; 
318            theDomain   : in out Domain; 
319            theLocation :        Pnt  from gp; 
320            theTolerance:        Real from Standard = 0.001; 
321            theCGFlag: Boolean from Standard = Standard_False;  
322            theIFlag: Boolean from Standard = Standard_False)
323            
324         ---Purpose: Constructor. Computes the global properties of a region of 
325         --          3D space delimited with the surface bounded by the domain 
326         --          and the point VLocation.
327     returns VGPropsGK; 
328
329     Create(theSurface  : in out Face; 
330            theDomain   : in out Domain; 
331            thePoint    :        Pnt  from gp; 
332            theLocation :        Pnt  from gp; 
333            theTolerance:        Real from Standard = 0.001;
334            theCGFlag: Boolean from Standard = Standard_False;  
335            theIFlag: Boolean from Standard = Standard_False)
336         ---Purpose: Constructor. Computes the global properties of a region of 
337         --          3D space delimited with the surface bounded by the domain 
338         --          and the point VLocation. The inertia is computed with 
339         --          respect to thePoint.
340     returns VGPropsGK; 
341
342     Create(theSurface  : in out Face; 
343            thePlane    :        Pln  from gp; 
344            theLocation :        Pnt  from gp; 
345            theTolerance:        Real from Standard = 0.001; 
346            theCGFlag: Boolean from Standard = Standard_False;  
347            theIFlag: Boolean from Standard = Standard_False)
348            
349         ---Purpose: Constructor. Computes the global properties of a region of 
350         --          3D space delimited with the naturally restricted surface 
351         --          and the plane.
352     returns VGPropsGK; 
353
354     Create(theSurface  : in out Face; 
355            theDomain   : in out Domain; 
356            thePlane    :        Pln  from gp; 
357            theLocation :        Pnt  from gp; 
358            theTolerance:        Real from Standard = 0.001; 
359            theCGFlag: Boolean from Standard = Standard_False;  
360            theIFlag: Boolean from Standard = Standard_False)
361            
362         ---Purpose: Constructor. Computes the global properties of a region of 
363         --          3D space delimited with the surface bounded by the domain 
364         --          and the plane.
365     returns VGPropsGK; 
366
367     SetLocation(me: in out; theLocation: Pnt from gp);
368         ---Purpose:  Sets the vertex that delimit 3D closed region of space.
369         ---C++: inline 
370
371     Perform(me: in out; theSurface  : in out Face; 
372                         theTolerance:        Real from Standard = 0.001; 
373                         theCGFlag: Boolean from Standard = Standard_False;  
374                         theIFlag: Boolean from Standard = Standard_False)
375                         
376         ---Purpose: Computes the global properties of a region of 3D space 
377         --          delimited with the naturally restricted surface and the 
378         --          point VLocation.
379     returns Real from Standard; 
380
381     Perform(me: in out; theSurface  : in out Face; 
382                         thePoint    :        Pnt  from gp;
383                         theTolerance:        Real from Standard = 0.001; 
384                         theCGFlag: Boolean from Standard = Standard_False;  
385                         theIFlag: Boolean from Standard = Standard_False)
386                         
387         ---Purpose: Computes the global properties of a region of 3D space 
388         --          delimited with the naturally restricted surface and the 
389         --          point VLocation. The inertia is computed with respect to 
390         --          thePoint.
391     returns Real from Standard; 
392
393     Perform(me: in out; theSurface  : in out Face; 
394                         theDomain   : in out Domain; 
395                         theTolerance:        Real from Standard = 0.001; 
396                         theCGFlag: Boolean from Standard = Standard_False;  
397                         theIFlag: Boolean from Standard = Standard_False)
398                         
399         ---Purpose: Computes the global properties of a region of 3D space 
400         --          delimited with the surface bounded by the domain and the 
401         --          point VLocation.
402     returns Real from Standard; 
403
404     Perform(me: in out; theSurface  : in out Face; 
405                         theDomain   : in out Domain; 
406                         thePoint    :        Pnt  from gp;
407                         theTolerance:        Real from Standard = 0.001; 
408                         theCGFlag: Boolean from Standard = Standard_False;  
409                         theIFlag: Boolean from Standard = Standard_False)
410         ---Purpose: Computes the global properties of a region of 3D space 
411         --          delimited with the surface bounded by the domain and the 
412         --          point VLocation. The inertia is computed with respect to 
413         --          thePoint.
414     returns Real from Standard; 
415
416     Perform(me: in out; theSurface  : in out Face; 
417                         thePlane    :        Pln  from gp;
418                         theTolerance:        Real from Standard = 0.001; 
419                         theCGFlag: Boolean from Standard = Standard_False;  
420                         theIFlag: Boolean from Standard = Standard_False)
421                         
422         ---Purpose: Computes the global properties of a region of 3D space 
423         --          delimited with the naturally restricted surface and the 
424         --          plane.
425     returns Real from Standard; 
426
427     Perform(me: in out; theSurface  : in out Face; 
428                         theDomain   : in out Domain; 
429                         thePlane    :        Pln  from gp;
430                         theTolerance:        Real from Standard = 0.001; 
431                         theCGFlag: Boolean from Standard = Standard_False;  
432                         theIFlag: Boolean from Standard = Standard_False)
433                         
434         ---Purpose: Computes the global properties of a region of 3D space 
435         --          delimited with the surface bounded by the domain and the 
436         --          plane.
437     returns Real from Standard; 
438
439     GetErrorReached(me)
440         ---Purpose: Returns the relative reached computation error. 
441         ---C++: inline 
442     returns Real from Standard;
443
444     GetAbsolutError(me)
445         ---Purpose: Returns the absolut reached computation error. 
446         ---C++: inline 
447     returns Real from Standard;
448   
449 -----------------------
450 --  Private methods  --
451 -----------------------
452
453     PrivatePerform(me: in out; 
454            theSurface  : in out Face; 
455            thePtrDomain:        Address from Standard; --  pointer to Domain.
456            IsByPoint   :        Boolean from Standard; 
457            theCoeffs   :        Address from Standard; 
458            theTolerance:        Real    from Standard; 
459            theCGFlag   :        Boolean from Standard;  
460            theIFlag    :        Boolean from Standard)
461            
462         ---Purpose: Main method for computation of the global properties that 
463         --          is invoked by each Perform method.
464     returns Real from Standard 
465     is private; 
466
467 fields
468  
469     myErrorReached: Real from Standard;
470     myAbsolutError: Real from Standard;
471
472 end VGPropsGK;