PK_ERROR_code_t PK_TOPOL_eval_mass_props
(
--- received arguments ---
int n_topols, --- number of topols ( >0 )
const PK_TOPOL_t topols[], --- topological entities array
double accuracy, --- 0.0 <= accuracy <= 1.0
const PK_TOPOL_eval_mass_props_o_t *options, --- options structure
--- returned arguments ---
double amount[], --- amount
double mass[], --- mass
double c_of_g[], --- centre of gravity
double m_of_i[], --- moment of inertia
double periphery[] --- periphery
)
This function evaluates mass properties of a given set of topological
entities.
Specific Errors:
PK_ERROR_bad_accuracy accuracy must lie between 0.0 and 1.0
PK_ERROR_empty_assy no bodies referenced from given assemblies
PK_ERROR_wrong_entity wrong entity type
PK_ERROR_different_types topols must all be of the same type
PK_ERROR_request_not_supported requested properties not all implemented
for the given topology
PK_ERROR_missing_geom missing geometry
PK_ERROR_density_le_0 negative or zero density
PK_ERROR_mass_eq_0 total mass is zero
This routine calculates the following geometric properties of certain
topological entities:
Type "Amount" "Mass" "Centre of "Moment of "Periphery"
Gravity" inertia"
========================================================================
Edge Length - C_of_g M_of_i -
Face Area - C_of_g M_of_i Circumference
Void region Volume - - - Surface Area
Solid region Volume Mass C_of_g M_of_i Surface Area
Wire body Length Mass C_of_g M_of_i -
Sheet Body Surface Area Mass C_of_g M_of_i Circumference
Solid Body Volume Mass C_of_g M_of_i Surface Area
Face/sheet)
considered) Volume - C_of_g M_of_i Surface Area
as Solid )
Assembly Total amount Mass As for components Total periphery
General Bodies:
dimension 3 Volume Mass C_of_g M_of_i Face area
dimension 2 Surface area Mass C_of_g M_of_i Edge length
dimension 1 Length Mass C_of_g M_of_i -
dimension 0 - Mass C_of_g M_of_i -
No other types are acceptable. The array of topologies topols must all
be of the same type, and the results are totals, except for the centre of
gravity and inertia, which refer to the collection of topologies. For an
array of assemblies, the results take account of all body occurrences
in the assemblies or sub-assemblies; these occurrences must all be
the same body type.
The values of results given as '-' are undefined on return.
The mass of a body is the product of its density and its amount, where the
density is obtained from an attached attribute and the amount depends on the
maximum dimension of the body. In the absence of a density attribute, the
density has a default value of 1. The dimension of a body is at least 0 if it
contains a vertex, 1 if it contains an edge, 2 if it contains a face and 3 if
it contains a solid region. The amount of a body is shown in the following
table:
Max. Dimension Amount
=============================================
3 Volume of solid regions
2 Surface area of faces
1 Length of edges
0 Number of vertices
For manifold bodies the dimension of all the bodies in a list must be the same
but, for general bodies, the dimension of a list of bodies is the maximum of
the dimensions of the bodies in the list.
Density attributes may also be attached to regions, faces, edges, or vertices.
Any density attached to one of these entities overrides the density of its
owning body and such an entity will always contribute to the mass, centre of
gravity and moment of inertia of its owning body, whatever the latter's maximum
dimension. As with bodies, the mass of an entity is the product of its density
and its amount (a vertex with density is regarded as a point mass, so the
density is its mass). The density of a void region is always zero and if a
density attribute is attached to a void region it will be ignored.
The periphery of a general body also depends on its maximum dimension. The
periphery of a body of dimension 3 is the surface area of all faces which bound
a void region. The periphery of a body of dimension 2 is the length of all
laminar or wireframe edges. The periphery of a body of dimension 1 or lower is
not defined.
For bodies or assemblies, m_of_i is the inertia tensor at the centre of
gravity ( with respect to the X, Y, Z axis directions ).
Accuracy of calculation:
If the calculation requested only involves simple geometries, an accurate
method of integration is used, and the parameter accuracy is ignored. In
complex cases accuracy is used to determine the accuracy of the
calculation: it must be in the range 0.0 to 1.0, and as it approaches 1.0,
the calculation will be more accurate but slower. The dependence of
results on 'accuracy' is not linear, and values below 0.9 will give
only coarse approximations. A great deal of calculation may be required
to satisfy an 'accuracy' of 1.0, and in general convergence cannot be
guaranteed. Supplying an accuracy parameter of 1.0 for parts involving
B-surfaces is not recommended.
Information found:
There are six possible requests which control how mass properties are
calculated - these are given in an option structure -
PK_TOPOL_eval_mass_props_o_t. The requests control the level of mass
properties calculated, whether periphery data is given, what style the
results bounds are presented in and whether the received entities
are considered separately or as part of a single entity.
Version 2 of the option structure also supports calculation of mass
properties by an alternative facetted method.
struct PK_TOPOL_eval_mass_props_o_s
{
int o_t_version; --- version number of option structure
PK_mass_t mass; --- required mass properties
--- (default = PK_mass_m_of_i_c)
PK_mass_periphery_t periphery; --- periphery required
--- (default = PK_mass_periphery_yes_c)
PK_mass_bound_t bound; --- bounds on results required
--- (default = PK_mass_bound_no_c)
PK_LOGICAL_t single; --- whether to treat topols as
--- single solid
--- (default = PK_LOGICAL_false)
PK_LOGICAL_t use_facets; --- whether to use alternative facetted
--- method (PK_LOGICAL_false)
double facet_tol; --- chordal tolerance to use for facets
--- 0.0 requests the internal default
};
The main mass properties form a hierarchy in that the mass is needed to find
the centre of gravity, and the centre of gravity is needed to find the
inertia. One token of type PK_mass_t controls the level to which
calculations are done. If no token for this option is given,
the default is PK_mass_m_of_i_c.
Token Interpretation
========================================================
PK_mass_no_c No data in this hierarchy is to be found
PK_mass_mass_c Finds the amount and mass of the entities only
PK_mass_c_of_g_c Finds the centre of gravity as well
PK_mass_m_of_i_c Finds the moment of inertia as well
The periphery data is controlled separately by another token of type
PK_mass_periphery_t, the default is PK_mass_periphery_yes_c.
Token Interpretation
========================================================
PK_mass_periphery_no_c No periphery data calculated
PK_mass_periphery_yes_c Calculates the periphery of the entities
Considering received entities as a single entity:
It is possible to supply an array of faces or an array of sheet bodies
and have them considered as forming the boundary of a single solid by
setting single to PK_LOGICAL_true (default is PK_LOGICAL_false).
Under this option the mass will not be returned, as there is currently
no way of unambiguously specifiying a density for the calculation.
The Moment of Inertia will be returned, but will be calculated without
reference to any density attributes attached to the supplied entities,
effectively assuming a density of one for the solid of which they form the
boundary.
No checking is done that the faces or sheets provided do form a valid
solid boundary. If they do not, the the returned results are likely to
be meaningless.
Alternative facetted method:
If the 'use_facets' option is set to PK_LOGICAL_true, then mass properties
of dimension 2 and 3 will be calculated by generated a facet mesh for each
face referenced and then combining the contributions for each facet. This
is intended to provide verification of the main parameter space based method.
The user has the option of supplying a chordal tolerance to use for the
facetting; this is equivalent to the 'curve_chord_tol' and
'surface_plane_tol' passed to PK_TOPOL_facet. If 0.0 is supplied, an
internal default will be used, taking into account the supplied 'accuracy'
parameter.
Note that is a backup method and will be slow and memory hungry if large
numbers of facets are generated; a careful choice of facet tolerance is
recommended.
Topologies are faces or edges:
An array of faces with the single option set to PK_LOGICAL_false or an
array of edges will be treated as a sheet or wire body respectively. Again
the density is not specified (any densities attached to the individual faces
or edges are ignored), so the Moment of Inertia will be calculated with an
assumed density of one.
Topologies are regions:
The periphery of a region is the sum of the unsigned areas of the faces - any
face occurring in a shell twice will be added to the total twice. The mass
of a region is only non-zero if it is solid. Properties of an array of
regions is the sum of the properties of the individual regions. It is only
possible to find the periphery of the exterior region and any other request
will result in the error PK_ERROR_request_not_supported being returned. It
is only possible to find the periphery and volume of a void region and any
other request will result in the error PK_ERROR_request_not_supported being
returned. It is possible to specify a mixture of solid and void regions, but
only if the request is supported for void regions.
Bounds:
Mass properties can be requested to calculate bounds on the values found
using a token of type PK_mass_bound_t. For each returned array, the initial
entries give the calculated value, and subsequent entries give the associated
bounds. There is the option of having no bounds output, of having a single
quantity to add or subtract from the answer value, or having intervals
specifying the ranges. For the centre of gravity, the latter two would
correspond to a sphere centred on the answer vector and a box containing
it. The default is PK_mass_bound_no_c.
Token Interpretation
========================================================
PK_mass_bound_no_c No errors are given
PK_mass_bound_modulus_c Modulus +/- to give range
PK_mass_bound_interval_c An interval bracketing the value is given
No error bounds are currently supported for the facetted method.
Returned arrays
The application must provide space for the returned information.
Parasolid will not attempt to write to return addresses for data which has
not been requested.
The size of the return arrays depends upon the setting of bound in the
options structure.
PK_mass_bound_no_c PK_mass_bound_modulus_c PK_mass_bound_interval_c
---------+------------------+-----------------------+------------------------
amount | 1 | 2 | 3
mass | 1 | 2 | 3
c_of_g | 3 | 4 | 9
m_of_i | 9 | 10 | 27
periphery| 1 | 2 | 3
---------+------------------+-----------------------+------------------------
For amount, mass and periphery, the zeroth array element is always the value.
If bound is PK_mass_bound_modulus_c then the 1st array element is the
modulus.
If bound is PK_mass_bound_interval_c then the 1st array element is the
lower bound and the 2nd array element is the upper bound.
For c_of_g, array elements 0, 1 and 2 always contain the coordinates of the
centre of gravity.
If bound is PK_mass_bound_modulus_c then the 4th array element is the
modulus.
If bound is PK_mass_bound_interval_c then elements 3, 4 and 5 contain the
lower bounds and elements 6, 7 and 8 contain the upper bounds.
For m_of_i, array elements 0 through 8 always contain the moment of inertia.
If bound is PK_mass_bound_modulus_c then the 9th array element is the
modulus.
If bound is PK_mass_bound_interval_c then elements 9 through 17 contain the
lower bounds and elements 18 through 26 contain the upper bounds.
