 |
PK_FACE_make_neutral_sheet_2 |
|
PK_ERROR_code_t PK_FACE_make_neutral_sheet_2
(
--- received arguments ---
int n_left_faces, --- number of left faces
const PK_FACE_t left_faces[], --- left faces
int n_right_faces, --- number of right faces
const PK_FACE_t right_faces[], --- right faces
double placement, --- placement parameter
const PK_FACE_make_neutral_sheet_o_t *options, --- options structure
--- returned arguments ---
PK_TOPOL_track_r_t *const tracking --- tracking information
)
This function creates the neutral sheet defined by the surfaces on the
faces and returns it as a sheet body.
This function does not support facet geometry [NF]
Specific Errors:
PK_ERROR_inconsistent_offset (MILD) surfaces are not offsets
PK_ERROR_su_not_coincident (MILD) surfaces are not coincident
PK_ERROR_bad_tolerance (MILD) tolerance value is invalid
PK_ERROR_cant_extend (SERIOUS) failed to extend the sheet
PK_ERROR_cant_fill_hole (SERIOUS) failed to patch hole
PK_ERROR_cant_offset (SERIOUS) failed to create offset sheet
PK_ERROR_invalid_methods (MILD) method data invalid
PK_ERROR_cant_find_thickness (MILD) thickness cannot be calculated
PK_ERROR_zero_thickness (MILD) thickness is zero
PK_ERROR_disjoint (MILD) neutral sheet would be disjoint
PK_ERROR_cant_get_surf (MILD) failed to fit a medial surface to
the faces
PK_ERROR_cant_cover (MILD) failed to cover face set
PK_ERROR_su_self_intersect (MILD) medial surface would be
self-intersecting
PK_ERROR_not_smooth (MILD) failed to cover across edge that
is not smooth
Introduction
This function receives two sets of faces and constructs a neutral sheet between
them. The construction method of the neutral sheet can be modified via controls
in the option structure.
If the function is successful then the tracking will have one record containing
the created body as product topol and all input faces as original topols. If
the created body has more than one face then, in addition to the tracking
record containing the created body, a record is returned for each face in the
created body, containing the face or faces it is derived from.
If the option 'extend_and_fill_holes' is set to PK_LOGICAL_true then the sheet
will be made large enough to trim against other neutral sheets or side faces,
by extending and filling holes. If it is set to PK_LOGICAL_false then the
sheet will not be modified and will just be the offset of one set of faces.
If the neutral surface cannot be created, then an appropriate PK_ERROR_t will
be returned.
Construction Methods
The function has three alternative construction methods. The default
construction method is PK_neutral_method_mid_offset_c.
Mid-Offset Construction (PK_neutral_method_mid_offset_c)
Summary: Using this method, a neutral surface will only be created if the
surfaces of the given faces are genuine non-zero offsets of each other. The
function will calculate the thickness by identifying the current offset
value of the received faces, and then output an offset of either
'left_faces' or 'right_faces' at the appropriate distance.
The function will calculate the thickness by identifying an offset value
such that each face in 'left_faces' is an offset at this value of a face
in 'right_faces' and similarly each face in 'right_faces' is an offset of
a face in 'left_faces'.
The thickness calculation is done exactly if 'have_tolerance' is
PK_LOGICAL_false, or to the specified 'tolerance' if 'have_tolerance' is
PK_LOGICAL_true. In this case an offset value will be found such that the
offset value for all faces lies within this 'tolerance'.
The value of 'placement' will then be used to create a neutral surface
whose points satisfy the following expression:
(1 - p) D1 = (1 + p) D2
where p is the value of 'placement', D1 is the distance to the surface of
'left_faces' and D2 is the distance to the surface of 'right_faces'. If
p = 0, the neutral surface is equidistant from the given surfaces. The
function chooses whether the resulting neutral sheet will be offset from
'left_faces' or 'right_faces'.
Offset-Left Construction (PK_neutral_method_offset_left_c)
Summary: Using this method, a neutral surface will be created if a non-zero
thickness can be calculated. The function will identify a thickness and
offset 'left_faces' at the appropriate distance.
The function will calculate the thickness by identifying the maximum
distance that 'left_faces' can be offset before they intersect
'right_faces'.
The value of 'placement' will then be used to create a neutral sheet body
that is an offset of the 'left_faces' at a distance
thickness * (1 + p) / 2.
If p = 1, the neutral sheet will placed so that it touches 'right_faces'.
If no offset of 'left_faces' will intersect 'right_faces', or the
thickness is calculated to be zero, the function will fail with the
appropriate error.
Medial Construction (PK_neutral_method_medial_c)
Summary: Using this method allows the creation of true neutral sheets for
face sets that are not tolerant offsets of each other. A neutral sheet
will be created such that each point on it satisfies the following
expression:
(1 - p) D1 = (1 + p) D2
where p is the value of 'placement', D1 is the distance to the surfaces of
'left_faces' and D2 is the distance to the surfaces of 'right_faces'. If
p = 0, the neutral sheet is equidistant from the given sets of faces.
If this method is used then 'have_tolerance' must be set to PK_LOGICAL_true
and a 'tolerance' specified. This tolerance will be used to build the
medial surfaces - i.e. the medial surfaces will be within that tolerance of
the theoretical medial surfaces. If a disjoint face set defined on more
than one surface is too complex or turns through too big an angle then the
function will fail with the error PK_ERROR_cant_cover. If the medial
surface would be self-intersecting because it lies more than the radius of
curvature away from either face set then the function will fail with the
error PK_ERROR_su_self_intersect. If creating the medial surface fails
because it cannot create a single surface across an edge which is not
smooth in either face set then the function will fail with the error
PK_ERROR_not_smooth. The function chooses whether the resulting neutral
sheet will inherit its topology from 'left_faces' or 'right_faces'.
Function Reporting
The function groups the faces as follows.
- If PK_neutral_method_mid_offset_c is set: each group has an offset value
such that each face from 'left_faces' in the group is an offset of some face
from 'right_faces' in the group at the given offset value. If 'tolerance' is
set, the offset values are within 'tolerance' of each other.
- If PK_neutral_method_offset_left_c or PK_neutral_method_medial is set,
all faces belong to the same group.
The function will provide a report record of type PK_REPORT_3_t with status
PK_REPORT_3_neutral_face_data_c for each group identified by the function.
Each report record will contain:
- the method PK_neutral_method_t used by the group;
- an integer indicating whether 'left_faces' or 'right_faces' were offset to
make the neutral sheet. The value will be zero if 'left_faces' were offset,
or one if 'right_faces' were offset. If no neutral sheet was created, the
value will be zero;
- faces from 'left_faces' that are part of this group;
- faces from 'right_faces' that are part of this group;
- the value by which 'left_faces' or 'right_faces' were offset to make the
neutral sheet - this will be zero if no neutral sheet was created. It will
also be zero if PK_neutral_method_medial_c is set as in this case the
offset is not constant;
- the placement parameter received by the function;
- the minimum thickness calculated by the function for this group of faces;
and
- the maximum thickness calculated by the function - this will be the same as
the minimum thickness unless method PK_neutral_method_mid_offset_c or
PK_neutral_method_medial_c is used and a 'tolerance' is provided.
- the tolerance used by the function. This is usually the same as 'tolerance'
but may have been reduced if the value is too large with respect to the
minimum thickness. If 'tolerance' is unset, the value will be zero.
The exact structure of the report is provided in the PK_REPORT_3_t
documentation.
Faces that are not part of any group will be reported in a PK_REPORT_1_t with
status PK_REPORT_1_fa_not_offset_c, and the function will fail with error
PK_ERROR_inconsistent_offset.
If Parasolid was unable to determine how to orient one or both face sets,
the faces responsible in 'left_faces' and 'right_faces' will be reported in a
report of type PK_REPORT_1_t with status PK_REPORT_1_fa_unoriented_c.
In certain circumstances - if both face sets are defined on a single surface
each, and these surfaces are exact offsets - success may be returned even if
the faces do not overlap. For certain applications this may be undesirable.
This may be avoided by using the 'overlap' option to perform extra checks and
only succeed if faces are overlapping.