PK_ERROR_code_t                     PK_SURF_intersect_curve
(
--- received arguments ---
PK_SURF_t                          surf,       --- surface
PK_CURVE_t                         curve,      --- curve
PK_INTERVAL_t                      bounds,     --- interval
const PK_SURF_intersect_curve_o_t *options,    --- options structure

--- returned arguments ---
int                         *const n_vectors,  --- number of intersections
PK_VECTOR_t                **const vectors,    --- positions of intersections
PK_UV_t                    **const uvs,        --- parameters on surface
double                     **const ts,         --- parameters on curve
PK_intersect_vector_t      **const types       --- types of intersections
)


PK_SURF_intersect_curve finds the intersections between a surface and
a curve.


Specific Errors:
    PK_ERROR_invalid_geometry          invalid geometry
    PK_ERROR_not_on_curve              given parameters not on curves
    PK_ERROR_bad_end_points            bad end points
    PK_ERROR_bad_parameter             bad parameter given
    PK_ERROR_cant_do_intersect         intersection cannot be done





PK_SURF_intersect_curve finds the intersections between a bounded curve and a
surface. It returns an array of intersection coordinates and
an array of tokens classifying the intersections.
The intersections are ordered along the bounded curve,
and are classified according to the direction of the curve.

The intersection coordinates are returned in an array of length n_vectors; if
there are no intersections of the curve and surface within the bounds,
n_vectors is returned as zero and vectors is returned as null.
If n_vectors intersections are found the array ts contains n_vectors
corresponding curve parameters and uvs contains the corresponding
u,v pairs of surface parameters. The curve and surface parametrisations
are defined in the documentation of PK_CURVE_ask_param and PK_SURF_ask_params.
The surface parameters in uvs are only valid for simple and touch
intersections. For coincident intersections the values in uvs
are not defined.



The intersection types are returned in an array of length n_vectors.
There are four types of intersection, as follows:

    PK_intersect_vector_simple_c :  A simple intersection not
                                    adjoining a region of coincidence.
    PK_intersect_vector_tangent_c:  The curve touches the surface
                                    at a point.
    PK_intersect_vector_start_c  :  An intersection at the start
                                    of a region of coincidence.
    PK_intersect_vector_end_c    :  An intersection at the end
                                    of a region of coincidence.

Whether an intersection is at the start or end of a region of coincidence
is determined by the direction of the curve, curve. In the
current version regions of coincidence will only be reported when the curve
given is found to be coincident with the surface at all points within the
bounds supplied.

Coincident intersections are returned for all points
lying at the bounds of regions of coincidence, including the ends of the
bounded curve, which are coincident with the surface.



The interval of the curve to be intersected with the surface is specified
by giving start and end parameters. These are given in the argument interval,
in the order start and then end.
If the curve is a trimmed curve the supplied bounds are ignored. However
a valid interval should be supplied.



The option structure PK_SURF_intersect_curve_o_t contains two fields
the first is a logical whether_box, if this is true a box is provided in
the next field box, this describes the box that contains the area of
interest. The box is used to improve performance. No guarantee is made that
all the intersections returned will lie in it.

For a box to be valid the difference between the maximum and minimum
components in all three principal directions must be greater than zero.



Any B-curve or B-surface or offset surface must be capable of passing the
full checks imposed by PK_GEOM_check.