PK_ERROR_code_t PK_BODY_boolean
(
--- received arguments ---
PK_BODY_t target, --- body to receive message
int n_tools, --- number of tool bodies
const PK_BODY_t tools[], --- tool bodies
const PK_BODY_boolean_o_t *options, --- boolean options
--- returned arguments ---
int *const n_bodies, --- number of resultant bodies
PK_BODY_t **const bodies --- resultant bodies
)
This function performs a boolean operation between the target body
and the list of tool bodies.
NOTE: This function is obsolete and has been superseded by PK_BODY_boolean_2.
Specific Errors:
PK_ERROR_contradictory_request bad combination of options or
data for type of boolean (MILD)
PK_ERROR_same_tool_and_target tool body is also target body (MILD)
PK_ERROR_missing_geom target or tool has incomplete
geometry (SERIOUS)
PK_ERROR_wire_body target or tool is a wire body (MILD)
PK_ERROR_duplicate_tools duplication in list of tool bodies
(MILD)
PK_ERROR_instanced_tools instanced tool bodies (MILD)
PK_ERROR_mixed_sheets_solids mixture of of sheet and solid
tool bodies (MILD)
PK_ERROR_cant_unite_solid_sheet attempt to unite solid and sheet
(SERIOUS)
PK_ERROR_opposed_sheets attempt to unite opposed sheets
(SERIOUS)
PK_ERROR_cant_intsc_solid_sheet cant intersect solid target with
sheet tool bodies (MILD)
PK_ERROR_t_sheet Operation would result in a T-sheet
(SERIOUS)
PK_ERROR_non_manifold non-manifold result (SERIOUS)
PK_ERROR_boolean_failure inconsistent arguments, or
internal error (SERIOUS)
PK_ERROR_general_body target or tool is general body (MILD)
PK_ERROR_invalid_match_region invalid matched topology data
(SERIOUS)
Introduction
A boolean operation between the target body and the tool bodies is
performed. The target body is modified and the tool bodies are deleted.
The resulting body or bodies replace the target, and are returned in
an array.
This function will accept general bodies in target or tools only if
generalised topology is enabled.
The Boolean Algorithm
A boolean may be a union, subtraction or intersection. The type of boolean
performed can be selected by setting the function field in the option
structure. If no function code is supplied, the default action is union.
Booleans in Parasolid may be thought of as being performed in three main
phases. These are imprinting, gluing, and selection.
o Imprinting : The faces of the target and the tool bodies are
intersected with each other to produce new edges where
they meet. These edges divide the faces of each body
into facesets which are either inside, outside, or on
the boundary of, the other bodies.
o Gluing : The resulting sets of faces are joined together into
a single intermediate body.
o Selection : The parts of the model which are to be kept or rejected
are selected, according to the type of boolean being
performed and the options supplied, using information
gained in the earlier phases.
If more than one tool body is supplied, the union of overlapping tool
bodies is computed first, and then the boolean between tools and
target is performed.
Booleans Performed with generalised topology disabled
If generalised topology is disabled, the result of the boolean may be any
number of bodies, each of which is a manifold and connected solid
or sheet.
o A union extends the target body by gluing to it all facesets of the tool
bodies which are outside the target body.
o A subtraction modifies the target body by removing all facesets which
overlap with the tool bodies.
o An intersection reduces the target body to only those facesets which
overlap with the tool bodies.
The behaviour of the subtraction function can be altered for solid/sheet,
sheet/sheet and sheet/solid booleans via the fence option.
o Subtract sheet tools from a solid or sheet target body. The resultant
bodies are of the same type (solid or sheet) as the original target
body.
o Fence = Front : Section the target body with the sheet tool, but only
return solid or sheet bodies in front of the sheet
tool body.
o Fence = Back : Section the target body with the sheet tool, but only
return solid or sheet bodies behind the sheet tool
body.
o Fence = None : Section the target body with the sheet tool, returning
solid or sheet bodies in front and behind the sheet
tool body.
o Subtract solid tools from a sheet target body. The resultant bodies are
sheet bodies.
o Fence = Front : The sheet target is modified by removing all facesets
which overlap with the solid tool bodies and then gluing
to it all the facesets of the tool bodies which are in
front of the sheet target body. A sheet body is returned.
o Fence = Back : The operation is the same as for the fence option being
set to Front except the facesets of the tool bodies
behind the sheet target body are maintained.
o Fence = None : The sheet target is modified by removing all facesets
which overlap with the solid tool bodies.
A valid manifold solid/sheet unite operation is possible when the surviving
regions of the unite operation enclose manifold volumes in the resultant body.
It is the responsibility of the application to ensure the following:
o The regions that survive the unite operation must specify a manifold
resultant body.
o The normals of the faces of the sheet tool body must be appropriate
to specify manifold enclosed volumes.
Booleans Performed with generalised topology enabled
If generalised topology is enabled, the result of the boolean will be a single
general body, which may be disconnected, non-manifold, of mixed dimension, or
any combination of these. The options prune_in_solid and prune_in_void may
be used to `prune off' lower-dimension components of the result (see below).
o A union extends the target body after imprinting to include all the
facesets from both tools and target.
o A subtraction modifies the target body by removing from it those pieces
which overlap with the union of the tool bodies.
o An intersection reduces the target body to those pieces which overlap
with the union of the tool bodies.
The value of the fence option is ignored within the context of booleans
performed with generalised topology enabled.
Merging and Tag Persistence
The result of a boolean may contain a number of new mergable faces,
edges and vertices. These are not merged away unless requested by
setting the merge_imprinted option. Only new mergable entities are
deleted. The mergable faces, edges and vertices of the original target
and tool bodies are not merged away.
The boolean operation obeys tag persistence rules under the
appropriate conditions. For a description of the persistent behaviour
of tags for a boolean operation, please refer to the section,
Persistence of tags, in the Functional Description.
Optimising Booleans
The boolean operation can be optimised, depending on the configuration of
the target and tool bodies, when additional information is known
regarding tool bodies not clashing with each other, or not clashing with
edges on the target body.
This optimisation is enabled by the options no_tool_intersect and
no_loop_intersect within the configuration options'. These
apply not only to instancing operations, but also to booleans with
multiple tools which need not be instances of the same body.
o If the no_tool_intersect option is set, the edges of each tool
body may clash with the edges of the target body, but the tool bodies
must not clash with each other.
o If the no_loop_intersect option is set, the tool bodies may clash
with each other, but must not clash with existing edges on the
target body.
A combination of both options will ensure no edge intersection tests are
performed between the target and tool bodies.
Error Reporting
When an error occurs the function will, where possible, make extra
information related to the error available to the application via the
standard form of the error. This information will consist of either a
single or a group of topological or geometric entities.
The error entity is accessible from the standard form of the error. If
an error code is returned by the PK function, the application may retrieve
the tag of the entity via a call to the function, PK_ERROR_ask_last. The
tag is returned in the entity field of the standard form of the error.
The returned entity may be one of the following entity types :
o Topology - Bodies, faces, edges, etc. may be returned in an attempt
to localise the reason for the PK error.
o Geometry - Surfaces may be returned by sectioning operations to
indicate the source of the PK error.
o Groups - Groups containing any of the above entities, including other
groups, may be returned if a set of entities resulted in
the PK error.
The sub-groups provide a mechanism for grouping entities
which are related in the context of the PK error.
Note:
If a group is returned as a result of an error :
1. The members of a group may be entities which existed before the
call (and so will survive rollback), the group itself will be
destroyed by rollback.
2. If the application does not perform a rollback, it is the
applications responsibility to delete the group and its
sub-groups.
Option Restrictions
The following options within the input options are
ignored by this function :
o check_fa
o default_tol
o max_tol
o tracking
The following options within configuration options are
ignored by this function :
o identical_intersect
o one_in_all_in
