PK_FIN_euler_glue

PK_ERROR_code_t PK_FIN_euler_glue
(
--- received arguments ---
int             n_fins,     --- number of fins
const PK_FIN_t  fins[],     --- fins to glue
PK_LOGICAL_t    same_dir    --- orientation of fins belonging to second edge
)


This function glues fins from two edges in the order indicated so that in the
result the fins all belong to one edge.


Specific Errors:

    PK_ERROR_bad_fin                'fins' does not contain the complete set
                                     of fins from the edges, contains a
                                     duplicate, re-orders the fins of an
                                     edge or fins from an edge are not
                                     given contiguously.

    PK_ERROR_wrong_number_edges     the total number of edges referenced by
                                    'fins' is not two.

    PK_ERROR_edge_closure_mismatch  the two edges referenced by 'fins' are not
                                    of the same closure type eg open, closed
                                    or ring.

    PK_ERROR_bad_sharing            Incorrect value of 'same_dir' supplied when
                                    edges already share a vertex.

    PK_ERROR_non_manifold           Generalised topology is disabled and the
                                    owning part(s) of the edges are general
                                    or the part resulting from the glue
                                    operation would be general.




This function glues fins from two edges in the order indicated so that in the
result the fins all belong to one edge. The edge of the first fin in 'fins'
will survive, the second edge is deleted.

'fins' must contain the complete set of fins from two distinct edges.

The order of fins about an edge is cyclic so that PK_FIN_ask_next_of_edge may
be used repeatedly to return to the fin first visited.

The fins in 'fins' which belong to each edge in turn must preserve the
cyclic order of that edge and must appear as a contiguous sequence so that
fins of the second edge are all inserted at the same point in the cyclic
sequence of fins from the first edge.

The first fin of each edge (as given by PK_EDGE_ask_first_fin)
may appear at any position in 'fins' as 'fins' is treated as a cyclic array.

The two edges must each have at least one fin, the edges must have the
same number of vertices (zero, one or two).

The order of fins in the surviving edge will be as indicated by 'fins'. The
cyclic nature of fin ordering means that the first fin of the surviving edge
as returned by PK_EDGE_ask_first_fin will not necessarily be the first member
of 'fins'.

No geometry is deleted or detached from its owning topology with the following
exceptions.

o A curve attached to the second edge is detached since the second edge does
  not survive; the caller is left to delete this curve if no longer required.

o Point geometry belonging to a vertex of the second edge is deleted along with
  that vertex unless it is shared by the surviving edge.

Attached geometries are not modified and do not affect the result, in addition
the precision of edges and vertices being of geometric nature is not altered
and will simply reflect the original values of the surviving topologies.

'same_dir' applies to the direction of the second edge.

If 'same_dir' is supplied PK_LOGICAL_true then fins from the second
edge will not change sign when transferred to the surviving edge.

If 'same_dir' is supplied PK_LOGICAL_false then fins from the second
edge will change sign when transferred to the surviving edge.

If the edges are not closed and share a common vertex and the vertex represents
the start of one edge and the end of the other edge then 'same_dir' must be
supplied with value PK_LOGICAL_false. Similarly if the common vertex represents
either the start of both edges or the end of both edges then the value of
'same_dir' must be supplied PK_LOGICAL_true. Failure to supply the correct
value of 'same_dir' in these cases will result in a return of
PK_ERROR_bad_sharing.

If the edges are from different parts then the contents of the part that owns
the second edge will be transferred to the part that owns the first edge, and
the part that owns the second edge will be deleted.

The resultant part will be general except when all of the following conditions
are met.

o 'fins' contains the fin from each of two laminar edges.
o  The original part(s) are manifold.
o  The resultant edge contains one positive and one negative fin

An error condition will arise if generalised topology is disabled and the other
criteria are not met.