PK_CURVE_make_surf_isocline

PK_ERROR_code_t  PK_CURVE_make_surf_isocline
(
--- received arguments ---
PK_CURVE_t       curve,        --- curve through which isocline surf passes
PK_INTERVAL_t    t_interval,   --- curve parameter range for which surf reqd
PK_VECTOR1_t     direction,    --- isocline direction
double           angle,        --- isocline angle
PK_HAND_t        which,        --- left or right hand isocline surf
PK_INTERVAL_t    range,        --- required extent of surface
double           tolerance,    --- tolerance for fitting surf through curve

--- returned arguments ---
PK_SURF_t *const surf          --- the isocline surface
)


This function makes an isocline surface 'surf' which passes through the
given 't_interval' of the given 'curve'.


The isocline is specified by 'direction' and 'angle'.

In general, two surfaces pass through the curve and satisfy the isocline
condition.  The convention used for selection is defined by analogy with
a mountain ridge from which descend two slopes:

    If you walk along the curve in the direction from the start parameter
    to the end parameter with your head pointing in the draw 'direction',
    then there are two isocline surfaces below you: one to your left and
    one to your right.

The selection is by the argument 'which' which may take either of the values:
PK_HAND_left_c or PK_HAND_right_c. The sign of 'angle' has no effect on the
resulting surface.

Along the curve, the surface will at least extend over the given
't_interval', but it will not necessarily be bounded by this.
The required extent of the surface away from the curve is specified by the
INTERVAL 'range' in distance units.
This measure is zero at the curve itself, positive along
the surface in the given 'direction', and negative in the opposite direction.
If the angle is pi/2 then positive values are in the direction of the cross
product of the curve tangent and the given 'direction'.
If the 'range' interval contains zero then the given 'curve' will be contained
in the resulting 'surf'.  If the projection of the surface in the given
'direction' would be self intersecting, then the 'range' is trimmed to avoid
this condition.

The function may, at times, have to use approximate geometry.
For such cases, 'tolerance' specifies an upper bound on the distance by which
a point on the actual geometry may deviate from its ideal position.
While the function will usually satisfy this constraint, it is not guaranteed.

If no surface exists which can satisfy the conditions (e.g. the given curve is
steep) then 'surf' is given the value PK_ENTITY_null.

If the given 'curve' belongs to the geometry of a PART, then the new 'surf'
will become construction geometry of that PART. Otherwise it will become
orphan geometry of the current PARTITION.