PK_ERROR_code_t PK_FACE_hollow_2
(
--- 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 ---
int *const n_new_faces,
PK_FACE_t **const old_faces, --- old faces ( optional )
PK_FACE_t **const new_faces --- new faces ( optional )
)
This function hollows a solid body by offsetting the given faces by the
given offsets.
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
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.
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. It it is known that the
offset surface of a face would be self-intersecting an attempt is made
to either remove the offset face or split it into faces with good
regions of the failing surface. 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 pairs of original and new faces are
returned in the old_faces and new_faces arguments. Both old_faces and
new_faces can contain null tags. This will occur when faces
are removed for the reasons given above.
When a face has been split, so a single face in one array corresponds to two or
more faces in the other array, then the single face is repeated to correspond
to each of the split faces. If the split face is on the outside of the
resultant body then the first face in 'old_faces' corresponding to a repeated
face in 'new_faces' will retain the tag of the original face that was split.
The order of original face tags in old_faces is the same as in faces. If
n_new_faces is returned equal to n_faces then no splitting has occurred.
Note that even when no splitting has occurred, it is still possible that
faces on the outside of the body have been deleted (old_faces contains
PK_ENTITY_null) and so there is still not necessarily a one to one
correspondence between faces and new_faces.
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.
