PK_ERROR_code_t                      PK_BODY_find_knit_pattern
(
--- received arguments ---
int                                  n_bodies,          --- array of
const PK_BODY_t                      bodies[],          --- bodies between
                                                        --- which to find
                                                        --- knitting pattern
const PK_BODY_find_knit_pattern_o_t *options,           --- options

--- returned arguments ---
PK_BODY_knit_pattern_t        *const knit_pattern,      --- knitting pattern
int                           *const n_absent_bodies,   --- bodies not included
PK_BODY_t                    **const absent_bodies      --- in pattern
)


This function constructs a knitting pattern by matching and splitting
coincident edges, then pairing them off into corresponding entries in
two edge arrays.


Specific Errors:
  PK_ERROR_cant_create_pattern    failure to create knitting pattern
  PK_ERROR_pattern_invalid        knitting would result in invalid body
  PK_ERROR_bodies_dont_knit       no coincident edges exist
  PK_ERROR_bad_type               body in the array is of incorrect type
  PK_ERROR_duplicate_array_item   a body is duplicated in the body array
  PK_ERROR_general_body           a general body is present in the array of
                                  bodies


  This function creates a knitting pattern which can be used as input
  to PK_BODY_apply_knit_pattern. The knitting pattern holds two arrays
  of edges, and an array of bodies. Corresponding elements in the arrays
  are coincident edges that will be fused in the resultant knitted body.

  The received body array bodies may contain either solid or sheet bodies
  but not wires. In the case of solids, all edges which the application
  intends to appear in the knitting pattern must have one adjacent face with
  a surface attached and one without. The faces in the solid without surfaces
  attached will be those which are eventually redundant when the resultant
  solid body is created using the pattern returned by
  PK_BODY_find_knit_pattern in a call to PK_BODY_apply_knit_pattern.

  The edges and matches fields of the returned knit pattern form the
  knitting pattern and n_edges is the length of each of these arrays.

  The reversals field of the knit pattern is an array of those bodies in
  the received bodies array that need to be reversed in orientation in
  order for application of the knitting pattern to succeed. These required
  reversals of orientation will by carried out by PK_BODY_apply_knit_pattern
  when the pattern is passed to it.

  The return argument absent_bodies is an array of those received bodies
  which have no edges appearing anywhere in the paired edge arrays of the
  knitting pattern.

  Negating some of the received bodies may not be sufficient to produce a
  valid knitted body. For example, knitting could result in a moebius strip.
  Such cases will be identified and will result in the error
  PK_ERROR_pattern_invalid.

  If none of the edges in the received bodies are coincident, the error
  PK_ERROR_bodies_dont_knit will be returned. If however a subset of bodies in
  the received list has coincident edges, a knitting pattern will be created
  and an error will not be invoked. The bodies with no edges in the pattern
  will be returned in absent_bodies array.

  Note that this routine may not preserve the topology of the received bodies:
  edges may be split in order to produce a 1:1 correspondence between the
  edges that form the pattern.

  This function is not supported for general bodies.