 |
PK_BODY_hollow_2 |
|
PK_ERROR_code_t PK_BODY_hollow_2
(
--- received arguments ---
PK_BODY_t body, --- body to be hollowed
double offset, --- offset distance
double tolerance, --- tolerance
const PK_BODY_hollow_o_t *options, --- user 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 all faces of the body
by the given offset distance
NOTE : This function supersedes PK_BODY_hollow.
This function offers partial support for facet geometry [PF]
Specific Errors:
PK_ERROR_bad_tolerance proposed tolerance is too small (MILD)
PK_ERROR_unsuitable_entity body is not solid body or any face specified
via a field of the options which does not
belong to the body (SERIOUS)
PK_ERROR_bad_combination incompatible options specified as follows:
- a face appears in 'offset_faces' and in
'pierce_faces'
- a face appears in 'local_faces' and in
`pierce faces'
- a face appears in 'offset_faces' and in
'local_faces' when using exclude option
- PK_hollow_local_none_c and
'n_local_faces' > 0
- PK_hollow_local_add_c and
'n_local_faces' = 0
- PK_hollow_local_exclude_c and
'n_local_faces' = 0 (MILD)
PK_ERROR_bad_value invalid offset value (MILD)
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.
Faces which are not to be offset at all are defined in the 'pierce_faces'
array in the supplied option structure. Pierced faces remain only as a
section through the hollowed body. For instance, hollowing a cylindrical
solid with one end face pierced will result in a tube with one open and
one closed end.
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 Hollowing for more information.
User options
The PK_BODY_hollow_o_t structure contains user control options. See
its documentation for details.
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.