PK_BODY_section_with_surf

PK_ERROR_code_t            PK_BODY_section_with_surf
(
--- received arguments ---
PK_BODY_t                  target,        --- Body to be sectioned by surface
PK_SURF_t                  surface,       --- Sectioning surface [PF]
const PK_BODY_section_o_t *options,       --- Sectioning options

--- returned arguments ---
PK_section_r_t      *const results        --- front/back faces/bodies
)


This function sections the target body with the tool surface.

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
    PK_ERROR_missing_geom               Target or tool has incomplete
                                        geometry
    PK_ERROR_wrong_surface              Surface not a plane or cylinder
    PK_ERROR_wire_body                  Tool is a wire body, or target is
                                        a wire body and general topology
                                        is not enabled
    PK_ERROR_partial_coi_found          Boolean failure due to to partial
                                        coincidence
    PK_ERROR_non_manifold               Non-manifold result
    PK_ERROR_boolean_failure            Inconsistent arguments, or
                                        internal error
    PK_ERROR_general_body               Tool is a general body, or target is
                                        a general body and general topology
                                        is not enabled
    PK_ERROR_bad_combination            A mixture of facet and classic geometry
                                        has been supplied




Introduction
The given target body is sectioned with the given tool surface. If the
'target' has classic geometry, the tool surface may be of class
PK_CLASS_plane or PK_CLASS_cylinder; if it has facet geometry, the tool
surface may be of class PK_CLASS_plane or PK_CLASS_mesh.

When the section surface intersects with the target body, the body will
be split, by the section surface, into two or more parts. The resulting
bodies are split into two lists, those in front of the section surface
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 surface are returned in the
'front_faces' and 'back_faces' arrays of the 'results' structure.

The front of the section surface is regarded as the side to which the
surface normal points.

Target bodies, or disjoint components of the target body, that do not
clash with the section surface 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 surface 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' function,
especially with regard to the phases of the boolean algorithm,
rules concerning tag persistence and error reporting. Refer to
the 'PK_BODY_boolean' 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 surface.
o Only calculate the bodies and faces behind the section surface.
o Calculate the bodies and faces in front and behind the section surface.


Returned Arguments
Refer to the 'PK_section_r_t' documentation for information
about the arrays returned in the 'results' structure.


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.

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 a component of the target body is not sectioned by the surface,
a PK_REPORT_r_t will be produced, with report record(s) of type
PK_REPORT_record_1_t. The report status will be PK_REPORT_1_cut_no_clash_c.


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'