PK_FACE_replace_surfs_3

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 [PF]

--- 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.

This function offers partial support for facet geometry [PF]


Specific Errors:
    PK_ERROR_bad_tolerance         (MILD)    proposed edge tolerance is too
                                             small
    PK_ERROR_wrong_entity_in_array (MILD)    given faces are not from same body
    PK_ERROR_missing_geom          (MILD)    replace geometry not specified
                                             for laminar edges in the supplied
                                             'edge_data'.
    PK_ERROR_not_in_same_partition (MILD)    faces and replacement orphan
                                             geometry not in same partition
    PK_ERROR_bad_combination       (MILD)    a mixture of facet and classic
                                             geometry has been supplied
    PK_ERROR_non_manifold          (SERIOUS) 'faces' are not locally manifold



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.

The faces can belong to a general body, so long as they are locally manifold.
The replace cannot cause the faces to clash with non-manifold regions of the
body.

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.

  o Any edge with mixed geometry after the operation which has been supplied by
    the user via the optional 'edge_data' structure must have a minimum
    tolerance of 5 times session precision.


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.