PK_ERROR_code_t      PK_CURVE_make_spcurves
(
--- received arguments ---
PK_CURVE_t           curve,       --- curve
PK_INTERVAL_t        range,       --- parameter bounds of reqd part of curve
PK_SURF_t            surf,        --- surface on which curve lies
PK_LOGICAL_t         degenerate,  --- create degenerate spcurves
PK_LOGICAL_t         sense,       --- spcurves in same dirn. as 'curve'
double               tolerance,   --- required accuracy if soln. is approx

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


This function creates an SPCURVE representation of a curve which lies,
possibly approximately, in a surface.


Specific Errors:
    PK_ERROR_bad_precision           tolerance less than modelling resolution
    PK_ERROR_tolerances_too_tight    tolerance too tight
    PK_ERROR_failed_to_create_sp     no spcurves made


This function approximates curve which lies approximately on surf by an
SP_Curve or series of SP_Curves, lying on surf.

The arguments are:


curve

   Curve to be approximated by SP_curve(s)

   Lies approximately on 'surf'.


range

   Parametric extent of the part of the given curve to be represented by one
   or more SP-Curves.

   If the range is sufficiently long to overhang the parameter range of a
   limited surface, then the surface may be extended in order to accommodate
   the SP-curve(s).

   If the given curve is a trimmed curve, then the range must be contained
   within the bounds of the trimmed curve.

surf

   Surface upon which to create SP_Curve(s), 'surf' forms the basis surface
   of the new SP_curve(s).

   If 'surf' is construction geometry or is attached to a face, within a
   body, the SP-curve will be created as construction geometry
   in that body, and may only be attached to topology within that body.


degenerate

   Sp_curves may start or end on surface degeneracies, may lie entirely
   within them, but may not pass through them. A trimmed curve which passes
   through a surface degeneracy will be approximated by at least two
   SP_Curves. If 'degenerate' is PK_LOGICAL_true a zero length SP_Curve will be
   returned which joins the otherwise disjoint SP_Curves in parameter space.
   Zero length SP_Curves may not be attached to a model.


sense

   If sense is PK_LOGICAL_true, then the created SP-curve(s) will start at
   the beginning of range and end at the end of range.  If sense is
   PK_LOGICAL_false, then the SP-curve(s) will be in the opposite direction.


tolerance

   The SP-Curve will be created to the distance tolerance tolerance, i.e. it
   lies within tolerance of the image of curve in the surface. The image of
   curve in this context means the curve formed by the locus of points
   on surf closest to corresponding points on curve.

   If the required tolerance cannot be met then the function will fail with
   error PK_ERROR_tolerances_too_tight indicating that
   a larger tolerance may allow a successful approximation.


The returns are


n_spcurves

   Number of SP_curves produced


spcurves

   Array of SP-Curves of length n_spcurves.



Ownership

The ownership of the newly created SP_Curve(s) is determined by the ownership
of surf as follows

    |____________________|___________________|
    | surf owner       | SP_Curve owner    |
    |____________________|___________________|
    | Partition          | Partition         |
    | Assembly           | Assembly          |
    | Body               | Body              |
    | Face               | Body owning face  |
    _____________________|___________________|