 |
PK_BODY_make_swept_tool |
|
PK_ERROR_code_t PK_BODY_make_swept_tool
(
--- received arguments ---
const PK_BODY_t tool, --- tool to sweep
const PK_AXIS1_sf_t *tool_axis, --- axis for tool
const PK_BODY_t path, --- path of sweep
const PK_BODY_make_swept_tool_o_t *options, --- options on sweeping
--- returned arguments ---
PK_TOPOL_track_r_t *const tracking, --- tracking information
PK_BODY_sweep_tool_r_t *const swept_tool --- resulting swept tool
)
This function creates a solid body by sweeping a solid tool body along a wire
path.
This function does not support facet geometry [NF]
Specific Errors:
PK_ERROR_bad_type The tool, path, or target is of the
incorrect type. (MILD)
PK_ERROR_bad_value A tool positioning vertex on the path is
required but not supplied or the axis
location does not lie in the plane normal
to the path at the tool positioning vertex.
(MILD)
PK_ERROR_bad_tolerance The value of tolerance is invalid. (MILD)
PK_ERROR_bad_combination A 'turn_axis' is supplied when
'have_lock_direction' is PK_LOGICAL_false,
or the axis of 'turn_axis' is not the same
as 'lock_direction'. (MILD)
PK_ERROR_sweep_failed PK_BODY_make_swept_tool suffered an
internal algorithmic failure. (SERIOUS)
PK_ERROR_boolean_failure The Boolean of the target and swept tool
failed. (SERIOUS)
PK_ERROR_disjoint The swept tool has split the target body.
(SERIOUS)
Introduction
This function creates a solid body which represents the volume swept out by a
solid tool body by revolving it about a specified axis and moving it along a
specified wire path, with the axis centred on the path. The tool is revolved
about the axis to make a spun outline, which is then swept along the path.
The solid tool body is supplied in the 'tool' argument, the tool axis is
supplied in the 'tool_axis' argument, and the wire path is supplied in the
'path' argument.
The user is informed of the result of the sweep operation via a returned
results structure which contains the resultant swept body and error
information.
Tool Specification
The following points need to be considered when specifying the tool body :
o The tool must be a solid body.
o The tool axis defines the axis about which to spin the tool body. It
must be perpendicular to the plane of the path if the path is planar,
or have a 'lock_direction' supplied to specify the tool orientation.
o The cross-section of the spun body obtained by spinning the tool body
about the tool axis must form a single connected set of curves. This
means that the input tool body must not be disjoint, and must intersect
the axis.
o By default, it does not matter where the tool is located with respect to
the path. The tool will be translated such that the tool axis location is
positioned on the path before being swept. If this behaviour is not
desired, 'place_tool_on_path' can be set to PK_LOGICAL_false to disable
it. In this case, the start vertex of the path must be specified using
'tool_site' and the 'tool_axis' must intersect the plane perpendicular
to the sweep direction at this vertex, taking into account any lock
direction specified.
Path Specification
The following points need to be considered when specifying the sweep path :
o The path must be planar and lie in a plane orthogonal to the tool axis,
unless a 'lock_direction' is supplied to specify the tool orientation.
Otherwise, a fault status of PK_sweep_tool_path_no_lock_c is returned.
o The sweep path need not be G1 continuous at vertices. At any non-G1
vertices the resultant swept body will be formed by spinning the tool body
on the axis centred at the non-G1 vertex. The sweep path must be G1
continuous where not at a vertex. If 'place_tool_on_path' is
PK_LOGICAL_false and the tool 'location' is not on the path, the path must
be G1 continuous. Otherwise, a fault status of PK_sweep_tool_path_not_g1_c
is returned.
o The sweep path may be closed in which case the resulting swept body
will close up on itself and is called a closed sweep.
o The sweep path may be self-intersecting.
o It is an error to specify a wire path that is a single ring edge with no
vertices.
Nominal Geometry on the Swept Body
The resultant swept body will always have nominal geometry enabled. The state
of the nominal geometry flag on the resultant swept body can be enquired and
set via PK_BODY_ask_curve_nmnl_state and PK_BODY_set_curve_nmnl_state
respectively.
The nominal geometry for an edge may be acquired via the functions,
PK_EDGE_ask_curve_nmnl and PK_EDGE_ask_geometry_nmnl.
Optional Boolean Functionality
The 'options' allow a 'target' body to be supplied that can either be
intersected with the swept tool or have the tool subtracted from it. If this is
requested, the 'swept_tool' returned is the 'target' resulting from
this operation. This functionality is useful whenever the desired sweep would
produce an invalidity outside the region of interest defined by the 'target'.
Returned Tracking and Error Information
The resultant swept body is returned in 'swept_tool' as a structure that
packages it with associated status information.
The status information, in the 'status' field of the returned structure, is
itself a structure that contains information on any failure to create the
swept body. The types of faults that occurred are indicated by the 'faults'
field. The locations of the faults are given by a list of points and list of
entities in the 'fault_locations' and 'fault_entities' fields respectively.
The tracking information is returned in 'tracking', and relates topology prior
to the operation to topology after it. Details of the structure of this
information are given in the documentation on PK_TOPOL_track_r_t.
The tracking information will relate faces in the resultant body to faces and
edges in the received tool, the path body, and optionally relate edges in the
result to faces, edges or vertices in the received tool and path. The tracking
records contain :
o for every face :
'product_topols' is an array containing that face.
'original_topols' is the set of edges in the path and the edges or
faces in the tool from which it was generated. Where the face results
from spinning the tool about a non-G1 path vertex, or the vertex at
the start or end of the sweep, the path topology will be this vertex.
If 'want_edge_tracking' is set to PK_LOGICAL_true, then the tracking records
will additionally contain:
o for each edge that is in the direction of the path :
'product_topols' is an array containing that edge.
'original_topols' is the set of corresponding path edges, along with
the vertices or edges on the tool from which it was generated.
o for each edge that is generated from the cross-section of the spun tool :
'product_topols' is an array containing that edge.
'original_topols' is the edges or faces in the tool from which it was
generated, along with either a corresponding path vertex or path edge.
o for each edge that is created by splitting faces during self intersection
repair :
'product_topols' is an array containing that edge.
'original_topols' is an array containing the set that is the union of
the sets of 'original_topols' of the two adjacent faces.
Topologies involved in many topological operations may appear in several
tracking records. In particular, where several product topologies arise from
the same original topologies these products will be grouped together in a
single track record.
If a Boolean operation has been performed, the product topologies will all
belong to the target body. Faces and edges created from the swept body will
refer to the originating topologies for the corresponding faces and edges on
the swept body. Edges produced from an imprint of the target and the swept
body will refer to the relevant target face in addition to the sweep origins.