PK_ERROR_code_t                PK_BODY_trim_neutral_sheets
(
--- received arguments ---
PK_BODY_t                      body,             --- the target body
int                            n_pairs,          --- the number of pairs
const PK_FACE_set_pair_t       pairs[],          --- array of pairs
double                         tol,              --- tolerance for curves

--- returned arguments ---
PK_BODY_t                      neutral_sheets[], --- neutral sheets
PK_neutral_error_t             errors[],         --- status of neutral sheets
PK_FACE_neutral_causes_array_t causes[]          --- tracking information
)


This function trims the neutral sheets in accordance with their pairs
of face sets.




This function trims some neutral sheets as specified by
pairs.  All the faces in the facesets must belong to body, which
should be a solid.

The argument tol is used to specify a tolerance in case an
approximate curve is constructed by the function.  If it is zero, the
function will choose its own non-zero value.


The returned arrays neutral_sheets, errors and causes must be the same
length as the given array of pairs. Each entry in the returned arrays
will correspond to the pair in the same position in the input array.
Each body in neutral_sheets will be the same as the sheet body in
the same position in pairs.  The value of the entry in errors will
indicate the status of the corresponding sheet body in
neutral_sheets.  The possible values are as follows:

    Value                     Meaning
    -----                     -------
    PK_neutral_success_c         No problems were detected and a trimmed
                              neutral sheet has been returned.

    PK_neutral_illegal_input_c   Either a neutral sheet has not been
                              supplied, or a face has been used in
                              more than one pair.
    PK_neutral_numerical_failure_c
                              An error has occurred while trying to
                              find the trim curves and their
                              endpoints.  The returned neutral sheet
                              will not be trimmed correctly.

    PK_neutral_unknown_config_c  The disposition of pair faces and side
                              faces is not one which the algorithm
                              recognises.  This is a limitation.
    PK_neutral_imprint_failure_c
                              An error has occurred while imprinting
                              the trim curves onto the neutral sheet.
                              This often means there is a bug in
                              finding the trim curves.

Each entry in causes will be an array containing the tracking
information for the corresponding neutral sheet, each element of this
array being the information for a face in the neutral sheet.

Where trimming has failed, the neutral sheet may have changed and may
have new edges scribed onto it.

If the face set pairs are incomplete for the body, it is possible that
the sheet not be trimmed properly, even though the status is
PK_neutral_success_c.  It is also possible that a neutral sheet will
become disconnected.  If this happens it will be converted to a
general body.