 |
PK_BODY_section_with_sheet_2 |
|
PK_ERROR_code_t PK_BODY_section_with_sheet_2
(
--- received arguments ---
PK_BODY_t target, --- body to be sectioned by sheet
PK_BODY_t sheet, --- sectioning sheet body
const PK_BODY_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 the target body with the tool sheet body.
Specific Errors:
PK_ERROR_contradictory_request Bad combination of options or
data for type of boolean (MILD)
PK_ERROR_missing_geom Target or tool has incomplete
geometry (SERIOUS)
PK_ERROR_wire_body Tool is a wire body, or target is
a wire body and general topology
is not enabled (MILD)
PK_ERROR_partial_coi_found Boolean failure due to to partial
coincidence (SERIOUS)
PK_ERROR_general_body Tool is a general body, or target is
a general body and general topology
is not enabled (MILD)
PK_ERROR_same_tool_and_target Tool body is also target body (MILD)
PK_ERROR_not_sheet Tool is not a sheet body (MILD)
PK_ERROR_instanced_tools Instanced tool bodies (MILD)
PK_ERROR_boolean_failure Inconsistent arguments, or
internal error (SERIOUS)
Introduction
The given target body is sectioned with the given tool sheet body. The target
body is modified and the sectioning sheet body is deleted.
When the sectioning 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.
Target bodies, or disjoint components of the target body, that do not
clash with the section sheet will be left unchanged. It is not defined
whether they will be returned in the front_bodies or in the back_bodies
array.
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_BODY_boolean_2' function,
especially with regard to the phases of the boolean algorithm and rules
concerning tag persistence. Refer to the 'PK_BODY_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
Tracking Information
If tracking information is requested by the 'tracking' option, the 'tracking'
structure contains topology tracking information on the operation. In the
case of this function, tracking information is returned for edges imprinted
on the 'target'.
For any imprinted edge returned in the structure:
o the 'track' field will have the value PK_TOPOL_track_derive_c, and
o the 'product_topols' array will contain the imprinted edge.
o For 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
o two original faces for which the product edge is the
intersection, or
o a face and an edge where the imprint was along a pre-existing
edge on one of the bodies, or
o two edges where the imprint was along a pre-existing edge on
both bodies.
For any wire edge of a general target body that is sectioned the
following records will be returned,
o A record with 'track' set to PK_TOPOL_track_derive_c, 'original_topols'
containing the original wire edge, and 'product_topols' containing the
derived edges from the splitting of this edge.
o For each new vertex created: a record with 'track' set to
PK_TOPOL_track_derive_c, 'original_topols' containing the original
wire edge and the intersecting sheet topology, and 'product_topols'
containing the new vertex.
Sectioning with Generalised Topology Enabled
If generalised topology is enabled, Parasolid will perform sections on a
general target body and will allow any resultant body or bodies to be general.
However the tool body must be manifold (it may be a disjoint manifold body).
When a target face is coincident with the section sheet, its behaviour
depends on the solidity of its neighbouring regions. If one of the face's
neighbouring regions is solid and the other is void, then the face will
appear only on the side of the section where its solid region lies. But if
both of its neighbouring regions have the same solidity (i.e. they are both
solid or both void), or if the face is surrounded on both sides by the same
region, then the face will be copied. If the normals of the target face and
the section sheet are parallel then the original face will appear in the
front body and the copy will appear in the back body. Otherwise (if the
normals of the target face and the section sheet are antiparallel) then
the copy will appear in the front body and the original face will appear
in the back body.
If it is not possible to classify a sectioned body as "front" or "back",
a PK_REPORT_r_t will be produced. The report record(s) will be of type
PK_REPORT_record_1_t, as follows:
o For successful operations:
o PK_REPORT_1_cut_unclassed_c will be produced if any sectioned body is
both in front of and behind the sectioning sheet.
o PK_REPORT_1_cut_no_clash_c will be produced if any component of the
target body does not clash with the sheet.
o For failing operations:
o PK_REPORT_1_cut_incomplete_c will be produced if any component of the
target body is not fully sectioned by the sheet. Note: The sheet must
protrude from the target on all sides; exactly fitting sheets will
trigger this report and cause the operation to fail.