 |
PK_FACE_boolean_2 |
|
PK_ERROR_code_t PK_FACE_boolean_2
(
--- 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 [PF]
--- 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 list of faces
of a target body and the list of faces of a tool body.
This function offers partial support for facet geometry [PF]
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_duplicate_tools Duplication in list of tool faces
(MILD)
PK_ERROR_duplicate_targets Duplication in list of target faces
(MILD)
PK_ERROR_instanced_tools Instanced tool bodies (MILD)
PK_ERROR_targ_faces_many_bodies Target faces are from more than
one body (MILD)
PK_ERROR_tool_faces_many_bodies Tool faces are from more than one body
(MILD)
PK_ERROR_unsuitable_topology A region selector is from boundary,
wrong body or ambiguous (MILD, SERIOUS)
PK_ERROR_cant_unite_solid_sheet Attempt to unite solid and sheet
(MILD)
PK_ERROR_cant_intsc_solid_sheet Cant intersect solid target with
sheet tool bodies (MILD)
PK_ERROR_partial_no_intersect No imprinting in face boolean (MILD)
PK_ERROR_boolean_failure Inconsistent arguments, or
internal error (SERIOUS)
PK_ERROR_unsupported_operation Target or tool faces do not belong to
a sheet body when completing imprint.
(MILD)
PK_ERROR_cant_complete_imprint unable to complete the imprint
(SERIOUS)
PK_ERROR_cant_limit_faces The 'limit_target_faces' and the
'limit_tool_faces' can only be used
with a limited set of operations
and bodies. They are not supported
for this operation.
(MILD)
PK_ERROR_bad_combination A mixture of facet and classic geometry
has been supplied (MILD)
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 within a return structure.
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_2 function,
especially with regard to the phases of the boolean algorithm,
rules concerning tag persistence, optimisation issues and status
reporting.
The effect of the 'fence', 'target_material_side', 'tool_material_side' and
'resulting_body_type' options are identical to the same options used by the
PK_BODY_boolean_2 function. Refer to the PK_BODY_boolean_2 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 one body are classified inside if they are locally inside
the other 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. This is modified if facesets from the target
are selected, see Select regions in boolean operations for more
information.
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 faces from either
or both the target and the tool 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 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.
Tracking Information
The 'tracking' structure contains topology tracking information on the
operation. In the case of this function, tracking information for edges
from 'target' involved in the imprint is returned.
For any new edge returned in the structure the 'track' field has the value
PK_TOPOL_track_derive_c and the single edge in 'product_topols'
originated in the 'n_original_topols' entities in 'original_topols'.
The entity type of each of these is recorded in 'original_classes'
array. In most cases this is either 2 original faces for which the
product edge is the intersection, or a face and an edge or two edges where
the imprint was along a pre-exisiting edge on one or other or both bodies.
Imprinted edges arising from any requested imprint completion are tracked
by the same method. The original topology associated with the body upon
which the completion is occurring is tracked as normal. The topology upon
the other body i.e. that which is implied to cause the imprint is handled
slightly differently. The topology upon this body which causes the imprint
of the vertex from which completion occurs is tracked. This topology will
either be a pre-existing vertex upon that body or an edge of the body
causing the imprinted vertex when imprinted upon the other body, note this
edge will only be coincident with the imprint at the point associated with
the completion vertex.
Tracking records detailing edges which arise from use of the
'limit_target_faces' or 'limit_tool_faces' options will contain topology
information for one body only, where the associated originating topology
on that body will arise directly from the limited set of faces used from
that body. The limiting of the face set having been the cause for the
edge's creation.
Option Restrictions
The following options within 'configuration' options are
ignored by this function :
o 'identical_intersect'
o 'one_in_all_in'