PK_ERROR_code_t PK_FACE_hollow
(
--- 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
PK_LOGICAL_t face_face_check, --- do face face checks
--- returned arguments ---
PK_FACE_t *const new_faces --- new faces
)
This function hollows a solid body by offsetting the given faces by the
given offsets.
NOTE: this function is obsolete and has been superseded by PK_FACE_hollow_2.
Specific Errors:
PK_ERROR_cant_hollow hollowing failure
PK_ERROR_bad_tolerance proposed edge tolerance is too small
PK_ERROR_unsuitable_entity body is not a solid body
PK_ERROR_bad_thickness total thickness is zero
PK_ERROR_cant_get_point failed to find vertex geometry
PK_ERROR_cant_get_curve failed to find edge geometry
PK_ERROR_cant_offset surf failed to offset or face could not
be deleted
PK_ERROR_cant_get_side_surf failed to find side surface
PK_ERROR_cant_get_side_curve failed to find side curve
PK_ERROR_obsolete_function function not suitable for particular case
Introduction
The body is hollowed. The offset argument gives the default offset of the
hollowing - the thickness of the skin of the resulting body. A positive
offset will offset the body outwards (i.e. in the direction of the face
normals) and a negative value inwards.
The result of hollowing a body will be to generate a body containing a void.
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.
Many circumstances can give rise to changes in topology. Amongst them are :
1) Dealing with geometry which fails to offset. If it is known that the
offset surface of a face would be self-intersecting an attempt is made
to remove the offset face. For example, a blend may be removed
from an edge. The investigation of self-intersection is not exhaustive,
however, and it can occur that instances are not trapped.
2) Dealing with configurations which can be repaired. For instance,
an edge can offset to a point or a face can become absorbed into
the body.
Checking options
The extent to which checking is applied to the body is specified by the
face_face_check argument. If face_face_check is true then
face-face checks are done on the body in addition to default checks.
For most applications setting face_face_check false will give an
adequate level of checking.
Old_faces and new_faces returns arguments
The tag of a face in the original body will remain on the exterior of the
resulting body and will retain the same sense.
Each face to be offset will have a partner created in the final body which is
an offset of the original face. The interior faces corresponding to the
given faces are returned in new_faces.
If the hollowing algorithm encounters a situation that will produce a one
to many relationship between faces on the exterior and interior (or vice-versa)
of the final body, then this function will fail with the error:
PK_ERROR_obsolete_function. For such cases, this function's successor,
PK_FACE_hollow_2, must be used.
Error handling
When an error occurs, the function will, where possible, make extra
information regarding the error available to the application
by means of a GROUP.
This GROUP is accessible from the standard form of the error. Note that,
while the members of the GROUP will be objects which existed before the
call (and so will survive rollback), the GROUP itself will be destroyed by
rollback. The members of the GROUP will be as follows:
PK_ERROR_cant_get_point 1 VERTEX Failed to find new geometry for
existing vertex
n FACEs Failed to find geometry for
new vertex.
PK_ERROR_cant_get_curve 1 EDGE Failed to find new geometry for
existing edge
n FACEs Failed to find geometry for
new edge
PK_ERROR_cant_get_surf n FACEs Unable to produce isocline
surfaces for these faces.
No surface replacement is
performed.
PK_ERROR_edge_didnt_vanish 1 EDGE An existing edge should have
disappeared
n FACEs A transient edge should have
disappeared
PK_ERROR_face_check_fails 1 FACE Face which failed check
PK_ERROR_face_face_check_fails 2 FACEs Pair of faces where
inconsistency found.
PK_ERROR_cant_offset 1 FACE Failed to offset or face could
not be deleted
This function is not supported for general bodies.
