PK_ERROR_code_t PK_BODY_boolean_2
(
--- 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 ---
PK_TOPOL_track_r_t *const tracking, --- tracking information
PK_boolean_r_t *const results --- boolean results
)
This function performs a boolean operation between the target body
and the list of tool bodies.
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 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 can't intersect solid target with
sheet tool bodies (MILD)
PK_ERROR_boolean_failure inconsistent arguments, or
internal error (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 within a results structure.
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.
Status and Fault Reporting
If the function returns an error code, PK_ERROR_duplicate_tools for example,
none of the return arguments of the function will be set. This is standard
practice for the PK interface. However, this is not the only mechanism by
which this function may indicate that a failure has occurred. The results
structure may return failure related information as well.
Whenever the function returns PK_ERROR_no_errors, the application must
inspect the contents of the results structure to check on the status of
the boolean operation. The result field of the results structure will
indicate the overall status of the boolean operation. If any bodies are to
be returned to the application, these will be contained within the bodies
array. If the results field indicates a failure, the reason(s) for the
failure will be contained within the array of report structures, referenced
via the reports field.
The meaning and implied actions of the result field is as follows :
1. PK_boolean_result_ok_c
o The boolean succeeded and the resultant entities are returned within
the bodies array.
2. PK_boolean_result_no_clash_c
o The boolean succeeded and the resultant entities are returned within
the bodies array. However, the target and tool entities did not
interact or clash in any manner.
3. PK_boolean_result_fail_c
o The boolean has failed.
o The bodies array will returned as null.
o The report structures must be inspected to determine the reason for the
failure and to identify the location of the failure.
o If this status is returned, the application cannot assume that the input
bodies are in a valid state.
Each report structure contains a report field indicating the reason for the
failure and, if possible, an array of entities. These entities may assist the
application in identifying the region or entities that resulted in the failure.
The entities array may contain topology from the target and tool bodies. The
entities returned in the array will be members of the following classes :
o PK_CLASS_body
o PK_CLASS_shell
o PK_CLASS_face
o PK_CLASS_edge
o PK_CLASS_vertex
NOTE: If the result field is set to PK_boolean_result_fail_c, the
application must not assume that the input bodies are in a valid
state.
Tracking Information
The returned tracking structure is for future enhancements. Currently, the
structure will always be returned with empty arrays.
Option Restrictions
The following options within the input options are
ignored by this function :
o tracking
The following options within configuration options are
ignored by this function :
o identical_intersect
o one_in_all_in
