PK_ERROR_code_t                  PK_FACE_replace_surfs_3
(
--- received arguments ---
int                              n_faces,        --- number of faces
const PK_FACE_t                  faces[],        --- faces
const PK_SURF_t                  surfs[],        --- replacement surfaces
const PK_LOGICAL_t               senses[],       --- surface orientation
double                           tolerance,      --- tolerance for operation
const PK_FACE_replace_surfs_o_t *options,        --- options

--- returned arguments ---
PK_TOPOL_track_r_t        *const tracking,       --- tracking information
PK_TOPOL_local_r_t        *const results         --- status information
)


This function replaces the geometry of the given faces with the
supplied surfaces.

NOTE: This function supersedes PK_FACE_replace_surfs_2, which is
      now obsolete.



Specific Errors:
    PK_ERROR_bad_tolerance         (MILD) proposed edge tolerance is too small
    PK_ERROR_unsuitable_entity     (MILD) body is not a sheet or solid body
    PK_ERROR_wrong_entity_in_array (MILD) given faces are not from same body



Introduction
All geometry of the given faces is replaced by the given geometry in surfs.
The surface orientation with respect to the face is specified by the logical
value in senses.

The number of surfaces and sense flags passed to the function, via the
surfs and senses arguments, must be identical to the number of faces
in the faces array.


Recalculating Edge and Vertex Geometry
The geometry of the edges and vertices connected to any modified faces
will be deleted and recalculated. Where edges are adjacent to faces whose
geometry is being replaced, the edge curves are re-computed as the
intersection of the face surfaces.

The user can prevent the recalculation of the geometry of particular
edges and vertices by supplying the new edge and vertex geometry via the
edge_data and vertex_data fields within the function's option structure.
This data is optional and any edge or vertex, adjacent to a modified face,
not specified within the structures will have its geometry recalculated.


Surface Sense Parameters
The sense flag, supplied to the function via the senses array, for a
particular face/surface combination is interpreted as follows :

 o PK_LOGICAL_true
   When the new surface is attached to the face, the face normal must be
   in the same direction as the natural surface normal (as calculated by
   the function PK_SURF_eval_with_normal).

 o PK_LOGICAL_false
   When the new surface is attached to the face, the face normal must be
   in the opposite direction to the natural surface normal (as calculated by
   the function PK_SURF_eval_with_normal).


Restrictions and Limitations
The following restrictions and limitations apply to this function :

  o Where edges or faces (sharing a vertex or edge at the boundary of
    the faces to be modified) have geometry which is inextendable, it may
    not be possible to recalculate vertices or edges. This is because the
    curve or surface do not intersect the new surface. This is likely to
    occur for tolerant edges since SP-curves are inextendable.

  o If the specified faces belong to a sheet body, none of the faces may
    form part of the boundary of the sheet. Ie. the face must not have
    any laminar edges.
    This restriction does not apply if the laminar edge geometry is
    supplied by the user via the optional edge_data structure.


User options
The PK_FACE_replace_surfs_o_t structure contains user control options.
In particular, it supports the notion of replacement edge/vertex geometry
being supplied by the user.


Tracking Information
The PK_TOPOL_track_t structure contains topology tracking information on
the operation. In the case of this function, only tracking information
records of the type PK_TOPOL_track_derive_c may be returned, if faces
have been split or merged during the operation.


Error handling
If this function returns PK_ERROR_no_errors, the result of the operation
will be indicated by the value of the status field of the results
structure. When this value is not PK_local_status_ok_c or
PK_local_status_nocheck_c, it indicates an operation failure and an array
of entities involved in this failure is returned through the field
error_entities of the results structure, when possible.
For more information regarding the failure status code and the error_entities,
refer to the PK documentation of the PK_TOPOL_local_r_t structure.