PK_ERROR_code_t   PK_BODY_embed_in_surf
(
--- received arguments ---
PK_BODY_t         body,      --- sheet body to receive message
PK_SURF_t         surf,      --- new surface for sheet body
double            tolerance, --- tolerance for SPCURVE generation

--- returned arguments ---
int        *const n_edges,   --- number of edges converted to SPCURVEs
PK_EDGE_t **const edges      --- edges converted to SPCURVEs (optional)
)


This function constructs the representation of a sheet body in the parameter
space of its existing surface and embeds that in the parameter space of a
new surface.


Specific Errors:

    PK_ERROR_not_in_same_partition  body and surf in different partitions
    PK_ERROR_failed_to_replace      unable to replace surface of sheet
    PK_ERROR_not_sheet              body is not a sheet body
    PK_ERROR_missing_geom           sheet has no surface attached
    PK_ERROR_unsuitable_entity      sheet has more than one non-rubber face
    PK_ERROR_wrong_surface          surf is not compatible with sheet's surf
    PK_ERROR_bad_sharing            illegal sharing of surf
    PK_ERROR_bad_tolerance          edge too short for tolerance
    PK_ERROR_invalid_geometry       surf fails continuity checks


The surface of the sheet is tweaked to the new surface while the
parameter space representation of the edges is maintained.

The supplied body must be a sheet body, which must have only
one face and there must be a surface attached to the face.

The new surface, surf must be of the same type as the surface currently
attached to the face of the sheet or an offset of that type. The new
surface must also have the same bound classification, as given by
PK_SURF_ask_params, as the surface of the face and must be capable of
passing the checks imposed by PK_GEOM_check.
Continuity checks are also performed on surf if requested by
PK_SESSION_set_check_continuity.

If the curve of an edge is an SPCURVE or a constant parameter
curve of the surface of the face then it will be transfered to the new
surface.

All other edges will be converted to SPCURVEs using the supplied
tolerance and then transfered to the new surface. It is an
error if any of these edges are shorter than twice the
tolerance. During the conversion the edges may need to be split at
surface discontinuities.

The number of edges whose curves have been converted to SPCURVEs will be
returned in n_edges.

The argument edges is optional.  If it is set to NULL then only n_edges is
returned.  Otherwise edges returns the array of edges whose curves have
been converted to SPCURVEs.

NOTE that PK_BODY_embed_in_surf will not replace the surface of a
blend face (PK_CLASS_blendsf).