PK_FACE_hollow_3

PK_ERROR_code_t           PK_FACE_hollow_3
(
--- received arguments ---
int                       n_faces,         --- number of faces
PK_FACE_t                 faces[],         --- faces to hollow
double                    offsets[],       --- offset distance for each face
double                    tolerance,       --- tolerance

const PK_FACE_hollow_o_t *options,         --- options [PF]

--- returned arguments ---
PK_TOPOL_track_r_t *const tracking,        --- tracking information
PK_TOPOL_local_r_t *const results          --- status information
)


This function hollows a solid body by offsetting the given 'faces' by the
given 'offsets'.

NOTE : This function supersedes PK_FACE_hollow_2.

This function offers partial support for facet geometry [PF]


Specific Errors:
    PK_ERROR_cant_hollow           (SERIOUS) hollowing failure
    PK_ERROR_not_unique            (SERIOUS) boolean resulted in more than
                                             one body
    PK_ERROR_boolean_failure       (SERIOUS) boolean failure
    PK_ERROR_bad_tolerance         (MILD) proposed edge tolerance is too small
    PK_ERROR_unsuitable_entity     (MILD) body is not a solid body
    PK_ERROR_wrong_entity_in_array (MILD) given faces are not from same body



Introduction
The 'body' is hollowed. The 'offsets' argument gives the offset distance
for each face. A positive offset will offset the body outwards (i.e. in the
direction of the face normals) and a negative value inwards.

Faces of the body which do not occur in 'faces' and faces of the body which
are given offset distances of 0.0 are pierced.

Under some circumstances the function may need to replace exact geometry by
tolerant geometry. For instance, a four-edge vertex in general will offset
to two three-edge vertices and a connecting edge. If this new edge is smaller
than the supplied tolerance then the vertex becomes tolerant and no new edge
is introduced. In all situations where approximation is required the new
geometry will have a tolerance less than or equal to the tolerance supplied
through the 'tolerance' argument.

See Offsetting specific faces in a body for more information.

User options
The PK_FACE_hollow_o_t structure contains user control options. See
its documentation for detail.

Tracking
The PK_TOPOL_track_t structure contains topology tracking information on
the operation. In the case of this function, two types of tracking information
records may be returned :
1)  PK_TOPOL_track_create_c, to report newly created offset faces (or faces
    deriving from them).
2)  PK_TOPOL_track_derive_c, to report faces deriving from existing ones,
    through any combination of splitting and merging.

Error handling
If this function returns PK_ERROR_no_errors, the result of the operation
will be indicated by the value of the 'status' field of the 'results'
structure. When this value is not PK_local_status_ok_c or
PK_local_status_nocheck_c, it indicates an operation failure and an array
of entities involved in this failure is returned through the field
'error_entities' of the 'results' structure, when possible.
For more information regarding the failure status code and the error_entities,
refer to the PK documentation of the PK_TOPOL_local_r_t structure.