[Bf-python] Curve API

[Stephen Swaney]

Lately I've been playing with the Curve interface.
The purpose of this message is to describe what I
think the Curve interface needs and to get your feedback.
Comments are welcome.

First some terminology:

A blender Curve consists of a number of splines.
Adding a curve via the blender interface gives
a Curve with a single spline.  Adding a Curve
with the python Curve.New() method gives a Curve
with 0 splines.  Multiple splines can be added
to a Curve in blender edit mode.  

Blender does not seem to mind if a Curve contains 
both nurb and bezier splines.  ( this seems weird, 
but is probably due to the historical Dutch tradition
of open mindedness. )

Splines come in two flavors:  bezier and nurb.
The control points for a nurb spline consist
of 4 values: x,y,z,w coordinates.
The control points for a bezier spline consist
of 9 values: 3 sets of x,y,z coordinates.  These
correspond to the 'control point' and it's two handles.

Current stuff:

The current Curve API provides methods to create an empty
Curve, fetch an existing Curve and methods to get and set
a whole pile of attributes.  The get/setControlPoint() methods
only work on existing control points.

New stuff:

The next step in building out the Curve interface is to add
methods to get counts for the number of splines in a curve 
and the number of control points in a spline.  We also need
methods to add new splines to a Curve and to add new points
to a spline.

All the methods below throw exceptions for out-of-range
input parameters or if Bad Things happen.

Here are prototypes for the new methods:

  getPointCount()

get a list of the number of control points in each spline in
the Curve, one value for each spline in the Curve.  
return type: list of integers


  getNumPoints( int spline_num )

get the number of control points for given spline.  
return type: integer


  getNumSplines()

get the number of splines in the Curve
return type: integer


  isNurb( int spline_num )

boolean function to test whether a given spline is a nurb spline
or a bezier.
returns 1 if spline is type nurb, returns 0 otherwise
return type: integer


  getSpline( int spline_num )

get a list of the control points that make up a given spline. 
Each spline point in the list is represented as a list of coordinates. 
Nurb spline points are 4 values - x,y,z,w. 
Bezier spline points are a list of 9 coordinates, 3 sets of x,y,z
values representing handle_1, the controlpoint and handle_2.
return type:  list of lists of float


  putNurbSpline( list_of_coords, optional int spline_num )

adds or replaces a nurb spline in the Curve. 
The list_of_coords arg is a list of control points for a nurb spline. 
Each control point is a list of 4 homogenous coordinates [x,y,z,w]. 
return type: none

The spline_num param is optional. 
If omitted, the spline is added to the Curve as a new spline. 
If spline_num is present, the list of coordinates replace that spline
in the Curve.


  putBezierSpline( list_of_coords, optional int spline_num )

adds or replaces a bezier spline in the Curve. 
The list_of_coords arg is a list of control points for the spline. 
Each control point is a list of 9 values representing the x,y,z 
coordinates of a bezier control point. 

The spline_num argument is optional. 
If present, that spline in the Curve is replaced by the list_of_coords. 
If spline_num is omitted, the new spline is added to the Curve. 


More stuff:

It would probably be nice to have some convenience functions
for creating nurb and bezier circles.

If we are going to have an isNurb() method, should we have
an isBezier() method for symmetry?  Are there other types
of Curves we shoud support?


Curves vs Surfaces:

Both Curves and Surfaces share an underlying Nurb data structure.
However, they are presented to the user as two separate
types in blender.  They have different sets of edit buttons 
and different properties even though there are Curve curves
and Surface curves.  Only Surface curves can be lofted or skinned,
for example.  

Because of these differences, I would argue for creating separate 
Surface and Curve modules.

As I said, the purpose of this message is to get feedback.  
Comments *are* welcome.

Let the arguments begin!

Stephen
-- 
Stephen Swaney			
sswaney at swbell.net