 |
PK_TOPOL_facet_mesh_2_o_t |
|
struct PK_TOPOL_facet_mesh_2_o_s
{
int o_t_version; --- version of this PK option struct
PK_facet_shape_t shape; --- constraints on facet generation
--- (PK_facet_shape_convex_c)
PK_facet_match_t match; --- vertex matching strategy at edges
--- (PK_facet_match_topol_c)
PK_facet_density_t density; --- increased facet density
--- (PK_facet_density_no_view_c)
int n_view_directions;--- array of view directions in which
--- to increased the facet density
PK_VECTOR1_t *view_directions; --- (0, NULL)
PK_facet_cull_t cull; --- culling of view dependent facets
--- (PK_facet_cull_none_c)
int n_cull_transfs; --- array of view transformations in
--- which to cull
PK_TRANSF_t *cull_transfs; --- (0, NULL)
int n_loops; --- array of loops in sheet bodies to
PK_LOOP_t *loops; --- be ignored when facetting(0,NULL)
int max_facet_sides; --- max number of sides on a facet (3)
PK_LOGICAL_t is_min_facet_width; --- whether min_facet_width is set
--- (PK_LOGICAL_false) [PF]
double min_facet_width; --- minimum facet width [PF]
PK_LOGICAL_t is_max_facet_width; --- whether max_facet_width is set
--- (PK_LOGICAL_false)
double max_facet_width; --- maximum facet width
PK_LOGICAL_t is_curve_chord_tol; --- whether curve_chord_tol is set
--- (PK_LOGICAL_false)
double curve_chord_tol; --- chordal tolerance between a curve
--- and its facet edges in model units
--- i.e. upper bound on distance from
--- chord to the curve it approximates
PK_LOGICAL_t is_curve_chord_max; --- whether curve_chord_max is set
--- (PK_LOGICAL_false)
double curve_chord_max; --- max length of chord in model units
--- i.e upper bound on length of chord
--- used to approximate a curved edge
PK_LOGICAL_t is_curve_chord_ang; --- whether curve_chord_ang is set
--- (PK_LOGICAL_false)
double curve_chord_ang; --- max angle between curve and chord
--- used to approximate it, in radians
--- i.e. upper bound on sum of angles
--- between chord and curve tangents
--- measured at the chord ends.
PK_LOGICAL_t is_surface_plane_tol;--- whether surface_plane_tol is set
--- (PK_LOGICAL_false)
double surface_plane_tol;--- distance tolerance between surface
--- and its facet, in model units
--- i.e upper bound on distance from a
--- position on a facet to the surface
PK_LOGICAL_t is_surface_plane_ang;--- whether surface_plane_ang is set
--- (PK_LOGICAL_false)
double surface_plane_ang;--- angular tolerance between surface
--- and its facet, in radians.
--- i.e upper bound on the angular
--- deviation between surface normals
--- at any 2 positions under the facet
PK_LOGICAL_t is_facet_plane_tol; --- whether facet_plane_tol is set
--- (PK_LOGICAL_false)
double facet_plane_tol; --- max dist from facet to mid-plane
PK_LOGICAL_t is_facet_plane_ang; --- whether facet_plane_ang is set
--- (PK_LOGICAL_false)
double facet_plane_ang; --- facet_plane_tol : max_facet_width
--- (max permitted ratio between them)
PK_LOGICAL_t is_local_density_tol;--- whether local_density_tol is set
--- (PK_LOGICAL_false)
double local_density_tol;--- local value of surface_plane_tol
--- (for increased facet density)
PK_LOGICAL_t is_local_density_ang;--- whether local_density_ang is set
--- (PK_LOGICAL_false)
double local_density_ang;--- local value of surface_plane_ang
--- (for increased facet density)
int n_local_tols; --- array of sets of local tolerances
PK_facet_local_tolerances_t
*local_tols; --- (0, NULL)
int n_topols_with_local_tols;
PK_TOPOL_t *topols_with_local_tols;
--- array of topological entities
--- for which local tolerances are
--- specified (0, NULL)
int *local_tols_for_topols;
--- index into 'local_tols'
--- picking out the local tolerances
--- to be attached to the
--- corresponding entity in
--- 'topols_with_local_tols'
PK_facet_ignore_t ignore; --- whether to ignore small features
--- when facetting. Small features
--- can be ignored by inputting an
--- absolute value or a ratio value
--- (PK_facet_ignore_no_c)
double ignore_value; --- features smaller than this will be
--- considered for ignoring (0.0)
PK_facet_ignore_scope_t
ignore_scope; --- whether to treat a face
--- individually or as part of the
--- face's owning body when looking
--- for ignorable features and
--- facetting an array of faces
--- (PK_facet_ignore_scope_global_c)
PK_facet_wire_edges_t
wire_edges; --- whether to take wire edges into
--- account faces when facetting
--- (PK_facet_wire_edges_no_c)
PK_facet_incr_t
incremental_facetting;
--- Whether to make use of
--- incremental facetting data
--- (PK_facet_incr_no_c)
PK_facet_incr_method_t
incremental_method;
--- Whether to only facet faces
--- without incremental facetting data
--- or to automaticaly facet any other
--- faces that need to be refacetted
--- (PK_facet_incr_method_attrib_c)
PK_facet_incr_prop_t
incremental_propagation;
--- For future use
--- (PK_facet_incr_prop_allow_c)
PK_facet_incr_tf_t
incremental_transformation;
--- Whether incremental facetting
--- data can be used on bodies which
--- have been transformed since the
--- last incremental facetting call.
--- (PK_facet_incr_tf_no_c)
PK_facet_incr_refine_t
incremental_refinement;
--- Whether to allow refinement
--- during incremental facetting
--- This option only applies if
--- 'incremental_method' is set to
--- PK_facet_incr_method_attrib_c.
--- (PK_facet_incr_refine_no_c)
PK_facet_incr_report_t
incremental_report;
--- Whether to report problem faces
--- during incremental facetting
--- This option only applies if
--- 'incremental_method' is set to
--- PK_facet_incr_method_attrib_c.
--- (PK_facet_incr_report_no_c)
PK_facet_inflect_t inflect; --- Whether facets around points of
--- inflection may be further refined
--- (PK_facet_inflect_no_c)
PK_facet_quality_t quality; --- Whether to perform extra checks
--- to improve the quality of the
--- facets
--- (PK_facet_quality_standard_c)
PK_LOGICAL_t vertices_on_planar;
--- Whether to force facet vertices
--- along tolerant edges to lie on a
--- planar face adjacent to the
--- tolerant edge if a planar face
--- exists
--- (PK_LOGICAL_false)
PK_facet_sing_topol_t
sing_topol; --- facet topology required around a
--- singularity
--- (PK_facet_sing_topol_default_c)
PK_facet_respect_t
respect_offset; --- Whether to take into account faces
--- that are offsets of one another
--- when producing facets
--- (PK_facet_respect_no_c)
int n_bodies_with_scales;
PK_BODY_t *bodies_with_scales;
--- array of bodies for which a scale
--- factor is specified
--- (0, NULL)
PK_scale_factor_t
*scale_factors; --- scale factor associated with the
--- corresponding body in
--- 'bodies_with_scales'
--- (NULL)
int n_viewports; --- number of viewports (0)
const PK_NABOX_sf_t
*viewports; --- array of viewports (NULL)
};
typedef struct PK_TOPOL_facet_mesh_2_o_s PK_TOPOL_facet_mesh_2_o_t;
Facet mesh generation controls. See here for more information.
Specific Errors:
PK_ERROR_nitems_lt_0 negative number of items in loop array.
(MILD)
PK_ERROR_lt_3_sides max_facet_sides too small. (MILD)
PK_ERROR_distance_too_small min/max_facet_width too small. (MILD)
PK_ERROR_distance_too_large min/max_facet_width too large. (MILD)
PK_ERROR_bad_tolerance is_<tol> is true but used with a bad <tol>
or negative number supplied for local
tolerance. (MILD)
PK_ERROR_unsuitable_topology entity is not face or body in
topols_with_local_tols array. (MILD)
PK_ERROR_bad_value integer value in local_tols_for_topols
array does not lie between 0 and
n_local_tols, or culling back faces
requested and no cull_transfs specified,
or increased facet density required
and no view_directions specified. (MILD)
PK_ERROR_bad_component inappropriate transformation in
cull_transfs. (MILD)
PK_ERROR_bad_combination a bad combination of options has been
requested. (MILD)
PK_ERROR_not_implemented 'incremental_method' is set to
PK_facet_incr_method_auto_c under
PK_TOPOL_facet. (MILD)
'incremental_method' is set to
PK_facet_incr_method_auto_c and 'topols'
contains faces. (MILD)
'incremental_method' is set to
PK_facet_incr_method_auto_c and either
'cull' is set to PK_facet_cull_back_c or
'density' is not set to
PK_facet_density_no_view_c. (MILD)
'incremental_method' is set to
PK_facet_incr_method_auto_c, 'match' is
set to PK_facet_match_topol_c and 'ignore'
is not set to PK_facet_ignore_no_c. (MILD)
'n_viewports' is set to a value > 1. (MILD)
'n_viewports' is not zero and
'incremental_facetting' is set to a value
other than PK_facet_incr_no_c. (MILD)
Used in:
PK_TOPOL_facet_2_o_t
The PK_TOPOL_facet_mesh_o_t structure provides the following controls :
- facet constraints (i.e. whether holes are permitted in facets or
if the generated facets may be concave).
- which edge matching strategy to use when matching adjacent facetted faces
- specifying view dependent options (face culling & increasing facet density)
- capping specified loops within a sheet body
- setting tolerance values to be used in the facetted approximation
Setting tolerance values
The tolerance values are defined by pair of PK_LOGICAL_t and double values,
the former indicating whether the double value has been set explicitly.
PK uses the convention that if no explicit tolerance value is provided,
Parasolid is free to calculate its own internal tolerance values. These
are generally case specific, rather than using specific fixed values.
SHAPE
This field controls whether generated facets can contain holes
or concave interior angles. The possible settings are one of :
PK_facet_shape_any_c : allow creation of holed or concave facets
PK_facet_shape_cut_c : cut facets with holes into concave facets
PK_facet_shape_convex_c : divide concave facets into convex facets (default)
--------------- --------------- ---------------
| | | | | | |
| /\ | | /\ | | /\ |
| / \ | | / \ | | / \ |
| / \ | | / \ | | / \ |
| /______\ | |__/______\_____| |__/______\_____|
| | | | | |
|_______________| |_______________| |_______________|
PK_facet_shape_any_c PK_facet_shape_cut_c PK_facet_shape_convex_c
-------------------- -------------------- -----------------------
The diagram above illustrates a (contrived) example of a facet containing an
interior hole which can be generated using the PK_facet_shape_any_c option.
The constraint PK_facet_shape_cut_c indicates that Parasolid must cut any
facets containing interior holes before output. This can sometimes generate
cases where the modified facets have concave interior angles.
The constraint PK_facet_shape_convex_c indicates that Parasolid must cut
any facets containing holes and further divide any concave facets into convex
facets before output.
The convexity test is made by projecting the facet fins onto the 'mid_plane'
of the facet and testing the interior angles. The 'mid_plane' is defined as
the plane passing through the centre of gravity of the facet vertices whose
normal is in the direction of the facet plane normal, where the facet plane
normal N is defined as follows:
N = normalise((v[0]Xv[1])+(v[1]Xv[2])+ ...+(v[n-2]Xv[n-1])+(v[n-1]Xv[0]))
where v[0], ..., v[n-1] are the facet vertices.
The PK_facet_shape_cut_c and PK_facet_shape_convex_c constraints are only
relevant when max_facet_sides > 3.
See here for more information.
MATCH
This field controls how facets between adjacent faces are matched. See
PK_facet_match_t for information about the values allowed.
| | | | | | | | | | | | | | | |
|...|....|...|.......| |...|....|...|...|.|.| |......|.|...........|
| | | | | | | | | | | | | B | |
| | | | | | | | | | | | | / \| |
| | | | | | | | | | | | | / C-----------Y
X---x----x---x---x-x-Y X---x----x---x---x-x-Y X---A---------D /|
| | | | | | | | | | | | | | |\ / |
| | | | | | | | | | | | | | | \ / |
| | | | | | | | | | | | | | | E |
|...|............|.|.| |...|....|...|...|.|.| |...|.........|..|...|
| | | | | | | | | | | | | | | | |
PK_facet_match_geom_c PK_facet_match_topol_c PK_facet_match_trimmed_c
--------------------- ---------------------- ------------------------
The above diagram illustrates a (contrived) example of the facets created
along an edge XY between two adjacent faces with the various matching
options. The dotted lines indicate the curve chord tolerance of the curve on
edge XY.
Actual examples of facets created using various matching options can be
found here.
The PK_facet_match_trimmed_c option clips exterior facets to within
'curve_chord_tol' of the appropriate model edge but does no matching. If this
option is selected, facets will, in general, overlap or leave gaps at the
boundaries of adjacent faces. In the above example a gap defined by ABCYEDA
exists at the boundary of the two faces.
The PK_facet_match_geom_c option modifies the geometry of such facet meshes
by clipping (and possibly extending) exterior facets to meet at the common
edge formed by the intersection of the underlying facet planes.
There are certain special cases in which facet meshes may not match see
here for more information.
The PK_facet_match_topol_c option further modifies the facet mesh so that
facet vertices are matched across common edges. The algorithm identifies
cases where an exterior vertex on one facet mesh lies between a connected
pair of exterior vertices on the other facet mesh and inserts a matching
vertex.
If the application inputs an array of faces, Parasolid recognises faces that
belong to the same body and have identical transform entities. For edges
between such faces the requested matching will be applied unless the option
'ignore_scope' is set to PK_facet_ignore_scope_local_c (see 'ignore_scope'
option under IGNORING SMALL FEATURES below).
DENSITY
The facet density option allows the density of the facet mesh to be increased
locally either in regions where the facet normals change from being front
facing to back facing relative to the view directions or in regions where
the facet normals are close to being parallel to the view directions. The
view directions are given in 'view_directions', if no 'view_directions' are
specified this option is ignored.
This option can be used when generating view specific facet meshes for use
by rendering packages when creating high quality images (containing
enhanced detail where the facet surfaces form silhouettes with the view
direction).
This field can take the following values :
PK_facet_density_no_view_c : facet density is independent of view
(default)
PK_facet_density_use_view_c : increase facet density at view silhouettes
PK_facet_density_parallel_c : increase facet density in regions where the
facet normals are close to parallel to the
view directions
PK_facet_density_sil_and_par_c: increase facet density at view silhouettes
and in regions where the facet normals are
close to parallel to the view directions
The PK_facet_density_no_view_c refers to no other arguments.
The PK_facet_density_use_view_c, PK_facet_density_parallel_c and
PK_facet_density_sil_and_par_c arguments require the following values
- the 'view_directions' option,
- the 'local_density_tol' tolerance value,
and optionally,
- the 'local_density_ang' tolerance value
See here for more information.
INCREASING FACET DENSITY IN ONE OR MORE DIRECTIONS
The 'view_directions' option allows the facet density to be increased one or
more view directions. These view directions are specified as an array of
unit vectors.
The PK_TOPOL_facet_mesh_m macro initialises the view_directions array to be
empty
n_view_directions = 0
in this case facet density will not be increased in any direction.
See here for more information.
CULL
This is a performance enhancement option for use when creating view
specific images from facet data (possibly in conjunction with the
the PK_facet_density_use_view_c option).
It can also be used to reduce the amount of facet data which are output.
This field can take the following values :
PK_facet_cull_none_c : do not cull any facets; output them all (default)
PK_facet_cull_back_c : cull back facing facets
The PK_facet_cull_none_c outputs all faces (and refers to no other arguments)
The PK_facet_cull_back_c argument requires the 'cull_transfs' option to be
set to contain viewing transformations which may contain perspective.
Currently only the first PK_TRANSF_t in the array will be used for culling.
It is not possible to request (the default) topology matching with this
option, PK_facet_match_geom_c or PK_facet_match_trimmed_c must be specified.
This option reduces the size of the generated facet mesh (and consequently
the amount of topological and geometric data which are output) by not
facetting back facing faces. A back facing face is one whose normal at
every point is backwards facing. If a face cannot quickly be identified as
back facing it will be facetted.
This option has no effect on sheet bodies.
See here for more information.
CULL VIEW TRANSFORMATIONS
The 'cull_transfs' option allows facets to be culled relative to one or more
view transformations. These view transformations are specified as an array
of PK_TRANSF_ts.
Defining a viewing transformation
Parasolid has a number of requirements on the view transformations used
for culling.
In general a viewing matrix shall be of the form M
| R(11) R(12) R(13) Px |
| |
M = | R(21) R(22) R(23) Py |
| |
| R(31) R(32) R(33) Pz |
| |
| Tx Ty Tz S |
The vector T represents a translation
The vector P represents perspective
S is the inverse global scale vector
The rotation submatrix R defines an orthonormal set of vectors H, V, D
| Hx Vx Dx |
R = | Hy Vy Dy |
| Hz Vz Dz |
M must satisfy the following constraints:
(i) The rotation matrix R must be orthonormal
(ii) The determinant on R is +1
(iii) D and P must be parallel if P is not a zero vector
(iv) S = 1 - Tz * w (where w = -( D DOT P )
The PK_TOPOL_facet_mesh_m macro initialises the 'cull_transfs' array to be
empty
n_cull_transfs = 0
in this case back facing facets will not be culled.
NOTE: At preset it is only possible to cull facets with respect to one
view transformation, thus only the first entry in the 'cull_transfs' array
will be used.
See #Cull Transformations## for more information.
LOOPS
The 'loops' option allows specific holes in a sheet body to be capped.
These are specified as an array of interior loops (being ones owned
by sheet bodies or faces which are included in the 'topol' array').
These interior loops are ignored during facetting; the effect is
to extend the surface geometry of the surrounding sheet face across
the loop.
The PK_TOPOL_facet_mesh_m macro initialises the loops array to be empty
n_loops = 0
See here for more information.
FACET SIZE AND NUMBER OF SIDES
The 'max_facet_sides' option controls the maximum number sides that any facet
can have and must take a value of 3 or more.
See here for more information.
The options 'is_min_facet_width' and 'is_max_facet_width' control the minimum
and maximum lengths of any of the facets' sides. To set an explicit value
for such constraints, the associated field
min_facet_width
or max_facet_width
is set to a positive value (specified in model units) and the associated flag
is set to PK_LOGICAL_true.
In cases where refinement results in a facet being created that has a width
smaller than 'min_facet_width' Parasolid will disregard the supplied curve,
surface and planarity tolerances so that the new facet will not be refined
any further. Therefore facets may exist with dimensions smaller than
'min_facet_width'.
If both a 'min_facet_width' and 'max_facet_width' are supplied the
'min_facet_width' must be less than the 'max_facet_width' otherwise
PK_ERROR_bad_combination will be returned.
Note: The 'min_facet_width' is ignored on topologies with facet geometry.
See here for more information.
CURVE TOLERANCE
The following arguments control curve tolerance values, measuring how closely
a curved edge entity is approximated by a number of straight line chords.
Three curve tolerance controls are provided :
curve_chord_tol : the maximum chordal distance between a
facet edge and its original edge entity
curve_chord_max : the maximum length of any facet edge which
represents part of an original edge entity
curve_chord_ang : the maximum angle which is permitted between
a facet chord and its original edge entity,
measured as the sum of the two angles formed
between the chord and the curve tangents at
each chord end.
To set one or more of these constraints, the associated flag must be set to
PK_LOGICAL_true and the value set to a positive value. In the case of the
'curve_chord_ang' the value must be no greater than pi/2 radians.
See here for more information.
SURFACE TOLERANCE
The following arguments control surface tolerance values, measuring
how closely any curved surface attached to a face is approximated
by a facet mesh.
Two surface tolerance controls are provided :
surface_plane_tol : the maximum distance between the mid-plane
of a facet and its original face entity
surface_plane_ang : the maximum angle (in radians) which is permitted
between the surface normals at any two positions
on the surface which lie within the facet boundary
(this is usually met but it is not guaranteed).
To set one of both of these constraints, the associated flag must be set to
PK_LOGICAL_true and the value set to a positive value. In the case of the
'surface_plane_ang' the value must be no greater than pi/2 radians.
See here for more information.
PLANARITY TOLERANCE
The "facet to mid-plane" tolerances control how closely vertices lie on
a common plane.
Two planarity tolerance controls are provided :
facet_plane_tol : the maximum distance between the mid-plane
of a facet and its facet vertices
facet_plane_ang : the maximum ratio permitted between :
1) the maximum distance from the mid-plane
of a facet to any of its facet vertices
2) the maximum width of a facet.
To set one or both of these constraints, the associated flag must be set to
PK_LOGICAL_true and the value set to a positive value. In the case of the
'facet_plane_ang' the value must be no greater than pi/2 radians.
LOCAL FACET DENSITY TOLERANCE
The "increased_density" tolerance values are used in conjunction
with the PK_facet_density_use_view_c, PK_facet_density_parallel_c and
PK_facet_density_sil_and_par_c density options. These define local surface
tolerance values to be used when generating facets in the region of view
dependent facet silhouettes and/or in regions where the facet normals are
close to being parallel to the specified view directions.
Two local facet density tolerance controls are provided:
local_density_tol : the maximum distance between the mid_plane of a
facet and its original face entity.
local_density_ang : the maximum angle (in radians) which is permitted
between the surface normals at any two positions
on the surface which lie within the facet boundary
(this is ususally met but it is not guaranteed).
If the PK_facet_density_use_view_c, PK_facet_density_parallel_c or
PK_facet_density_sil_and_par_c options are requested the
'is_local_density_tol' flag and its associated value must be set (to a
positive value) otherwise the option is ignored.
It is also possible (although not compulsory) to set the
'is_local_density_ang' flag. The associated value must be positive and must
be no greater than pi/2 radians.
See here for more information.
FACETTING TOPOLOGICAL ENTITIES WITH LOCAL TOLERANCES
It is possible to attach local tolerances to individual or groups of
topological entities (either faces or bodies), these local tolerances will
then override the facetting tolerances for the particular face/body.
In order to facet certain entities with local tolerances it is necessary
to fill in the following fields:
'local_tols'
This field is an array of PK_facet_local_tolerances_t. This array contains
all local tolerance sets to be attached to topological entities.
'topols_with_local_tols'
This field takes an array of unique topological entities (faces or bodies)
which are to be facetted using local tolerances. If this is empty all
entities will be facetted to the tolerances previously specified in the
options structure. If this is not empty the parallel array
'local_tols_for_topols' must be filled in.
'local_tols_for_topols'
This field must be of length 'n_topols_with_local_tols', and takes integer
values corresponding to indexes into the 'local_tols' array. For
each topological entity in 'topols_with_local_tols', the corresponding entry
in 'local_tols_for_topols' is the index into 'local_tols' corresponding to
the PK_facet_local_tolerances with which the entity is to be facetted.
When finding the tolerances to use when facetting a paticular face, the
tolerances are initially set to the default tolerances. If any tolerances
were specified in the options structure these tolerances overwrite the
default tolerances. If the face's owning body has local facet tolerances
specified these tolerances (provided they are not set to 0.0) override any
existing tolerances for this face. If the face itself has local facet
tolerances specified these tolerances will override any existing tolerances
for this face (provided they are not 0.0).
The curve tolerance along an edge will be the minimum local curve tolerance
of the edge's faces.
The PK_TOPOL_facet_mesh_o_m initialises the 'local_tols' array to be empty
n_local_tols = 0,
'topols_with_local_tols' is also initialised to be empty
n_topols_with_local_tols = 0,
in this case all entities will be facetted using the facetting tolerances
given above.
See here for more information.
IGNORING SMALL FEATURES
The 'ignore' option allows 'small' features to be ignored when facetting.
The value specified in 'ignore_value' defines which features are classed as
small. The overall box is the box containing all entities to be facetted,
taking into account associated 'topol_transfs' and 'scale_factors'.
The permitted values for this option:
PK_facet_ignore_no_c: (default)
All features will be facetted regardless of size.
PK_facet_ignore_absolute_c:
Any feature with a box size smaller than the value specified in
'ignore_value' may be ignored. If the feature belongs to a body that is
being scaled, i.e. if the body is supplied in 'bodies_with_scales', then the
scale will be taken into account. The feature with the scale applied would
need to have a box size smaller than the 'ignore_value'.
PK_facet_ignore_ratio_c:
Here 'ignore_value' corresponds to the ratio of box size of the feature to
the size of the overall box i.e. if this value is set to 0.01 then features
smaller than 1% of the overall box may be ignored. If facetting bodies the
overall box will be the union of all the 'topols' boxes (with 'topol_transfs'
and 'scale_factors' applied), if faces are being facetted the overall box
will depend on 'local_scope' as described below.
If a feature belongs to a body that is being scaled the 'ignore_value'
corresponds to the ratio of the box size of the scaled feature to the size of
the overall box.
PK_facet_ignore_body_ratio_c:
'ignore_value' corresponds to the ratio of the box size of the feature to
the size of the box of the body containing the feature.
Note that if the option 'loops' has been specified, facetting will ignore the
given loops regardless of the value of the 'ignore' option.
The option 'ignore_scope' only has an effect when facetting an array of
faces, the permitted values for this option:
PK_facet_ignore_scope_global_c: (default)
Ensures that the only loops ignored on a face when facetting an array of
faces are the loops that would have been ignored had the face's owning body
been facetted, thus small holes in the face will not be ignored if the loop
defining the hole is adjacent to faces that are not classed as small. In
this case the overall box will be the union of all of the 'topols' owning
bodies boxes (with 'topol_transfs' and 'scale_factors' applied).
PK_facet_ignore_scope_local_c:
When looking for ignorable features the faces in the array of faces will be
facetted as separate entities, hence there will be no matching between
adjacent faces. If the face contains holes defined by loops which can be
classed as small these will be ignored. In this case the overall box will be
the union of all the 'topols' boxes (with 'topol_transfs' and 'scale_factors'
applied).
See here for more information.
WIRE EDGES
The behaviour of the facetting operation on faces which contain wire edges
can be modified via the 'wire_edges' option.
The permitted values for this option:
PK_facet_wire_edges_no_c: (default)
Any wire edge in a face will be facetted over as long as that edge is
manifold.
PK_facet_wire_edges_yes_c:
Facetting will take wire edges in faces into account and will facet the face
in such a way that no facet is intersected by a wire edge.
See here for more information.
INCREMENTAL FACETTING
The 'incremental_facetting' option allows a trade off between memory usage
and performance.
Geometry matching supports incremental facetting. Topology matching supports
incremental facetting only if the 'incremental_method' is set to
PK_facet_incr_method_auto_c and the 'quality' is set to
PK_facet_quality_improved_c. Trimmed matching does not support incremental
facetting. If incremental facetting is requested but not supported,
PK_ERROR_bad_combination will be returned.
This option must be set to PK_facet_incr_no_c when the function is running
concurrently in a thread without locked partitions.
Incremental facetting is achieved by attaching incremental facetting data to
faces, edges and fins. Positional information is attached to edges and
fins and a flag is attached to each face which has been facetted. When any
portion of the model changes the incremental facetting data associated with
the changed region will be deleted.
The 'incremental_facetting' option can be set to one of the following values:
PK_facet_incr_no_c
Incremental facetting off, any incremental facetting data present will be
ignored.
All values of PK_facet_match_t are valid with this setting.
PK_facet_incr_clear_c
Incremental facetting off, any incremental facetting data present will be
deleted.
All values of PK_facet_match_t are valid with this setting.
PK_facet_incr_refresh_c
Incremental facetting on, any incremental facetting data present will be
deleted and new incremental facetting data generated.
PK_facet_match_trimmed_c is not supported with this setting.
PK_facet_incr_yes_c
Incremental facetting on, any existing incremental facetting data will be
used and new incremental facetting data generated as appropriate.
PK_facet_match_trimmed_c is not supported with this setting.
The incremental facetting data will only be made use of if the option
takes the last value, PK_facet_incr_yes_c.
The incremental facetting data associated with the edges and fins is used
to regenerate the positions of facet vertices, allowing the newly created
facets to meet the existing facets on neighbouring faces preserving geometry
or topology matching. There will be cases where it might not be possible to
honour the matching from a previous facetting operation, for instance, the
addition of a small feature between a facet edge and a model edge, in such
cases refinement is said to be required and the behaviour will depend on the
incremental facetting options detailed below.
The behaviour of incremental facetting depends on the 'incremental_method'
selected:
PK_facet_incr_method_auto_c:
If a body or an array of bodies is being facetted then any faces that need
to be refacetted in order to honour the requested matching will be
refacetted. Faces without the incremental facetting data will be facetted,
and any faces that need refinement of their edges will be refacetted.
Note: If topology matching is requested this method must be used.
Note: This method is not implemented for cases where 'topols' is an array
of faces.
By default if a body is transformed and then subsequently handed into
incremental facetting all faces of the body will be refacetted. If
however the application is able to transform the facets displayed the
'incremental_transformation' option may be used to limit the faces that
need to be refacetted to those that have been modified rather than just
transformed. The 'incremental_transformation' option can take one of the
following values:
PK_facet_incr_tf_no_c:
Incremental data on faces whose owning body has been transformed
since the last call to incremental facetting will be ignored. All
faces of body will all be refacetted in their transformed position
during the incremental facetting call.
PK_facet_incr_tf_rigid_c:
Incremental data on faces whose owning body had a rigid body transform
applied will be taken into account. Only faces that have been modified
(excluding being transformed) since the last call to incremental
facetting will be refacetted. The new facets created for these faces
will match the facets in the transformed position.
PK_facet_incr_tf_rigid_ref_c:
Like PK_facet_incr_tf_rigid_c but the transform applied to the body
may also contain reflection components as well as the rigid body
transform.
Note: 'incremental_transformation' should only be set to
PK_facet_incr_tf_rigid_c or PK_facet_incr_tf_rigid_ref_c if the
displayed facets have been transformed.
Note: If the 'incremental_method' is set to PK_facet_incr_method_auto_c
the 'incremental_report' and 'incremental_refinement' options are
ignored.
Note: 'incremental_method' cannot be set to PK_facet_incr_method_auto_c
under PK_TOPOL_facet.
PK_facet_incr_method_attrib_c
Facet only those faces which do not have incremental facetting data,
whether facetting an array of faces or bodies.
The incremental facetting data associated with the edges and fins is used
to regenerate the positions of facet vertices.
If facetting an array of faces then a face will fail to facet if any of
its edges which do not have the incremental facetting data flag are shared
by a face which is unmarked and does not occur in the array. This is
because such edges will be refacetted and it cannot be guaranteed that
geometry matching will be honoured.
The incremental_refinement option can be used to control the behaviour in
cases where refinement is required. This option can take any one of the
following values:
PK_facet_incr_refine_no_c
Refinement is not allowed, if an edge requires refinement then an error
will be reported for those faces which share that edge and are not
marked as already facetted. If facetting an array of faces then only
faces from the array will be reported.
PK_facet_incr_refine_yes_c
If refinement is required for an edge then new incremental facetting
data will be generated for that edge and its fins, these will replace
any existing incremental facetting data. Any face which shares the edge
but is not being refacetted, either because it has incremental
facetting data or because an array of faces is being facetted which
does not include this face, will not be refacetted and the geometry
matching may not be honoured.
The incremental_report option controls which faces are reported through the
error mechanism. This option can take any one of the following values:
PK_facet_incr_report_no_c
No extra details reported.
PK_facet_incr_report_missing_c
If facetting an array of faces then those faces which need to be
included to define facetted perimeters will be reported through the
error mechanism.
PK_facet_incr_report_refine_c
If an edge requires refinement then all those faces which share that
edge that have not been refacetted will be reported through the error
mechanism. This option should only be set if 'incremental_refinement'
is set to PK_facet_incr_yes_c.
PK_facet_incr_report_yes_c
All reporting mechanisms will be selected. This option should only be
set if 'incremental_refinement' is set to PK_facet_incr_yes_c.
Note: The 'incremental_method' PK_facet_incr_method_attrib_c is not
supported for topology matching.
Note: If the 'incremental_method' is set to PK_facet_incr_method_attrib_c
the 'incremental_propagation' option is ignored.
See here.
FACETS AROUND POINTS OF INFLECTION
The 'inflect' option may be used to refine facets around points of
inflection.
The permitted values for this option are:
PK_facet_inflect_no_c: (default)
Facets around points of inflection are not refined.
PK_facet_inflect_split_near_c:
Facets around points of inflection may be further refined to better
represent the change in curvature of the surface.
See here for more information.
IMPROVING FACET QUALITY
The 'quality' option may be used to control the quality of facets produced.
There is a trade off between the quality of the facets and the performance of
the facetting algorithm.
The permitted values for this option are:
PK_facet_quality_standard_c: (default)
No extra checks are carried out to improve the quality of facets.
PK_facet_quality_improved_c:
Extra checks are performed during facetting in order to improve the quality
of facets.
See here for more information.
FACET VERTICES ALONG TOLERANT MODEL EDGES
The 'vertices_on_planar' option may be used to force facet vertices along
tolerant model edges to lie on a planar face adjacent to the tolerant edge,
if such a face exists.
The permitted values for this option are:
PK_LOGICAL_false: (default)
Facet vertices can lie on any of the faces adjacent to the tolerant edge.
PK_LOGICAL_true:
If there is one planar face adjacent to the tolerant edge, the facet vertices
will be forced to lie on this face. If there are multiple planar faces
adjacent to the tolerant edge the facet vertices will lie on one of the
planar faces.
See here for more information.
FACET TOPOLOGY AT SINGULARITY
The 'sing_topol' option may be used to indicate the required facet topology
at a singularity.
The permitted values for this option are:
PK_facet_sing_topol_default_c: (default)
A singularity has a single facet vertex around which a number of adjacent
triangular facets radiate.
PK_facet_sing_topol_degen_c:
The singularity is surrounded by a set of degenerate fins of degenerate
triangular facets. Each two adjacent such fins are separated by a vertex.
Each pair of adjacent triangular facets radiating around the singularity that
would be created for the PK_FACET_sing_topol_default_c are now separated by
a zero thickness triangular facet with a zero length fin at the
singularity. Although these fins are of zero length in 3 space, the UV
parameters at their vertices are distinct in parameter space. The
parameters (and hence normals and derivatives) at each vertex at the
singularity are the same as would be available via the fin_data, data_param
and param_uv tables in the PK_facet_sing_topol_default_c case unless a
facet with its apex at the singularity has one of its sides which meet at the
singularity coincident with a model edge, in which case the singular
parameter at the apex will be set to the value at the other end of the fin
coincident with the model edge. In the fin_fin table, the co-fin of a
degenerate fin at a singularity will be set to -3.
FACET GENERATION FOR OFFSET FACES
The 'respect_offset' option may be used to control the facets produced on
faces that are offsets of one another.
The permitted values for this option are:
PK_facet_respect_no_c: (default)
Facets are created based on the supplied tolerances but if the
'surface_plane_tol' is larger than the separation between faces in thin
walled regions of the part it is possible that facets may clash.
PK_facet_respect_yes_c:
Facetting takes into account faces that are offsets of one another and tries
to reduce the likelihood that facets on these faces clash.
Note: this may result in more facets being created.
Note: If 'respect_offset' is set to PK_facet_respect_yes_c, the 'density'
option must be set to PK_facet_density_no_view_c, the 'incremental_facetting'
option must be set to PK_facet_incr_no_c and the 'cull' option must be set to
PK_facet_cull_none_c, otherwise the error PK_ERROR_bad_combination will be
returned.
See here for more information.
SCALING FACETS ON BODIES
It is possible to associate a scale factor with a body so that any facets
produced for such a body, or faces of that body, are then enlarged by the
supplied scale factor. The centre of scaling is the origin.
In order to supply scale factors for bodies it is necessary to fill in the
following fields:
'bodies_with_scales'
This field, of length 'n_bodies_with_scales', is an array of unique bodies
which are to have a scale factor applied. If this is empty no scaling will
occur. If this is not empty the parallel array 'scale_factors' must be
filled in.
'scale_factors'
This field must be of length 'n_bodies_with_scales'. Each PK_scale_factor_t
in this array is the scale associated with the corresponding body in
'bodies_with_scales'.
Note: If 'topol_transfs' are supplied any translation component of the
transform will be applied to the facets after they have been scaled.
See here for more information.
LIMITING FACETS OUTPUT USING VIEWPORTS
The 'viewports' and 'n_viewports' options may be used to limit the facets
returned to those which lie on faces that overlap with at least one of the
specified viewports. To do this an array of 'viewports' should be supplied.
Any 'topol_transfs' and 'scale_factors' associated with the face or its body
are taken into account when overlapping the face with the viewport.
If 'n_viewports' is 0 all facets will be returned.
Note: if more than one viewport is supplied PK_ERROR_not_implemented will be
returned.
See here for more information.