src/GProp/GProp_GProps.cdl

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