PK_ERROR_code_t                   PK_FACE_intersect_surf
(
--- received arguments ---
PK_FACE_t                         face,       --- face
PK_SURF_t                         surf,       --- surface
const PK_FACE_intersect_surf_o_t *options,    --- options structure

--- returned arguments ---
int                        *const n_vectors,  --- number of point intersections
PK_VECTOR_t               **const vectors,    --- posns of point intersections
int                        *const n_curves,   --- number of intersection curves
PK_CURVE_t                **const curves,     --- intersection curves
PK_INTERVAL_t             **const bounds,     --- bounds of curves
PK_intersect_curve_t      **const types       --- types of intersections
)


PK_FACE_intersect_surf finds the intersections between a face and a surface.


Specific Errors:
    PK_ERROR_missing_geom              missing geometry
    PK_ERROR_invalid_geometry          invalid geometry
    PK_ERROR_not_on_curve              given parameters not on curves
    PK_ERROR_bad_option_data           bad option structure data
    PK_ERROR_bad_shared_entity         face and surface from different bodies
    PK_ERROR_cant_do_intersect         intersection cannot be done



 PK_FACE_intersect_surf finds the intersections between a face (face)
 and a surface (surface), returning intersection points (vectors)
 and curves of intersection (curves).

 The surface (surf) must be an orphan or owned by the same body as face.
 If surf is not an orphan any curves will be created as construction
 geometry in the body.

 If surf is an orphan and any of the curves returned are of type
 intersection curve then these curves will refer to surf and a copy
 of the surface of the face.

 No attempt is made to define surface regions of partial coincidence, and
 if the surfaces are fully coincident no intersection data will be returned.

 The returned points (vectors) will be returned at points where the surface
 and face make point contact. n_vectors indicates the number of intersection
 points.

 The curves returned (curves) will be the basis curves of trimmed curves,
 and their corresponding bound in bounds,  n_curves indicates
 the number of curves returned.

 types classifies curves as being either:

      PK_intersect_curve_simple_c : Simple intersection curves
   or PK_intersect_curve_tangent_c: Tangent intersection curves

 The available fields in the option structure PK_FACE_intersect_surf_o_t are as
 described below:

 The option have_box indicates whether a box has been specified
 (default = PK_LOGICAL_false)

 The option box enables a 3-space box of interest to be supplied. The
 box may be used to improve performance. The intersection curves returned
 are not guaranteed to lie within the bounds of the box.

 The option have_uvbox_1 indicates whether a uvbox_1 has been specified.
 The option have_uvbox_2 indicates whether a uvbox_2 has been specified.

 The options uvbox_1 and uvbox_2 enable the supplying of parameter boxes
 for the face and the surface respectively. Again these
 boxes are only used to constrain the region of interest for performance
 purposes. The intersection curves returned are not trimmed to lie
 within the boundaries of the parameter box/es.
 Four parameters should be supplied to define the parameter box, U-min,
 U-max, V-min and V-max.

 The option have_vector indicates whether a uvbox_2 has been specified.

 The option vector enables a point on a branch of the intersection to be
 specified (by supplying the x, y, and z coordinates). For this
 case only the branch of the intersection on which this point lies will be
 returned.