PK_ERROR_code_t                       PK_BODY_apply_knit_pattern
(
--- received arguments ---
const PK_BODY_t                       body,         --- target body
const PK_BODY_knit_pattern_t         *knit_pattern, --- knitting pattern
                                                    --- to be applied
const PK_BODY_apply_knit_pattern_o_t *options,      --- options

--- returned arguments ---
PK_BODY_knit_result_t          *const knit_result   --- status, edges not knit
)


This function assembles a composite sheet or solid body by merging paired edge
in the knit pattern


Specific Errors:

  PK_ERROR_corrupt_body           Corrupted target body
  PK_ERROR_bad_type               bad type
  PK_ERROR_wire_body              An edge in the pattern is from a wire body
  PK_ERROR_no_eds_from_target     No edges in the pattern are from target body
  PK_ERROR_instanced_tools        An edge is from an instanced (non-target)
                                  body
  PK_ERROR_duplicate_array_item   The same edge appears in both lists or twice
                                  in one of the lists
  PK_ERROR_not_in_same_partition  Edges are not all in the same partition
  PK_ERROR_general_body           One of the edges is owned by a general body



  This function joins a number of faces or bodies together by fusing coincident
  edge topology. This process is henceforth referred to simply as "knitting";
  it should be noted that it is a purely topological operation which will NOT
  perform any geometric checks whatsoever.

  body is the 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 edges held in the knitting pattern
  supplied in knit_pattern. body must be a  solid or sheet body, and all
  edges in the knitting pattern must be edges of solids and/or sheets. All
  bodies except body involved in the knit will be destroyed. The edges in
  the edges array within the knitting pattern will survive the knit while
  those in matches array of the same pattern will be destroyed. The outer
  shell of body will also be the outer shell of the result.

  The two edge arrays of the knitting pattern specify matching edge pairs to
  be fused together. These must not contain duplicate entries. In addition, at
  least one edge from the target body must appear in the pattern and any
  edge not in that target body must not come from an instanced body.

  Pairs of edges in corresponding positions in the edges and matches
  arrays of the knitting pattern will be knitted together, provided that
  these corresponding edges satisfy the following:

      (1) they match up 1:1, i.e. every edge in edges has ONE partner in
         matches
      (2) they have the same number of distinct vertices.
      (3) an edge in sheet body has only one adjacent face and a face in
          a solid body has one adjacent face with a surface attached and
          one without.

  The 1:1 matching is done automatically by other routines in the most common
  uses of PK_BODY_apply_knit_pattern. In Partial Booleans the pattern edge
  lists are made up by PK_BODY_imprint_body and then further filtered by
  PK_BODY_identify_facesets. PK_BODY_find_knit_pattern can also be used to
  infer the connectivity of an assemblage of sheets. The application can, of
  course, create a knitting pattern itself, though it then runs the risk of
  creating an inconsistent body if geometric tolerance requirements are not
  met.

  The option field body_type enables the application to force the type
  (PK_BODY_sewing_solid_c or PK_BODY_sewing_sheet_c) of the result body.
  If the token PK_BODY_sewing_any_c is supplied then a solid will be
  created if possible (i.e. if the knitting operation encloses a volume) and a
  sheet will be created otherwise.

  The option field sort_face_shells enables the application to control
  whether PK_BODY_apply_knit_pattern attempts to sort the resulting faces
  into their respective shells. This operation will not need to be done
  when PK_BODY_apply_knit_pattern is used within a partial Boolean.

  The returned structure knit_result holds information about the edges that
  were not knitted together, and the level of success in applying the knitting
  pattern.

  Within knit_result the array unknit_edges contains all those edges from
  the edges array within knit_pattern which did not knit together because
  of a failure to meet the conditions described above.

  In the cases where a solid body was required ('type' PK_BODY_sewing_solid_c)
  the unknit_edges array will additionally contain all edges in the result
  body which have only one adjacent face with a surface attached. The presence
  of such edges in a  knitted solid is a consequence of the received knitting
  pattern being incomplete (i.e. edges were omitted from the knitting pattern
  which were necessary in order to successfully enclose a volume). The status
  field of knit_result will be set to PK_BODY_knit_not_completed_c
  in such cases, though all edges not in unknit_edges will still have been
  knitted successfully.

  The status field of knit_result will normally be set to
  PK_BODY_knit_completed_c on a successful knit. Note that the error
  PK_ERROR_corrupt_body should never be returned in normal operation,
  and indicates either an internal failure or a corrupt input body.

  This function is not supported for general bodies.