PK_ERROR_code_t PK_FACE_section_with_sheet_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_section_o_t *options, --- sectioning options
--- returned arguments ---
PK_TOPOL_track_r_t *const tracking, --- tracking information
PK_section_2_r_t *const results --- front/back faces/bodies
)
This function sections selected regions of the target body with
selected regions of the tool sheet body.
Specific Errors:
PK_ERROR_contradictory_request Bad combination of options or
data for type of boolean
PK_ERROR_missing_geom Target or tool has incomplete
geometry
PK_ERROR_wire_body Target or tool is a wire body
PK_ERROR_partial_coi_found Boolean failure due to to partial
coincidence
PK_ERROR_general_body Target or tool is general body
PK_ERROR_same_tool_and_target Tool body is also target body
PK_ERROR_instanced_tools Instanced tool bodies
PK_ERROR_not_sheet Tool is not a sheet body
PK_ERROR_unsuitable_topology A region selector is from boundary,
wrong body or ambiguous
PK_ERROR_partial_no_intersect No imprinting in face boolean
PK_ERROR_boolean_failure Inconsistent arguments, or
internal error
Introduction
The given target body is sectioned with the given tool sheet body.
When the section sheet body intersects with the target body, the body will
be split, by the sheet faces, into two or more parts. The resulting
bodies are split into two lists, those in front of the section sheet
and those behind it. These bodies are returned in the front_bodies and
back_bodies arrays of the results structure. All new faces associated
with these bodies which lie in the sectioning sheet are returned in the
front_faces and back_faces arrays of the results structure.
The front of the section sheet is regarded as the side to which the
face normals point.
Any body unaffected by the sectioning operation will be left unchanged,
but will be put into the appropriate array within the results structure.
The operation of the sheet sectioning function may be controlled via
an option structure passed to the function as an input argument.
This function operates similarly to the PK_FACE_boolean_2 function,
especially with regard to the phases of the boolean algorithm, the
region selectors and rules concerning tag persistence. Refer to the
PK_FACE_boolean_2 documentation for information about these subjects.
Section Options
The function can be instructed, via the fence option, to :
o Only calculate the bodies and faces in front of the section sheet.
o Only calculate the bodies and faces behind the section sheet.
o Calculate the bodies and faces in front and behind the section sheet.
Status and Fault Reporting
If the function returns an error code, PK_ERROR_not_sheet 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 section operation. The result field of the results structure will
indicate the overall status of the section operation. If any bodies or
faces are to be returned to the application, these will be contained within
the front_bodies, back_bodies, front_faces and back_faces arrays.
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_section_result_ok_c
o The section succeeded and the resultant entities are returned within
the appropriate arrays.
2. PK_section_result_no_clash_c
o The section succeeded and the resultant entities are returned within
the appropriate arrays. However, the target and tool entities did not
interact or clash in any manner.
3. PK_section_result_fail_c
o The section has failed.
o The result arrays 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_section_result_fail_c, the
application must not assume that the input bodies are in a valid
Tracking Information
The returned tracking structure is for future enhancements. Currently, the
structure will always be returned with empty arrays.
Function Restrictions
The following restrictions apply to sheet sectioning operations :
o This function does not support general bodies.
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
