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
6 // This file is part of Open CASCADE Technology software library.
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.
14 // Alternatively, this file may be used under the terms of Open CASCADE
15 // commercial license or contractual agreement.
17 #ifndef _GProp_GProps_HeaderFile
18 #define _GProp_GProps_HeaderFile
20 #include <Standard.hxx>
21 #include <Standard_DefineAlloc.hxx>
22 #include <Standard_Handle.hxx>
25 #include <Standard_Real.hxx>
27 class Standard_DomainError;
31 class GProp_PrincipalProps;
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.
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.
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.
57 //! The global properties computed are :
58 //! - the dimension (length, area or volume)
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,
70 //! Example of utilisation in a simplified C++ implementation :
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 ();
77 //! //computes the inertia of a 3d curve
78 //! Your_CGProps Component1 (curve, ....);
80 //! //computes the inertia of surfaces
81 //! Your_SGprops Component2 (surface1, ....);
82 //! Your_SGprops Component3 (surface2,....);
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);
93 //! //returns the centre of mass of the system in the
94 //! //absolute cartesian coordinate system
95 //! gp_Pnt G = System.CentreOfMass ();
97 //! //computes the principales inertia of the system
98 //! GProp_PrincipalProps Pp = System.PrincipalProperties();
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);
108 DEFINE_STANDARD_ALLOC
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();
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);
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.
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.
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);
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.
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;
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;
211 //! returns the matrix of inertia. It is a symmetrical matrix.
212 //! The coefficients of the matrix are the quadratic moments of
216 //! matrix = | Ixy Iyy Iyz |
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;
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;
236 //! computes the moment of inertia of the material system about the
238 Standard_EXPORT Standard_Real MomentOfInertia (const gp_Ax1& A) const;
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;
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;
285 #endif // _GProp_GProps_HeaderFile