 |
PK_FACE_instance_bodies |
|
PK_ERROR_code_t PK_FACE_instance_bodies
(
--- received arguments ---
int n_target_faces, --- number of target faces
--- (>0)
const PK_FACE_t target_faces[], --- target faces
int n_tool_bodies, --- number of tool bodies
--- (>0)
const PK_BODY_t tool_bodies[], --- tool bodies to be
--- instanced
const PK_TRANSF_array_t transforms[], --- instancing transforms
const PK_FACE_instance_bodies_o_t *options,
--- returned arguments ---
PK_TOPOL_track_r_t *const instance_tracking,
--- tracking records
--- for instances
PK_TOPOL_track_r_t *const tracking --- tracking records
--- for topology
)
This function instances (creates and then booleans transformed copies of...)
tool bodies with a single target body.
Specific Errors
PK_ERROR_unsuitable_entity Arguments not of correct type
(MILD or SERIOUS)
PK_ERROR_targ_faces_many_bodies Target faces are from more than one body
(MILD)
PK_ERROR_general_body Target or tool is a general body
(MILD)
PK_ERROR_same_tool_and_target Target body cannot also be a tool body
(MILD)
PK_ERROR_duplicate_array_item Duplicate face in target or duplicate
body in tool array
(MILD)
PK_ERROR_tool_generation Problems instancing tool, tools may clash
(MILD or SERIOUS)
PK_ERROR_instanced_tools Tool is instanced within an assembly
(MILD)
PK_ERROR_invalid_bodies Boolean failure or invalid bodies
(SERIOUS)
PK_ERROR_non_manifold Result is non-manifold
(SERIOUS)
PK_ERROR_missing_geom A topological entity lacks geometry
(SERIOUS)
PK_ERROR_cant_do_imprint Imprint failure
(SERIOUS)
PK_ERROR_partial_coi_found Failure due to detection of partial
coincidence
(SERIOUS)
PK_ERROR_partial_no_intersect No imprinting in a local boolean
(MILD)
PK_ERROR_boolean_failure Inconsistent arguments or internal error
(MILD or SERIOUS)
PK_ERROR_not_implemented Requested operation is not
implemented
(MILD)
PK_ERROR_cant_limit_faces The option 'limit_target_faces'
can only be used with a limited set of
operations and bodies. The supplied option
set is not supported for this operation
(MILD)
PK_ERROR_cant_intsc_solid_sheet Can't intersect solid target with
sheet tool bodies (MILD)
PK_ERROR_cant_unite_solid_sheet Attempt to unite solid and sheet
(MILD)
PK_ERROR_unsupported_transf Unsupported type of transform
(MILD)
The tool bodies are not modified by the boolean: all instanced occurrences in
the resultant body are copies created during the operation.
Each tool body is instanced by applying the corresponding array of transforms
supplied in the array of arrays of transforms, 'transforms'.
Body Instancing Restrictions
If the instanced tool bodies do not intersect, then for optimal performance
the field 'no_tool_intersect' in the configuration structure should have
the value PK_LOGICAL_true. However, incorrectly setting this to
PK_LOGICAL_true when instanced tool bodies do intersect may result in
invalidities or failures.
The effect of the 'target_material_side', 'tool_material_side',
'limit_target_faces', 'imprint_complete_targ',
'imprint_complete_tool' and 'extend_face_list' options and their
interactions are identical to the same options used by the
PK_FACE_boolean_2 function. Refer to the PK_FACE_boolean_2 documentation
for information about these subjects.
Returned Tracking Information
If the 'tracking_type' option is set to PK_instance_track_type_none_c
no tracking information will be returned.
Tracking is returned in two separate tracking structures,
'instance_tracking' and 'tracking'.
Tracking information associated with instances is returned. An instance is
tracked by a pair of entities, one being the original tool body and one the
transform applied to generate that instance.
The 'tracking' structure contains topology tracking information on the
operation. Information is returned in the 'tracking' structure, if
'tracking_type' is set to PK_instance_track_type_topol_c or
PK_instance_track_type_both_c. The first record contains product
topology consisting of all the resultant bodies, this is of particular
use in scenarios where the target body is split.
The remaining records in 'tracking' will contain information regarding
newly created topology. New faces and edges will be tracked to the
underlying topologies used to create them upon the original tool and
target along with the tracking information associated with the relevent
instance.
The 'instance_tracking' structure contains tracking regarding the
resultant faces arising from each instance. For each instance a tracking
record is created with the originators being the tool body tag and the
the tag of the transform applied to it to yield the instance. The product
topologies contained in this record will be a list of all the resultant
faces arising from that instance. The instance tracking information will
be returned if 'tracking_type' is set to PK_instance_track_type_inst_c or
PK_instance_track_type_both_c.