PK_ERROR_code_t PK_FACE_pattern
(
--- received arguments ---
int n_pattern_faces, --- number of pattern faces (>0)
const PK_FACE_t pattern_faces[], --- pattern faces
int n_transforms, --- number of transforms (>0)
const PK_TRANSF_t transforms[], --- pattern transformations
const PK_FACE_pattern_o_t *options, --- pattern options
--- returned arguments ---
PK_FACE_pattern_r_t *const pattern_results --- status and tracking info
)
This function creates a pattern of a feature on the target body.
Specific Errors:
PK_ERROR_wrong_transf transform is general affine
A pattern of features is created by specifying a collection of faces
on the target which form the feature and a set of transformation
entities which will determine the pattern. The collection of faces
is copied in-situ and transformed to form the pattern. The pattern
faces specified may belong to a manifold or general body.
Pattern Faces
The collection of pattern faces which are to be patterned must satisfy
the following basic requirements :
o All the faces must belong to the same body.
o All the faces of the feature to be patterned, must be
specified.
The set of pattern faces may have any number of boundaries (circuits of
edges) at which it meets the non-pattern faces. Each boundary must,
after being transformed, remain coincident with the body. The location
of the transformed boundary is restricted to affect only those
topological entities which are initially incident with the pattern
faces. There are two types of boundary circuit - those that form a
loop inside a non-pattern face, and those that cross non-pattern edges.
Boundary circuits inside non-pattern faces:
o After transformation, the boundary loop must remain in the same
face.
o A boundary circuit must not be a winding loop.
Boundary circuits which cross non-pattern edges:
If a boundary circuit is connected to non-pattern edges, then those
edges must occur in groups, each of which contains all the edges
coincident with a particular curve (e.g. if the feature consisted of a
chimney in the middle of a roof, the ridge curve of the roof would be
such a curve).
o There should be an even number of edges in each group, and at
the vertex where an edge meets the pattern faces, there must be
exactly one edge which is not adjacent to a pattern face (except
in the limiting case where two edges graze the pattern faces at a
single vertex).
o Each of the edges in a group must have the same number of
incident faces and the surfaces of these faces must be the same
or coincident.
o On transformation, it will be necessary to split existing edges
and perhaps also faces in order to accommodate an instance of the
face set. Any edges or faces which are to be split must either be
adjacent to the face set initially, or be edges and faces resulting
from earlier splits.
o Regions can not be split.
o If there are any boundary circuits of this type, then none of the
transforms may contain a reflection component.
Tracking and Error Information
The function returns overall and specific tracking information with
respect to the patterning operation. The tracking information relates
to the pattern faces themselves and not to other faces which may be
created due to splitting non-pattern faces; applications must not
assume anything about the order in which non-pattern faces or edges
are split since this is not defined and may change in future if
internal algorithms are changed. The amount of information returned
will depend on the state of result field in the return structure and
the data contained in the patterns array :
Patterning result array is empty
The patterning operation has failed outright and no individual
pattern data is returned. The result field will contain a
value that reflects the reason for the failure. The error_topols
array may also contain topological data that will help identify
the reason for the failure.
This situation will typically arise if there is something wrong
with the input data.
Result flag indicates partial success
If the result flag indicates partial success by containing the
value, PK_pattern_result_partial_c, the patterns array will contain
a pattern data structure for each patterned feature. This array will
map one-to-one with the transforms array input to the function.
Each pattern data structure only contains data pertaining to a single
instance of the pattern. The status field indicates whether the
instance of the pattern was successful.
o If the instance of the pattern was successful, then the
pattern_faces array will contain the newly created faces
of the pattern. This array will map one-to-one with the
pattern_faces input to the function.
o If the instance of the pattern was unsuccessful, and the instance
has not been removed from the body, then the pattern_faces array
will contain the newly created faces of the pattern. The
error_topols array may contain topological data that will help
identify the reason for the failure (e.g. faces which have been
found to clash).
Result flag indicates complete success
If the result flag indicates complete success by containing the
value, PK_pattern_result_ok_c, the patterns array will contain a
pattern data structure for each patterned feature. This array
will map one-to-one with the transforms array input to the function.
Each pattern data structure only contains data pertaining to a single
instance of the pattern. Every status field of the pattern data
structures will indicate a successful operation.
In each pattern data structure, the pattern_faces array will contain
the newly created faces of the pattern. This array will map one-to-one
with the pattern_faces input to the function.
State of the Body
If the value of the result field contains anything other than the
PK_pattern_result_ok_c code, then the input body should be considered
to be in an invalid state. In other words, it will fail to check.
If the value of the result field does contain the PK_pattern_result_ok_c
code, then the application programmer still needs to consider the
following :
o If no checking was specified in the options, the resultant body
may be inavlid.
o If checking was specified in the options, the instances of the
pattern may clash.
Pattern Checking
By default and for reasons of performance, minimal checking of the
patterned features takes place. The amount of checking the function
undertakes is controlled via the check flags in the option structure.
Where creation of instances requires edges or faces to be split, then
certain basic checks are always performed. The points in a group of
edges at which splits are to be made are checked for consistency - if
a clash between two instances is implied, then the later instance is
removed and its returned status will be
PK_pattern_status_outside_fa_c.
o Loop checking is controlled via the check_loops flag and, if
enabled, the function checks for clashes between new edges in an
instance and existing edges which share a face with each other and
also ensures that complete new loops lie inside a face. No loop
checking is performed for pairs of new edges; thus, there may be
clashing edges in different instances in the result, even if loop
checking is on.
If the loop check for a particular pattern instance fails :
o The instance of the pattern is removed from the body.
o A suitable status is returned via the pattern data results
structure which may also include a clashing edge in the
error topology.
o Face-face checking is controlled via the check_fa_fa flag and if
enabled, the function checks if any there are any clashes between
the faces of each instance of the pattern and the non-pattern faces
of the original body.
No face-face checking is performed between instances of the pattern.
If the face-face check for a particular pattern instance fails :
o The instance of the pattern is NOT removed from the body.
o A suitable status is returned via the pattern data results
structure which will include error topology. The error topology
array will contain pairs of clashing faces. Each pair will be
returned in the format, pattern face followed by clash face :
error_topols[ pattenface1 clashface1 patternface2 clashface2 ...]
