PK_BODY_knit

PK_ERROR_code_t                    PK_BODY_knit
(
--- received arguments ---
PK_BODY_t                          body,        --- target body
int                                n_topols,    --- number of topols
const PK_TOPOL_t                   topols[],    --- topols
const PK_TOPOL_t                   matches[],   --- matched topols
PK_BODY_knit_o_t                  *options,     --- options

--- returned arguments ---
PK_TOPOL_track_r_t          *const tracking     --- tracking information
)


This function assembles a body by merging paired topols from the 'topols'
and 'matches' array.



Specific Errors:

    PK_ERROR_general_body   (MILD/SERIOUS) generalised topology not enabled
                                           and result would be a general
                                           body
    PK_ERROR_missing_geom           (MILD) topol has no geometry
    PK_ERROR_inconsistent_geom      (MILD) matching topols have inconsistent
                                           geometry
    PK_ERROR_duplicate_array_item   (MILD) topol is duplicated in 'matches'
                                           array or appears in both arrays
    PK_ERROR_not_in_same_partition  (MILD) topols are not all in the same
                                           Partition
    PK_ERROR_unsuitable_topology    (MILD) matching topols are not vertex to
                                           vertex or edge to edge
    PK_ERROR_no_topols_from_target  (MILD) no 'topols' or 'matches' are from
                                           the target body
    PK_ERROR_contradictory_request  (MILD) the desired body type is general
                                           and session general topology is
                                           disabled





Introduction
This function joins a number of bodies together by fusing coincident topology.
This process is henceforth referred to simply as "knitting". It should be
noted that for classic bodies it is a purely topological operation which will
perform limited geometric checks.

The only topols permitted in the 'topols' and 'matches' arrays are vertices
and edges. A vertex may only be matched with a different vertex, and an edge
may only be matched with a different edge. PK_ERROR_unsuitable_topology is
returned if this condition is not met.

For classic bodies, the distance between each matched pair of topologies must
be within the sum of their tolerances. PK_ERROR_inconsistent_geom is returned
if this condition is not met by supplied vertex pairs, or any vertex pairs
indirectly provided by the supplied edges.

This function supports non-manifold bodies if session general topology is
enabled (see PK_SESSION_ask_general_topology).

For facet bodies, knitted topols will be accurate. Meshes may be adjusted to
ensure they meet at knitted topols.

For mixed bodies, matched pairs of edges featuring any facet geometry must
produce a locally manifold result.  PK_ERROR_general_body is returned if this
condition is not met.

There is a 1:1 matching between the two topol arrays such that an element
in the 'topols' array will be knitted to the element in the 'matches' array
with the same index. The two arrays should therefore be the same length defined
by 'n_topols'.  The 'matches' array must not contain duplicates and a
topol in the 'matches' array is not allowed to also be contained in the
'topols' array. Duplicate topols are permitted in the 'topols' array e.g.
to create non-manifold wire vertices.

'body' is the target body the application wishes to hold the final result of
the knitting operation. All the other body topology to be joined onto 'body' is
supplied indirectly in the two arrays of topols. All bodies except 'body'
involved in the knit will be destroyed. The topols from the 'topols' array
will survive the operation while those in 'matches' will be destroyed.

Tracking Information
The returned 'tracking' structure is for future enhancements. Currently, the
structure will always be returned with empty arrays.

Error Reporting
When an error occurs the function will, where possible, make extra information
related to the error available to the application via the Parasolid report
stream.

When PK_ERROR_inconsistent_geom is returned from the function a record of type
PK_REPORT_record_type_1_c with a status of PK_REPORT_inconsistent_geom_c will
be created for each pair of mismatched vertices. The vertices will be returned
in the 'old_items' list. The 'new_items' list will be empty.