PK_SURF_intersect_curve

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_ERROR_mixed_geometry            cannot intersect foreign and facet
                                       geometry





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.