PK_MESH_imprint_vectors

PK_ERROR_code_t                     PK_MESH_imprint_vectors
(
--- received arguments ---
PK_MESH_t                           mesh,           --- mesh
int                                 n_vectors,      --- number of vectors
const PK_VECTOR_t                  *vectors,        --- vectors
const PK_MESH_imprint_vectors_o_t  *options,        --- options

--- returned arguments ---
PK_MESH_t                    *const resultant_mesh, --- mesh with imprinted
                                                    --- vectors
PK_MVERTEX_t                 *const mvertices,      --- mvertices
PK_MESH_imprint_vectors_r_t  *const results         --- status information
)


This function imprints an array of vectors onto a mesh.


This function creates a copy of the given 'mesh' with the given 'vectors'
imprinted. The 'destination' of the new mesh may be specified by the 'options'.

The function may optionally return an mvertex array of the same length as the
vector array, where the ith mvertex comes from the ith vector. Note that
one mvertex may come from multiple input vectors if they are within session
precision of each other, and an input vector may be snapped to an existing
mvertex if they are within session precision.

If any vector is not within session precision of the mesh or not within
session precision of its corresponding parameter or mtopol (given in the
options structure), then the function will not imprint any vectors and
'resultant_mesh' will be PK_ENTITY_null. Additionally, all vectors which were
not within session precision of the mesh or their given parameter/mtopol will
have their indices in the input array included in the 'error_indices' array
in the 'results'.

A "cluster" is a set of input vectors which satisfy the following conditions:

1. It has at least two members.
2. Each member is within session precision of at least one other in the set.
3. No input vectors outside the set are within session precision of any member.
4. It does not have any smaller subsets satisfying the first three conditions.

The algorithm will attempt to resolve each cluster into a single vector which
lies within session precision of all the vectors in the cluster. If it is not
possible to resolve all the clusters, the function will not imprint the
vectors and 'resultant_mesh' will be PK_ENTITY_null. All vectors in the
clusters which cannot be resolved will have their index in the input array
included in the 'results'.

The function does not attempt to repair any defects in the 'resultant_mesh',
but will return any defects in the 'resultant_mesh' caused by imprinting the
vectors in the 'results'.