PK_BODY_make_section_with_surfs

PK_ERROR_code_t                 PK_BODY_make_section_with_surfs
(
--- received arguments ---
int                             n_targets, --- number of target bodies
PK_BODY_t                       targets[], --- target bodies
int                             n_tools,   --- number of tool surfaces
PK_SURF_t                       tools[],   --- tool surfaces
const PK_BODY_make_section_o_t *options,   --- Sectioning options

--- returned arguments ---
PK_TOPOL_track_r_t       *const tracking,  --- tracking information
PK_BODY_make_section_r_t *const results    --- resultant bodies
)


This function generates sections of target bodies using set of tool surfaces.
Target bodies remain unchanged.



Specific Errors:
    PK_ERROR_contradictory_request      Bad combination of options or bad value
                                        for option 'result_body_type' (MILD)
    PK_ERROR_missing_geom               Target or tool has incomplete
                                        geometry (SERIOUS)
    PK_ERROR_wire_body                  Target is a wire body (MILD)
    PK_ERROR_non_manifold               Non-manifold result (SERIOUS)
    PK_ERROR_boolean_failure            Inconsistent arguments, or
                                        internal error (SERIOUS)
    PK_ERROR_general_body               Target is a general body (MILD)



Introduction
The given set of tool surfaces is used to generate sections of target bodies.
The target bodies remain unchanged.

Targets may be solid or sheet bodies.

When targets are imprinted on tool surfaces, new tool faces will be generated.
After imprinting, any tool faces that are inside target bodies are
retained, and any tool faces that are outside target bodies are deleted. If
this results in the resultant body being split into several disjoint manifold
components, 'allow_disjoint' in the options structure controls whether the
body is split or not.

The operation of the sectioning may be controlled via a set of options passed
to the function as an input argument.

Output of the operation is returned in the 'results' structure.

When the optional argument 'offsets' is used to section a solid body, the
curve tangent direction in the resultant bodies will be set so that the
solid region of the originating target is on the left. Here, "left" is defined
relative to a forward and vertical direction. The forward direction is
the resultant curve tangent and the vertical direction is the
tool surface normal.

See Non-destructive sectioning for more information.

Section Options
If the 'tracking' option is set to PK_LOGICAL_true, then tracking information
for all faces and edges from 'bodies' in 'results' is returned.

If the 'allow_disjoint' option is set to PK_LOGICAL_true, then 'bodies' in
'results' may contain disjoint manifold components.
If this option is set to PK_LOGICAL_false, resultant bodies having disjoint
manifold components will be split such that every resultant body has a single
manifold component.

'result_body_type' can either be PK_BODY_type_sheet_c or PK_BODY_type_wire_c.
If 'result_body_type' is PK_BODY_type_wire_c, attempts will be made to ensure
that 'bodies' contains valid wire bodies, i.e no vertex has more than two
edges meeting.


Returned Arguments
Tracking

The 'tracking' structure contains topology tracking information on the
operation. In the case of this function, tracking information for all the
faces and the edges from 'bodies' is returned.

For the faces, the PK_TOPOL_track_t structure in 'tracking' will be of type
PK_TOPOL_track_create_c. 'original_topols' will contain the tag of the surface
from the 'tools' that was imprinted to create the face.
For the faces 'n_original_topols' will be 1.

For the edges, the PK_TOPOL_track_t structure in 'tracking' will be of type
PK_TOPOL_track_create_c. 'original_topols' will contain the tag of the target
face and tool surface. If the edge is coincident with the target edge,
tag of the target edge will be returned. The first entity will be from the
target body and second entity will be tool surface.
For the edges 'n_original_topols' will be 2.

Status and Fault Reporting

The 'results' structure contains resultant bodies and additional information,
if any about the operation.

If the function returns 'PK_ERROR_no_errors', then resultant bodies will be
contained within the 'bodies' array.

If the 'n_offsets' option is set greater than zero and all the offsets
are distinct then any 'bodies' returned in the 'results' returned argument
will be returned in the order that their corresponding offset values were
supplied in the 'offsets' option array.


The 'reports' will provide information about non-manifold or other invalid
sections.

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

If 'report' is PK_boolean_report_non_manifold_c, the invalid section body will
be returned in 'entities' array.

Function Restrictions
The following restrictions apply to the sectioning operation :

   o Targets can be solid bodies or sheet bodies.
   o This function supports general bodies only if the optional argument
     'offsets' is used.