PK_ERROR_code_t PK_BODY_sew_bodies
(
--- received arguments ---
int n_bodies, --- number of bodies to sew
const PK_BODY_t bodies[], --- bodies to sew
double gap_width_bound, --- lower bound on gap width
const PK_BODY_sew_bodies_o_t *options, --- options on sewing
--- returned arguments ---
int *const n_sewn_bodies, --- number of sewn bodies
PK_BODY_t **const sewn_bodies, --- bodies produced by sewing
int *const n_unsewn_bodies, --- number of input bodies
--- not sewn
PK_BODY_t **const unsewn_bodies, --- input bodies not sewn
int *const n_problem_groups,--- number of problem
--- edge groups
PK_BODY_problem_group_t **const problem_groups --- problem edge groups
)
This function attempts to sew the received bodies together where they have
edges common to within a given tolerance upper bound.
Specific Errors:
PK_ERROR_bad_type One of the bodies in the list is of the
incorrect type.
PK_ERROR_bad_value No sheets provided for sewing
PK_ERROR_bad_iteration_count The requested number of iterations was
less than one.
PK_ERROR_bad_gap_bound A bad gap width bound was supplied in
the option field 'iteration_bounds' when
requesting sewing to make multiple sewing
attempts
PK_ERROR_bodies_dont_knit No coincident edges could be found
PK_ERROR_duplicate_array_item One of the bodies supplied is duplicated
PK_ERROR_corrupt_body One of the bodies supplied was corrupted by
the sewing operation
PK_ERROR_non_manifold The result of the sew would be non-manifold
PK_ERROR_sewing_failure The sewing algorithm produced an internal
error that forced early termination of the
operation.
PK_BODY_sew_bodies sews a collection of sheet bodies ( presented in the array
'bodies' ) together by glueing them where their edges 'meet'. The notion of
'meeting' is governed by the received parameter 'gap_width_bound'. This
parameter sets a lower limit on the width of gap between sheets that will be
allowed to remain. Where gaps thinner than this occur, PK_BODY_sew_bodies will
make every effort to glue both sides of the gap together.
Sewing proceeds by picking the first body in the 'bodies' array and finding all
other sheet bodies that can be glued, either directly or indirectly, onto it.
This collection of bodies is merged into a single connected result body. The
connectivity is achieved through fusing together all pairs of edges that were
found to be close enough to each other. Subject to options ( discussed below ),
this process will be repeated on another target picked from those bodies not
involved in the sewing so far. Sewing will complete once no more bodies are
available to be selected as a target.
Sewing by default makes a single attempt to sew sheets as described in the
previous paragraph. During this attempt it uses the specified value of
'gap_width_bound' to determine which edges are close and which are not.
It is possible to request that sewing make repeated attempts to sew the sheets
together. This is achieved by setting the option field 'number_of_iterations'
to a value greater than 1. Each iteration will be performed on all the sheets,
sewn or not, returned by the previous sewing attempt.
When iterating, an array of gap width bounds may be supplied in the option
field 'iteration_bounds' where it is desired that sewing iterate over specific
values for the gap width bound. The array is expected to hold one value of gap
width bound for each iteration. Sewing will attempt using the bounds in the
order in which they are provided. Alternatively the 'iteration_bounds' field
may be set to NULL. PK_BODY_sew_bodies will in this case generate an ascending
sequence of gap width bounds to iterate over, terminating in the value given
in the argument 'gap_width_bound'. Where the bounds are to be automatically
selected, then the value of 'gap_width_bound' must exceed 1.0e-7 to give
the iteration some room for maneouvre. If the value offered is too small, then
sewing will return the error PK_ERROR_bad_iteration_bound.
The return arguments of the procedure hold the results of the sewing operation
and some information on what could not be sewn and why. The successful element
of the sewing operation is reflected in the array 'sewn_bodies'. This array
holds all of the bodies produced by sewing at least two of the received sheets
together.
PK_BODY_sew_bodies will in general try to return the ifail PK_ERROR_no_errors.
It will do this even where there have been problems encountered during the
sewing operation. This is necessary to allow the function to pass out
information on these difficulties, since the return of any other ifail
severely limits what may be passed out with it.
To find the real limits of a successful call to PK_BODY_sew_bodies the
application must look through the information covered in the less successful
part of the information returned. This is held in the arrays 'unsewn_bodies'
and 'problem_groups'. 'unsewn_bodies' will hold all of those bodies presented
in the received 'bodies' array that had no other received sheet body sewn onto
them ( though they may have been modified during the edge matching process to
resolve difficulties there ). 'problem_groups' is an array of structures each
of which holds an array of edges associated with a single problem found during
sewing, and a token indicating the believed type of that problem. These types
are listed in the documentation of the structure type PK_BODY_problem_group_t.
Of them PK_BODY_sewing_non_manifold_c, and PK_BODY_sewing_non_oriented_c are
returned only where the options set are inconsistent with a result possessing
either attribute. Whatever the application considers to be the worst problem
type reported in the 'problem_groups' array, will in general be the 'true'
limit of the operations success.
The content of the returned arguments, and some potential properties of the
returned sewn bodies are limited by the options available in the received
options structure. Documentation of these options is available in that provided
on PK_BODY_sew_bodies_o_t.
