0031939: Coding - correction of spelling errors in comments
[occt.git] / src / GProp / GProp_GProps.hxx
1 // Created on: 1992-08-24
2 // Created by: Michel CHAUVAT
3 // Copyright (c) 1992-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 #ifndef _GProp_GProps_HeaderFile
18 #define _GProp_GProps_HeaderFile
19
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
23
24 #include <gp_Pnt.hxx>
25 #include <Standard_Real.hxx>
26 #include <gp_Mat.hxx>
27 class Standard_DomainError;
28 class gp_Pnt;
29 class gp_Mat;
30 class gp_Ax1;
31 class GProp_PrincipalProps;
32
33
34
35 //! Implements a general mechanism to compute the global properties of
36 //! a "compound geometric system" in 3d space    by composition of the
37 //! global properties of "elementary geometric entities"       such as
38 //! (curve, surface, solid, set of points).  It is possible to compose
39 //! the properties of several "compound geometric systems" too.
40 //!
41 //! To computes the global properties of a compound geometric
42 //! system you should :
43 //! . declare the GProps using a constructor which initializes the
44 //! GProps and defines the location point used to compute the inertia
45 //! . compose the global properties of your geometric components with
46 //! the properties of your system using the method Add.
47 //!
48 //! To compute the global properties of the geometric components of
49 //! the system you should  use the services of the following classes :
50 //! - class PGProps for a set of points,
51 //! - class CGProps for a curve,
52 //! - class SGProps for a surface,
53 //! - class VGProps for a "solid".
54 //! The classes CGProps, SGProps, VGProps are generic classes and
55 //! must be instantiated for your application.
56 //!
57 //! The global properties computed are :
58 //! - the dimension (length, area or volume)
59 //! - the mass,
60 //! - the centre of mass,
61 //! - the moments of inertia (static moments and quadratic moments),
62 //! - the moment about an axis,
63 //! - the radius of gyration about an axis,
64 //! - the principal properties of inertia  :
65 //! (sea also class PrincipalProps)
66 //! . the principal moments,
67 //! . the principal axis of inertia,
68 //! . the principal radius of gyration,
69 //!
70 //! Example of utilisation in a simplified C++ implementation :
71 //!
72 //! //declares the GProps, the point (0.0, 0.0, 0.0) of the
73 //! //absolute cartesian coordinate system is used as
74 //! //default reference point to compute the centre of mass
75 //! GProp_GProps System ();
76 //!
77 //! //computes the inertia of a 3d curve
78 //! Your_CGProps Component1 (curve, ....);
79 //!
80 //! //computes the inertia of surfaces
81 //! Your_SGprops Component2 (surface1, ....);
82 //! Your_SGprops Component3 (surface2,....);
83 //!
84 //! //composes the global properties of components 1, 2, 3
85 //! //a density can be associated with the components, the
86 //! //density can be defaulted to 1.
87 //! Real Density1 = 2.0;
88 //! Real Density2 = 3.0;
89 //! System.Add (Component1, Density1);
90 //! System.Add (Component2, Density2);
91 //! System.Add (Component3);
92 //!
93 //! //returns the centre of mass of the system in the
94 //! //absolute cartesian coordinate system
95 //! gp_Pnt G = System.CentreOfMass ();
96 //!
97 //! //computes the principales inertia of the system
98 //! GProp_PrincipalProps Pp  = System.PrincipalProperties();
99 //!
100 //! //returns the principal moments and radius of gyration
101 //! Real Ixx, Iyy, Izz, Rxx, Ryy, Rzz;
102 //! Pp.Moments (Ixx, Iyy, Izz);
103 //! Pp.RadiusOfGyration (Ixx, Iyy, Izz);
104 class GProp_GProps 
105 {
106 public:
107
108   DEFINE_STANDARD_ALLOC
109
110   
111
112   //! The origin (0, 0, 0) of the absolute cartesian coordinate system
113   //! is used to compute the global properties.
114   Standard_EXPORT GProp_GProps();
115   
116
117   //! The point SystemLocation is used to compute the global properties
118   //! of the system. For more accuracy it is better to define this
119   //! point closed to the location of the system. For example it could
120   //! be a point around the centre of mass of the system.
121   //! This point is referred to as the reference point for
122   //! this framework. For greater accuracy it is better for
123   //! the reference point to be close to the location of the
124   //! system. It can, for example, be a point near the
125   //! center of mass of the system.
126   //! At initialization, the framework is empty; i.e. it
127   //! retains no dimensional information such as mass, or
128   //! inertia. However, it is now able to bring together
129   //! global properties of various other systems, whose
130   //! global properties have already been computed
131   //! using another framework. To do this, use the
132   //! function Add to define the components of the
133   //! system. Use it once per component of the system,
134   //! and then use the interrogation functions available to
135   //! access the computed values.
136   Standard_EXPORT GProp_GProps(const gp_Pnt& SystemLocation);
137   
138   //! Either
139   //! - initializes the global properties retained by this
140   //! framework from those retained by the framework Item, or
141   //! - brings together the global properties still retained by
142   //! this framework with those retained by the framework Item.
143   //! The value Density, which is 1.0 by default, is used as
144   //! the density of the system analysed by Item.
145   //! Sometimes the density will have already been given at
146   //! the time of construction of the framework Item. This
147   //! may be the case for example, if Item is a
148   //! GProp_PGProps framework built to compute the
149   //! global properties of a set of points ; or another
150   //! GProp_GProps object which already retains
151   //! composite global properties. In these cases the real
152   //! density was perhaps already taken into account at the
153   //! time of construction of Item. Note that this is not
154   //! checked: if the density of parts of the system is taken
155   //! into account two or more times, results of the
156   //! computation will be false.
157   //! Notes :
158   //! - The point relative to which the inertia of Item is
159   //! computed (i.e. the reference point of Item) may be
160   //! different from the reference point in this
161   //! framework. Huygens' theorem is applied
162   //! automatically to transfer inertia values to the
163   //! reference point in this framework.
164   //! - The function Add is used once per component of
165   //! the system. After that, you use the interrogation
166   //! functions available to access values computed for the system.
167   //! - The system whose global properties are already
168   //! brought together by this framework is referred to
169   //! as the current system. However, the current system
170   //! is not retained by this framework, which maintains
171   //! only its global properties.
172   //! Exceptions
173   //! Standard_DomainError if Density is less than or
174   //! equal to gp::Resolution().
175   Standard_EXPORT void Add (const GProp_GProps& Item, const Standard_Real Density = 1.0);
176   
177   //! Returns the mass of the current system.
178   //! If no density is attached to the components of the
179   //! current system the returned value corresponds to :
180   //! - the total length of the edges of the current
181   //! system if this framework retains only linear
182   //! properties, as is the case for example, when
183   //! using only the LinearProperties function to
184   //! combine properties of lines from shapes, or
185   //! - the total area of the faces of the current system if
186   //! this framework retains only surface properties,
187   //! as is the case for example, when using only the
188   //! SurfaceProperties function to combine
189   //! properties of surfaces from shapes, or
190   //! - the total volume of the solids of the current
191   //! system if this framework retains only volume
192   //! properties, as is the case for example, when
193   //! using only the VolumeProperties function to
194   //! combine properties of volumes from solids.
195   //! Warning
196   //! A length, an area, or a volume is computed in the
197   //! current data unit system. The mass of a single
198   //! object is obtained by multiplying its length, its area
199   //! or its volume by the given density. You must be
200   //! consistent with respect to the units used.
201   Standard_EXPORT Standard_Real Mass() const;
202   
203
204   //! Returns the center of mass of the current system. If
205   //! the gravitational field is uniform, it is the center of gravity.
206   //! The coordinates returned for the center of mass are
207   //! expressed in the absolute Cartesian coordinate system.
208   Standard_EXPORT gp_Pnt CentreOfMass() const;
209   
210
211   //! returns the matrix of inertia. It is a symmetrical matrix.
212   //! The coefficients of the matrix are the quadratic moments of
213   //! inertia.
214   //!
215   //! | Ixx  Ixy  Ixz |
216   //! matrix =    | Ixy  Iyy  Iyz |
217   //! | Ixz  Iyz  Izz |
218   //!
219   //! The moments of inertia are denoted by Ixx, Iyy, Izz.
220   //! The products of inertia are denoted by Ixy, Ixz, Iyz.
221   //! The matrix of inertia is returned in the central coordinate
222   //! system (G, Gx, Gy, Gz) where G is the centre of mass of the
223   //! system and Gx, Gy, Gz the directions parallel to the X(1,0,0)
224   //! Y(0,1,0) Z(0,0,1) directions of the absolute cartesian
225   //! coordinate system. It is possible to compute the matrix of
226   //! inertia at another location point using the Huyghens theorem
227   //! (you can use the method of package GProp : HOperator).
228   Standard_EXPORT gp_Mat MatrixOfInertia() const;
229   
230   //! Returns Ix, Iy, Iz, the static moments of inertia of the
231   //! current system; i.e. the moments of inertia about the
232   //! three axes of the Cartesian coordinate system.
233   Standard_EXPORT void StaticMoments (Standard_Real& Ix, Standard_Real& Iy, Standard_Real& Iz) const;
234   
235
236   //! computes the moment of inertia of the material system about the
237   //! axis A.
238   Standard_EXPORT Standard_Real MomentOfInertia (const gp_Ax1& A) const;
239   
240   //! Computes the principal properties of inertia of the current system.
241   //! There is always a set of axes for which the products
242   //! of inertia of a geometric system are equal to 0; i.e. the
243   //! matrix of inertia of the system is diagonal. These axes
244   //! are the principal axes of inertia. Their origin is
245   //! coincident with the center of mass of the system. The
246   //! associated moments are called the principal moments of inertia.
247   //! This function computes the eigen values and the
248   //! eigen vectors of the matrix of inertia of the system.
249   //! Results are stored by using a presentation framework
250   //! of principal properties of inertia
251   //! (GProp_PrincipalProps object) which may be
252   //! queried to access the value sought.
253   Standard_EXPORT GProp_PrincipalProps PrincipalProperties() const;
254   
255   //! Returns the radius of gyration of the current system about the axis A.
256   Standard_EXPORT Standard_Real RadiusOfGyration (const gp_Ax1& A) const;
257
258
259
260
261 protected:
262
263
264
265   gp_Pnt g;
266   gp_Pnt loc;
267   Standard_Real dim;
268   gp_Mat inertia;
269
270
271 private:
272
273
274
275
276
277 };
278
279
280
281
282
283
284
285 #endif // _GProp_GProps_HeaderFile