PK_POINT_make_helical_curve

PK_ERROR_code_t         PK_POINT_make_helical_curve
(
--- received arguments ---
PK_POINT_t              point,          --- point
const PK_AXIS1_sf_t    *axis,           --- axis
PK_HAND_t               hand,           --- handedness
PK_INTERVAL_t           turns,          --- range of turns
double                  helical_pitch,  --- height of a single turn
double                  spiral_pitch,   --- increase in radius of a single turn
double                  tolerance,      --- used in approximations

--- returned arguments ---
PK_CURVE_t       *const curve           --- created bcurve
)


This function creates a helix, tapered helix or spiral by sweeping a point
about an axis. The curve will be created as a b_curve to a tolerance supplied
by the user.


Specific Errors:
    PK_ERROR_tolerances_too_tight   The requested tolerance could not be met.
                                    (MILD)
    PK_ERROR_cant_make_bspline      The requested curve could not be made.
                                    (SERIOUS)
    PK_ERROR_bad_parameter          Implied negative distance from the axis.
                                    (MILD)
    PK_ERROR_bad_tolerance          The requested tolerance is less than the
                                    session precision. (MILD)


The point is swept around the axis to form a helix, tapered helix or spiral.
The 'helical_pitch' is the distance along the axis moved in one turn and the
'spiral_pitch' is the distance moved away from the axis in one turn. These
distances may be negative. The 'turns' argument specifies how many complete
revolutions the curve should make. Note that in general, unless both ends of
the interval are whole numbers, the curve may extend beyond the required
number of turns in both directions. The curve will be supplied as an
approximate bcurve to the tolerance supplied.

If the 'spiral_pitch'  is zero then a helix will be generated.
If the 'helical_pitch' is zero then a spiral will be generated.
If both are zero error PK_ERROR_bad_parameter will be generated.
Otherwise a tapered helix will be generated.

The 'turns' argument need not include position 0.0 - the supplied point, but
must not imply a negative distance from the axis.

For example, if the following parameters are supplied :
A point distance 10 from the axis and a 'spiral_pitch' of 2.

A 'turns' parameter (-5 -1) would result in the spiral starting on the axis
and reaching a distance 8 from the axis over 4 turns.
A 'turns' argument of (-6 0) would not be allowed since -6 turns would result
in a distance to the axis of -2. This would result in PK_ERROR_bad_parameter.

If the 'hand' argument is PK_HAND_right_c then the curve will sweep
clockwise when viewed along the axis.