PK_CURVE_embed_in_surf_2

PK_ERROR_code_t                   PK_CURVE_embed_in_surf_2
(
--- received arguments ---
PK_CURVE_t                        curve,        --- curve
PK_SURF_t                         surf,         --- surface
const PK_CURVE_embed_in_surf_o_t *options,      --- options

--- returned arguments ---
int                        *const n_spcurves,   --- no. spcurves returned
PK_SPCURVE_t              **const spcurves      --- spcurves
)


This function creates one or more spcurves by embedding a b-spline
representation of a specified section of a curve in parameter space
(or the Z=0 plane) into the parameter space of a given surface.

This function does not support facet geometry [NF]


Specific Errors:
    PK_ERROR_unsuitable_entity  'curve' is not a 2D b-curve or is not a
                                 3D b-curve or analytic curve lying in Z=0
                                 plane (MILD)
    PK_ERROR_bad_combination    'curve' is a line but no 'curve_interval' has
                                 been specified in the options (MILD).
    PK_ERROR_bad_interval       'curve_interval' has been specified but the
                                'curve' cannot be trimmed using it (MILD).
    PK_ERROR_invalid_geometry   'curve' does not make valid spcurves when
                                 embedded in 'surf' (SERIOUS)
    PK_ERROR_illegal_degeneracy 'curve' has a degeneracy which prevents it
                                 from being embedded in 'surf' to create valid
                                 spcurves (MILD)
    PK_ERROR_cant_extend         'curve' lies outside of 'surf' in parameter
                                 space, and the surface cannot be extended far
                                 enough to include the curve or the curve
                                 cannot be adjusted to lie within the surface
                                 (SERIOUS)


The 'curve' must be one of:

    1:  a 2D b-curve; that is it must either be a rational b-curve
        with a vertex dimensionality of 3, or a non-rational b-curve
        with a vertex dimensionality of 2. 2D b-curves that are not
        orphans or are not in the same partition as the surface into
        which it is to be embedded will be copied.

    2:  a 3D b-curve, line, circle or ellipse lying in the Z=0 plane
        These curves will be converted to a curve satisfying condition
        1 by contructing the exact 2D b-spline representation of the path
        followed by their (x,y) components in the Z=0 plane.

The 'options' structure may be used to specify a parametric sub-interval of
the whole curve to embed in the surface. The 'have_curve_interval' field of
the options structure should be set to PK_LOGICAL_true to indicate that the
embedding is to be confined to the parametric interval specified in the field
'curve_interval'. If `have_curve_interval` is set to PK_LOGICAL_false the
whole of the given 'curve' will be embedded in the parameter space of the
given 'surf'.

Note that the supplied 'surf' may be extended so that it includes the entire
area onto which the spcurves reach. In order to avoid modifying the 'surf' in
this way, you must ensure that any spcurve created does not leave the base
range of the 'surf' or specify an appropriate value in the 'geom_adjust'
option.

Each of the resulting curves will satisfy the degeneracy and continuity
conditions for an spcurve.  See documentation of PK_SPCURVE_sf_t.