 |
PK_FACE_boolean |
|
PK_ERROR_code_t PK_FACE_boolean
(
--- received arguments ---
int n_targets, --- number of target faces
const PK_FACE_t targets[], --- target faces
int n_tools, --- number of tool faces
const PK_FACE_t tools[], --- tool faces
const PK_FACE_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 list of faces
of a target body and the list of faces of a tool body.
NOTE: This function is obsolete and has been superseded by PK_FACE_boolean_2.
Specific Errors:
PK_ERROR_contradictory_request Bad combination of options or data for
type of boolean
PK_ERROR_same_tool_and_target Tool body is also target body
PK_ERROR_missing_geom Target or tool has incomplete
geometry
PK_ERROR_duplicate_tools Duplication in list of tool faces
PK_ERROR_duplicate_targets Duplication in list of target faces
PK_ERROR_instanced_tools Instanced tool bodies
PK_ERROR_targ_faces_many_bodies Target faces are from more than
one body
PK_ERROR_tool_faces_many_bodies Tool faces are from more than one body
PK_ERROR_unsuitable_topology A region selector is from boundary,
wrong body or ambiguous
PK_ERROR_cant_unite_solid_sheet Attempt to unite solid and sheet
PK_ERROR_opposed_sheets Attempt to unite opposed sheets
PK_ERROR_cant_intsc_solid_sheet Cant intersect solid target with
sheet tool bodies
PK_ERROR_t_sheet Operation would result in a T-sheet
PK_ERROR_non_manifold Non-manifold result
PK_ERROR_boolean_failure Inconsistent arguments, or
internal error
PK_ERROR_partial_no_intersect No imprinting in face boolean
PK_ERROR_general_body Target or tool is general body
PK_ERROR_invalid_match_region Invalid matched topology data
Introduction
A boolean operation between the target faces and the tool faces is
performed. The bodies associated with the given faces are actually
booleaned, the faces are provided as a means to localising the
boolean operation. The target body is modified and the tool body
is deleted. The resulting body or bodies replace the target, and
are returned in an array.
A boolean based on faces is faster than a boolean based on bodies as
it involves the comparison of only the face pairs given in targets
and tools. The drawback being that topological consistency in
the result cannot be guaranteed.
This function operates similarly to the PK_BODY_boolean function,
especially with regard to the phases of the boolean algorithm,
rules concerning tag persistence, optimisation issues and error
reporting.
The effect of the fence option is identical to the fence option
used by the PK_BODY_boolean function. Refer to the PK_BODY_boolean
documentation for information about these subjects.
Face Booleans
In a face boolean, only the edges of intersection of the given faces are
imprinted, unless the extend_face_list or stop_self_intersection
options are set. The loops of imprinted edges divide the boundary of
both bodies into facesets.
For a body boolean all the facesets of the tool bodies lie
completely inside or outside the target body. However, this is not
necessarily the case for a face boolean, as not all faces of
both bodies are used to compute the imprinted edges. For a face boolean,
boundary facesets of the tool body are classified inside if they are
locally inside the target body near a loop of imprinted edges, and
outside if they are locally outside near the loop of imprinted edges.
o The extend_face_list option may be set to ensure that the imprinted
loops are complete.
o The stop_self_intersection option may be set to eliminate the
possibility of self intersecting results.
In a face boolean unite, boundary facesets of the tool body which are
outside the target body are glued to the target. Whilst for subtract and
intersect operations, only boundary facesets of the tool body
inside the target body are used.
Select Regions
It is also possible for a face boolean to use a subset of these
boundary facesets in computing the result. The subset of tool faces
is specified within the select_region options of the boolean
options. These faces can be excluded or included by setting the
value of the select_type option to the appropriate value.
The following restrictions are imposed :
o All the selected regions are either excluded or included. It is
not possible to exclude some faces and include other faces.
o The selected regions must be from the tool body.
o Each faceset must be unambiguously identified by a face, edge or
vertex which is interior to the faceset.
Help points
It may not always be possible to unambiguously specify a faceset
with a select region based on a face. This situation may be
avoided by being able to specify a point and a face. The point
specifying the region of interest within a given face.
The help points are passed to this function via the help_points
array within the select_region option structure.
The following retrictions apply to help points :
o A help point can only be associated with a face.
o The help point must lie on the face.
o The face/help point combination must uniquely identify a faceset
otherwise a PK_ERROR_unsuitable_topology error will be returned.
Boolean Restrictions
The following restrictions apply to face boolean operations :
o The targets argument must contain one or more faces from a single body,
and tools must contain one or more faces from another body.
o Face boolean operations can only be performed with generalised
topology disabled.
o There must be at least one intersection between the given topology of
the target and tool (i.e. at least 1 face pair must clash). If this
is not the case the boolean will not be performed and the error
PK_ERROR_partial_no_intersect will be returned.
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