 |
PK_BODY_extrude |
|
PK_ERROR_code_t PK_BODY_extrude
(
--- received arguments ---
PK_BODY_t profile, --- minimum, wire or sheet profile
--- to extrude
PK_VECTOR1_t path, --- direction of linear extrusion
const PK_BODY_extrude_o_t *options, --- options structure
--- returned arguments ---
PK_BODY_t *const body, --- resulting extruded body
PK_TOPOL_track_r_t *const tracking, --- tracking information
PK_TOPOL_local_r_t *const results --- status information
)
This function creates a new body by performing a linear extrusion of a given
profile.
Specific Errors:
PK_ERROR_distance_le_0 distance over which profile is to be
extruded is zero or negative (MILD)
PK_ERROR_unsuitable_entity profile is unsuitable for extrusion (MILD)
PK_ERROR_general_body can't extrude general body (MILD)
PK_ERROR_non_manifold can't extrude body with non-manifold
boundary (MILD)
PK_ERROR_impossible_sweep can't determine swept geometry (SERIOUS)
PK_ERROR_su_self_intersect extrusion would produce a self intersecting
surface (SERIOUS)
PK_ERROR_no_division bound does not divide extruded body
(SERIOUS)
PK_ERROR_no_nth_division nth division does not exist
(SERIOUS)
PK_ERROR_disjoint disjoint extruded body is not allowed
(SERIOUS)
PK_ERROR_not_implemented option not implemented
(MILD)
PK_ERROR_failed_to_bound extrude failed to stop at supplied bound
(SERIOUS)
PK_ERROR_distance_too_large extruded body would protrude outside the
size box (MILD/SERIOUS)
The new 'body' is created by extruding the given 'profile' body along the
given 'path' vector between two bounds.
The 'profile' may be a minimum, wire or sheet body, the resulting 'body' then
being a wire, sheet or solid body respectively.
For a profile with facet geometry, if a laminar edge of a sheet profile or any
edge of a wireframe profile self-intersects when viewed down the direction of
extrusion, then that edge will be split to avoid said self-intersection. This
does not apply if an 'extruded_body' is provided.
Bounds are defined in terms of extrusion divisions. An extrusion division is
where a potentially infinite body extruded in the direction of and in the
opposite direction to the 'path' vector would be divided into two.
An extrusion division may be a copy of the given 'profile' at a given distance
along the 'path', or it may be defined by the intersection between the
potentially infinite body and a given entity. Intersections with a given
entity which do not divide the infinite body in two in the direction of the
path are not extrusion divisions and are ignored.
The resulting 'body' is bounded in the 'path' direction by extrusion
divisions selected by the 'start_bound' and 'end_bound' fields of the options
structure. The 'forward' fields of the 'start_bound' and 'end_bound'
structures indicate whether each respective bound is on the side of the
'profile' in the positive direction of the 'path' or on the other side.
The given 'profile' will be contained in the result body if the 'start_bound'
of the 'options' has its 'forward' field set to PK_LOGICAL_false and the
'end_bound' of the 'options' has its 'forward' field set to PK_LOGICAL_true.
If both 'forward' fields are given the same value then the resulting 'body' is
entirely on one side of the given 'profile'.
The intersection between the potentially infinite body and a given entity
may produce more than one division. If the given 'profile' is contained in
the result 'body' then divisions are ordered by increasing distance from the
'profile'. When both bounds are on the same side of the 'profile' then
divisions for the bound nearest the 'profile' are ordered by increasing
distance from the 'profile', and divisions for the bound furthest from the
'profile' are ordered by increasing distance from the bound nearest to
the 'profile'. The ordering of divisions may be reversed ( 'nearest' field
of the 'start_bound' and 'end_bound' structures ) so that furthest rather than
nearest divisions may be selected.
If the bounding entities intersect the 'profile', the first division can be
specified using the 'side' field of the 'start_bound' and 'end_bound'
structures. For the option PK_bound_side_both_c, such profile divisions are
ignored. For PK_bound_side_out_c or PK_bound_side_in_c, the outside or inside
parts respectively of the bound entity at the profile are counted as the first
division.
If the start and end divisions intersect each other then the result 'body' is
undefined.
If the divisions produce a disjoint extrusion and the 'allow_disjoint' option
is PK_LOGICAL_true then the resulting 'body' will contain disjoint components.
The components will clash if the result would be non-manifold. In this case
the status will be set to PK_local_status_fa_fa_fail_c and the user should call
PK_BODY_disjoin on the resulting 'body'.
The 'end_bound' must be on the side of the 'start_bound' in the positive
direction of the 'path' vector.
The given 'profile' is unaffected by this function.
Pre-extruded body options:
If the option 'extruded_body' is not PK_ENTITY_null, this body is used to
create the resulting 'body' instead of extruding the 'profile' along the
'path'. Any extrusion divisions selected by the 'start_bound' and
'end_bound' must divide the 'extruded_body'.
The bound method PK_bound_distance_c cannot be used with this option.
PK_bound_none_c can be used with this option and indicates no extrusion
divisions for that bound.
The resulting 'body' is not guaranteed to have the same tag as
'extruded_body'. If the 'profile' is within the 'extruded_body' (i.e.
if the start bound is backward and the end bound is forward) then it
should be an exact section of 'extruded_body'. This lets you to specify
a region to include, and is necessary to resolve any ambiguities where
multiple solutions are possible. Otherwise spurious results may be
returned.
Tracking:
The PK_TOPOL_track_r_t structure contains track records of the type
PK_TOPOL_track_create_c.
When 'extruded_body' is PK_ENTITY_null:
For a sheet body 'profile' there is a track record for every face in
the result 'body'. For each face the original class may be:
- PK_CLASS_edge: the face is produced be sweeping an edge of the
'profile',
- PK_CLASS_face: the face is derived from a face of the 'profile' or
from a face of a bounding body,
- any subclass of PK_CLASS_surf: the face is produced from a surface
in a PK_bound_surf_c bound.
For a wire body 'profile', there is a track record for every face showing
the edge it has been swept from, and a track record for the bound edges
relating them to the bounds. For each bound edge the original class may
be:
- PK_CLASS_face: the edge was produced by intersection with the face
of a bounding body,
- PK_CLASS_edge: the edge was produced by intersection with a bounding
body which coincided with an edge of that bounding body, or the edge
was produced as a result of a PK_bound_distance_c bound from a profile
edge,
- any subclass of PK_CLASS_surf: the edge is produced by intersection
with a surface in a PK_bound_surf_c bound.
For a minimum body 'profile', there is a track record for the edge
relating it to the vertex it was swept from, and a track record for each
resulting vertex showing how that was obtained. For these vertices, the
original class may be:
- PK_CLASS_vertex: the vertex is produced by a PK_bound_distance_c
bound,
- PK_CLASS_face: the vertex is produced at an intersection with a face
at a PK_bound_face_c, PK_bound_body_c or PK_bound_sheet_c bound
- any subclass of PK_CLASS_surf: the vertex is produced at the
intersection with a surface given with a PK_bound_surf_c bound.
When 'extruded_body' is provided in the options structure:
If the 'extruded_body' is a solid body for each face the original class
may be:
- PK_CLASS_face: the face is derived from a face of the 'extruded_body'
or from a face of a bounding body.
- any subclass of PK_CLASS_surf: the face is produced from a surface
in a PK_bound_surf_c bound.
If the 'extruded_body' is a sheet body then track records are created for
all faces and edges of the result body. For each face of the
result body the original class may be:
- PK_CLASS_face: the face is derived from the face of the
'extruded_body'
For each edge the original class may be:
- PK_CLASS_face: the edge was produced by intersection with the face
of a bounding body,
- PK_CLASS_edge: the edge was produced by intersection with a bounding
body which coincided with an edge of that bounding body, or the edge
is derived from an edge of 'extruded_body',
- any subclass of PK_CLASS_surf: the edge is produced by intersection
with a surface in a PK_bound_surf_c bound.
The 'results' argument is currently only used if the 'allow_disjoint' option
is PK_LOGICAL_true and the disjoint 'body' components clash. In this case,
the 'status' field of the PK_TOPOL_local_r_t structure will be set to
PK_local_status_fa_fa_fail_c. Otherwise, the 'status' field is always set to
PK_local_status_ok_c.