PK_MFACET_find_perimeters

PK_ERROR_code_t                      PK_MFACET_find_perimeters
(
--- received arguments ---
int                                  n_mfacets,  --- the number of mfacets
const PK_MFACET_t                    mfacets[],  --- the mfacets
const PK_MFACET_find_perimeters_o_t *options,    --- options

--- returned arguments ---
PK_MFACET_find_perimeters_r_t *const results     --- results structure
)


This function returns the perimeter mfins around a set of given mfacets.
Optionally, the set of mfacets can be expanded by a callback function that uses
the given mtopols as seeds to propagate out from.


Specific Errors:
    PK_ERROR_mtopols_not_same_mesh (MILD) 'mfacets' not all from same mesh.
    PK_ERROR_not_implemented       (MILD) 'track_type' option is not
                                          PK_MTOPOL_track_none_c
    PK_ERROR_callback_failed       (MILD) the callback function failed.
    PK_ERROR_bad_value             (MILD) the value of 'min_n_mfacets' is
                                          negative


A perimeter is defined as the set of mfins forming the boundary of a set of
mfin-connected mfacets. If the user does not supply a callback function
based on an mfin topology criterion, this boundary comprises every mfin of the
set of mfin-connected mfacets that does not have an adjacent mfin whose mfacet
is also in the set. Therefore, it includes the mfins of any inner loops or
holes within the mfin-connected set. Sets of mfacets connected only at
mvertices lie within distinct perimeters.

If the user supplies a callback function 'select_cb' based on mfin topology,
the perimeter boundary will comprise all the mfins at which the callback
function stopped the selection propagation by returning 'select' equal to
PK_logical_false. Therefore, the perimeter may include internal wire mfins.

This function returns the perimeters of the set of input mfacets as one or
more mloops. An mloop is a connected set of mfins ordered into a loop in the
direction of the mfins. Each mloop consists of at least two mfins. An mloop
cannot contain the same mfin more than once but more than one mfin in the
mloop may point to the same mvertex. See here for more information.

At most one perimeter bounds each set of mfin-connected mfacets. An
mfin-connected set of the received mfacets may form a closed set, for
example, all the mfacets of a topological sphere, and in that case that
set of mfacets will have no perimeter (and therefore no mloops).

The PK_MFACET_find_perimeters_o_t structure contains application control
options.

The mloops are returned in a PK_MFACET_find_perimeters_r_t structure.

The option 'select_cb' allows the application to pass a callback function
to control an mfacet propagation algorithm. This algorithm will propagate
outwards from the mfacets given as input in the argument `mfacets[]', which
now act as seeds of the propagation. The criterion for propagation must be
implemented in the callback function and this can either be formulated in
terms of adjacent mfacets or mfins.

An mfin is considered to be a wire mfin if both it and its adjacent mfin lie
on the perimeter of the mfacetset. This can only happen when a 'select_cb' is
supplied that has its 'select_mtopol_class' as PK_CLASS_mfin.  If such a
'select_cb' does not select an mfacet when given a particular mfin but that
mfacet is subsequently selected by propagating across one of its other mfins,
then the first mfin will be considered to be a wire mfin.  If the option
'select_wire_mfins' is set to PK_selector_type_include_c, these wire mfins and
their adjacent mfins will be included in the perimeter of the mfacetset.
Note that 'select_cb' should behave symmetrically: it should return the same
selection result for an mfin and its adjacent mfin. Otherwise,
PK_mfacet_find_perimeters will return PK_ERROR_callback_failed.