PK_ERROR_code_t          PK_FACE_remove_to_solid_bodies
(
--- received arguments ---
int                      n_faces,             --- number of faces
const PK_FACE_t          faces[],             --- faces
PK_FACE_heal_t           parent_heal_action,  --- method for healing wounds
PK_FACE_heal_t           child_heal_action,   --- method for healing wounds
PK_LOGICAL_t             local_check,         --- whether to do local check

--- returned arguments ---
int               *const n_parent_bodies,     --- number of parent bpdies
PK_BODY_t        **const parent_bodies,       --- parent bodies
PK_local_check_t **const parent_check_results,--- results of local check
int               *const n_child_bodies,      --- number of child bodies
PK_BODY_t        **const child_bodies,        --- child bodies
PK_local_check_t **const child_check_results  --- results of local check
)


This function separates a body into two or more bodies by selecting which
faces are to be removed into new bodies.


Specific Errors:

    PK_ERROR_wire_body              (MILD) unable to make solid from wire body
    PK_ERROR_dont_make_solid        (MILD) can't make solid from given faces
    PK_ERROR_non_manifold           (MILD) can't heal wound with non-manifold
                                           boundary
    PK_ERROR_not_in_same_part       (MILD) faces not all from same body
    PK_ERROR_general_body           (MILD) faces come from general body
    PK_ERROR_bad_selection_code     (MILD) a disallowed heal action has been
                                           requested
    PK_ERROR_cant_heal_wound        (MILD) cannot heal wound - impossible
                                           geometry
    PK_ERROR_all_faces_in_body      (MILD) cannot remove all faces from body
    PK_ERROR_not_implemented        (MILD) parent_heal_action or
                                           child_heal_action not implemented


All of the given faces, which must belong to the same body, are removed into
one or more new bodies.
A new body is created from each set of connected faces in the given set of
faces and from each set of connected faces remaining from the original body.
Bodies arising from the given set of faces are referred to as child_bodies
and bodies arising from the remaining faces are referred to as parent_bodies.

The faces must not form the shell of a sheet body.  If the faces form an
interior (void) shell of a solid, then that shell is removed into a solid.
If a resulting body does not have a complete boundary, then any
holes are treated as wounds which are healed as specified by a heal action.
For parent bodies parent_heal_action may take the values:

    PK_FACE_heal_no_c               don't heal wounds - leave rubber faces
    PK_FACE_heal_cap_c              find a surface in which all edges of a hole
                                    lie and attach this to a face covering the
                                    hole
    PK_FACE_heal_grow_from_parent_c grow the faces the parent had around the
                                    hole until they cover it

For child bodies child_heal_action may take the values:

    PK_FACE_heal_no_c               don't heal wounds - leave rubber faces
    PK_FACE_heal_cap_c              find a surface in which all edges of a hole
                                    lie and attach this to a face covering the
                                    hole
    PK_FACE_heal_grow_from_child_c  faces around the hole are extended until
                                    they cover the hole
    PK_FACE_heal_grow_from_parent_c grow the faces the parent had around the
                                    hole until they cover it

The local_check argument specifies whether checks on newly created
topological and geometrical entities are to be performed, and the
parent_check_results and child_check_results arguments return the result
of such checks.
These arguments may take the values:

    PK_local_check_no_c             local checking not performed either because
                                    local_check was PK_LOGICAL_false or the
                                     heal action was PK_FACE_heal_no_c
    PK_local_check_ok_c             body passes local checks
    PK_local_check_negated_c        as initially created, body was inside out
                                    but it has been negated and is now valid
    PK_local_check_failed_c         body fails local checks - it is
                                    self-intersecting

Rubber faces can not be grown to heal other wounds.

This function will not operate on faces from a general body.