**************************************************************************
**************************************************************************
              SPLINE GENERATOR FOR PERSISTENCE OF VISION 3.x
**************************************************************************
**************************************************************************

Created by Chris Colefax, February 1997

1.0  INSTALLATION
2.0  QUICK START
3.0  CREATING SPLINE FILES
        3.1  CREATING MULTIPLE SEGMENTS IN A SPLINE FILE
        3.2  CREATING A LOOPING SPLINE
        3.3  CREATING STRAIGHT LINE SEGMENTS
        3.4  CREATING SHARP CORNERS
        3.5  USING SPLINER.INC
4.0  USING SPLINE FILES IN POVRAY SCENE FILES
        4.1  PREVIEWING A SPLINE
        4.2  USING A SPLINE FOR ANIMATION
        4.3  CREATING SPLINE BASED OBJECTS
5.0  CONTACTING THE AUTHOR

**************************************************************************


1.0  INSTALLATION
**************************************************************************
Copy the three POVRay include files (Spline.inc, SplineR.inc, ShowSpl.inc)
to one of the directories (folders) in your POVRay library path.  Normally
this is the INCLUDE sub-directory of the directory where you installed
POVRay, so if you installed POVRay in C:\POVRAY you should copy the
include files to C:\POVRAY\INCLUDE.  On a Windows 95 system, this is
probably something like:

   C:\Program Files\POV-Ray for Windows\Include

On UNIX and similar systems, where filenames are case-sensitive, you may
have to rename the includes file to Spline.inc, SplineR.inc, and
ShowSpl.inc, rather than all uppercase or all lowercase.  If you want to
render the sample files you should also check that the naming of Smooth.spl,
Unsmooth.spl, Landscap.pov, and Map.gif are as shown.  This will enable you
to render the sample files without modification.


2.0  QUICK START
**************************************************************************
The POVRay Spline Generator allows you to create smooth spline objects for
use in a POVRay scene file simply by specifying a number of control
points, in a similar way to POVRay's lathe, prism, and surface-of-
revolution (sor) objects.  However, with the POVRay Spline Generator you
can specify your control points using three-dimensional vectors, and the
generator will automatically calculate a smooth spline that passes through
each point!  You can then use the splines to position your camera,
light_sources, and objects in animations, or to create smooth spline-based
objects.

The first step when using the spline generator is to create a spline file
which specifies the control points of the spline.  Then you specify how
far along the spline you wish to move and the generator will give you a
vector indicating the current position of the spline, eg. If you have
created a spline file called "MySpline.spl" and wish to know the position
of this spline halfway along its length, you would add the following lines
to your scene file:

   #declare spline_clock = .5
   #include "MySpline.spl"

The generator would then create a variable called "spline_pos" which
contains the position halfway along the spline, which you can now use to 
position your object, camera, etc, eg:

   camera {location spline_pos look_at <0, 0, 0>}
   object {MyObject translate spline_pos + <10, 5, 0>}


3.0  CREATING SPLINE FILES
**************************************************************************
Before you can use the spline generator you must create a spline file,
which contains a list of the points needed to define the spline, as well
as other options you can use to modify the spline.

Each spline is made up of a number of segments, each segment being a
smooth curve which joins two points (point1 and point2).  In addition to
these two points you must also specify two other points for each segment
which control the curvature of that segment (point0 and point3).  After
declaring these four points you then include the spline generator file.

A simple curved spline file would look like this:

   #declare point0 = <-5, -3, -5>
   #declare point1 = <-5,  0, -5>
   #declare point2 = < 5,  0,  5>
   #declare point3 = < 5, -3,  5>
   #include "Spline.inc"

This would create a curve which goes from point1 <-5, 0, -5> to point2
<5, 0, 5>.  Because of the positions of the curve control points (point0
and point3) the curve would arch upwards in the middle.  How do we know 
this?  Well, we can see that point0 is 3 units 'below' point1 (we shall
consider that +y is up), and that point3 is 3 units below point2.

Now imagine drawing a line up from point0 to point1, and then continuing
the line a little above point1.  The direction of this line is the
direction that the spline starts moving in as it leaves point1.

Now, do a similar thing with point2 and point3, drawing a line up from
point3 to a little past point2.  The direction of this line is the
direction that the spline will be moving as it reaches point2.

To create the curve the spline generator will start at point1, facing in
the direction of the line from point0 to point1. It will then start moving
in that direction, as well as moving towards point2.  Then, as it nears
point2 it will make sure that it is facing in the direction from point2 to
point3, until it finally reaches point2.

Therefore, if we had #declared point0 = <-5, 3, -5> we can see that this
would change the shape of the curve.  Because the direction from point0 to
point1 is now downwards the spline would move down at the start rather than
up.  Because we haven't changed point3 the spline would still have to move
down as it reached the end (point2).  To do this it would have to move up
somewhere in the middle, so that it is above point2.  This is exactly what
it does!

So, we can see how the directions from point0 to point1 and from point2 to
point3 are used to set the curvature of the spline.  In addition, the
size of these distances will also alter the shape of the spline, eg. if we
had #declared point0 = <-5, -10, -5> and #declared point3 = <5, -10, 5> the
curve would arch upwards much higher in the middle, because the lengths of
the lines from point0 to point1 and point2 to point3 are much greater.

If we had #declared point0 = <-5, -1, -5> and #declared point3 = <5, -1, 5> 
the curve wouldn't arch upwards very much at all, because the lengths of
the lines from point0 to point1 and point2 to point3 are quite small
compared to the distance between point1 and point2.


3.1  CREATING MULTIPLE SEGMENTS IN A SPLINE FILE
**************************************************************************
The example spline above consists of only one segment, the shape of which
is determined by four points.  You can, however, create splines with as
many segments as you want, each segment being a different curve.  The
spline generator will join up all the curves to create one long spline.

To create a multiple segment spline file, you must specify the number of
segments in the spline.  Then you create the first segment exactly as
above.  Finally, for each segment after the first you must specify the next
point to move to, and the point to determine the curvature of the spline
as it reaches this next point.  You do this by redeclaring point2 and 
point3, and including the spline generator file again, eg. for a three 
segment curve:

   #declare spline_segments = 3

   #declare point0 = <-15, -3, 5> #declare point1 = <-15,  0, 5>
   #declare point2 = < -5,  0, 0> #declare point3 = < -5, -3, 0>
   #include "Spline.inc"

   #declare point2 = <5, 0, 0> #declare point3 = <5, 3, 0>
   #include "Spline.inc"

   #declare point2 = <15, 0, 0> #declare point3 = <15, -3, 0>
   #include "Spline.inc"

This will create a smooth spline that goes from point1 <-15, 0, 5> to
point2 <-5, 0, 0>, to the next point2 <5, 0, 0>, to the next point2
<15, 0, 0>.  The other points are used to curve the spline is a smooth 'M'
shape.  After the first segment you don't have to worry about point0 and
point1, because the spline generator will automatically join the last
point of the previous segment to the next point2 specified.

The one thing to make sure of is that you #include "Spline.inc" after each 
segment (the number of times this line appears in the spline file should 
always be equal to spline_segments).


3.2  CREATING A LOOPING SPLINE
**************************************************************************
If you wish to create a looping spline (eg. for a continuously looping
animation) you simply add the following line to the spline file:

   #declare spline_loop = true

The spline generator will then join the last point of the spline to the
first point with a smooth curve segment, creating a spline that moves in
an unbroken loop (see "Smooth.spl" for an example of this).


3.3  CREATING STRAIGHT LINE SEGMENTS
**************************************************************************
Normally you use point0 and point3 to curve the spline in different ways,
depending on the shape you want the spline to have.  If, however, you want
parts of the spline to be completely straight, just set point0 to be the
same as point1 (if you want a straight line at the beginning of the
spline), and set point3 to the same as point2 (if you want a straight line
anywhere else in the spline).  The following would create a spline made up
of straight line segments:

   #declare spline_segments = 2

   #declare point0 = < 0,  0,   0> #declare point1 = <0,   0,   0>
   #declare point2 = <10, 10, -10> #declare point3 = <10, 10, -10>
   #include "Spline.inc"

   #declare point2 = <15, -10, 10> #declare point3 = <15, -10, 10>
   #include "Spline.inc"


3.4  CREATING SHARP CORNERS
**************************************************************************
By default the spline generator will create a smooth-cornered spline (ie.
the join between each segment is completely smooth).  If you want to
create a spline with sharp corners where two segments join up you must
not only redeclare point2 and point3, but point0 as well (you should never
have to redeclare point1, as this would create a spline with gaps between
segments).

Because point0 is used to determine the direction at the start of the
spline segment, altering this for a segment after the first segment will
result in sharp corners (normally the generator uses the same direction as
at the end of the previous segment).  The following would create a spline
that passes through the same points as the example spline in section 3.1,
but because point0 has been redeclared for each segment it will create a
spline with three arches and sharp corners, rather than a smooth 'M' shape.

   #declare spline_segments = 3

   #declare point0 = <-15, -3, 5> #declare point1 = <-15,  0, 5>
   #declare point2 = < -5,  0, 0> #declare point3 = < -5, -3, 0>
   #include "Spline.inc"

   #declare point0 = <-5, -3, 0>
   #declare point2 = < 5,  0, 0> #declare point3 = <5, -3, 0>
   #include "Spline.inc"

   #declare point0 = < 5, -3, 0>
   #declare point2 = <15,  0, 0> #declare point3 = <15, -3, 0>
   #include "Spline.inc"

See "UnSmooth.spl" for an example of a spline file with sharp corners.


3.5  USING SPLINER.INC
**************************************************************************
When you use Spline.inc to create your spline file the vector you specify
for each point (including curve control points) indicates the absolute
position of that point relative to the origin, eg. specifying point0 =
<-5, -3, -5> and point1 = <-5, 0, -5> will create a spline that starts
in a direction parallel to the y axis because that is the direction
between the two points.

If you prefer, however, you can use the "SplineR.inc" file to create
spline files for which you can specify relative curve control points
rather than absolute control points.  The following two code examples
would result in exactly the same spline:

   #declare point0 = <-5, -3, -5> #declare point1 = <-5,  0, -5>
   #declare point2 = < 5,  0,  5> #declare point3 = < 5, -3   5>
   #include "Spline.inc"

is the same as:

   #declare point0 = <0, -3, 0> #declare point1 = <-5,  0, -5>
   #declare point2 = <5,  0, 5> #declare point3 = < 0, -3   0>
   #include "SplineR.inc"

The only difference is that point0 and point3 have been specified relative
to point1 and point2 (respectively).  This allows you to change point1 and
point2 without having to worry about maintaining the same directions for
the curve control lines.  Note that Spline.inc and SplineR.inc should not
be used in the same multi-segment spline file or you will get unexpected
results (see "UnSmooth.spl" for an example of a spline file that uses 
SplineR.inc).


4.0  USING SPLINE FILES IN POVRAY SCENE FILES
**************************************************************************
After you have created your spline file with the necessary control points
and spline options, you are ready to use the spline in your POVRay scene
files.

4.1  PREVIEWING A SPLINE
**************************************************************************
You can create a simple rendered image of your spline using the
"ShowSpl.inc" file.  Just create a scene file with the following code:

   #declare spline_file = "MySpline.spl"
   #include "ShowSpl.inc"

Then add a suitable camera to specify where you want to view your spline
from, and when you render the scene file you will get an image that plots
the shape of the spline.  This is useful when setting up a spline file
and trying to determine the correct points to use (see "SP_Samp1.pov" and
"SP_Samp2.pov"), and it is especially helpful when creating a spline to
position a camera, as you can add the above two lines of code to your scene
and check that the camera does not pass through any solid objects, etc.
(see "PFlyAnim.pov" for an example of this technique).

In addition to the spline_file variable you can declare the following
BEFORE including "ShowSpl.inc":

1.  spline_smoothness
   This determines the number of points of the spline plotted, eg:
      #declare spline_smoothness = 200
   will result in a much smoother spline, although it will take longer to
   parse and render.

2.  spline_object
   By default the spline is plotted using unit-sized spheres, bright white
   spheres.  You can change this object definition to plot the spline with
   a differently shaped or coloured object, eg:

      #declare spline_object = box {<-1, -1, -1>, <1, 1, 1>
         texture {Box_Texture}}

   Note that the object should generally be centred around the origin, or
   the spline preview will be in the wrong position.


4.2  USING A SPLINE FOR ANIMATION
**************************************************************************
To use a spline file to position an object, camera, light_source, etc. you
must first specify the "spline_clock" variable.  This determines how far
along the spline you wish to move, and should generally range from 0 (the
start of the spline) to 1 (the end of the spline).  If you specify a value
outside this range the spline generator will automatically loop back to
the beginning of the spline (if you use a number over 1) or to the end (if
you specify a number less than 0), eg:

   #declare spline_clock = 1.5

would be the same as #declare spline_clock = .5, and would give the spline 
position halfway along the spline.

In animations you will generally want the spline_clock to be equal to
POVRay's internal clock variable, and if this is the case you can simply
not specify any spline_clock at all and the spline generator will auto-
matically use the clock variable in its place.

If you want to loop through the spline more than once you should specify
spline_clock to be a multiple of the clock variable, eg:

   #declare spline_clock = clock * 5

This will loop through the spline 5 times.  Also, You can 'phase shift'
the spline by adding an amount to the clock, eg:

   #declare spline_clock = clock + .5

This is useful when you want the spline to start somewhere other than the
beginning, or if you want to use one spline for both the location and
look_at variables of a camera ,eg:

   camera {
      #declare spline_clock = clock #include "CamPath.spl"
         location spline_pos
      #declare spline_clock = clock + .1 #include "CamPath.spl"
         look_at spline_pos}

This will cause the camera to look slightly ahead of itself along the
spline, while still changing direction with the spline (see "FlyAnim.pov").

After you have declared your spline_clock you must then include the spline
file you wish to use, as shown in the camera statement above.  The spline
generator will then calculate the "spline_pos" variable which will contain
the vector location of the spline at the distance along the spline
specified by the spline_clock variable.  You can then use this vector
anywhere that vectors are accepted (eg. translations, rotations, colors) or
you can use the individual components of the vector as float values (eg.
spline_pos.x will return the x-coordinate of the spline position, see
"BallAnim.fli" for an example).

Note that you can modify the spline_pos variable to translate or scale the
entire spline without having to edit the spline file, eg:

   object {MyObject translate spline_pos * 1.5 + <4, -5, -10>}

This will scale the spline path by 1.5 and translate it by <4, -5, -10>
without affecting the size of the object being translated.


4.3  CREATING SPLINE BASED OBJECTS
**************************************************************************
In addition to using splines for moving objects along paths in animations
you can use them to create static objects.  Basically you set up a scene
file like this:

   #declare spline_clock = 0 #while (spline_clock <= 1)
      #include "MySpline.spl"
      object {MyObject translate spline_clock}
   #declare spline_clock = spline_clock + (1 / 40) #end

For a more complicated scene file that uses this method see the
"Tentacle.pov" example file.  You could use a similar method to create
objects such as ropes, neon lettering, railways, roller coasters, and a
variety of organic shapes.

In fact, you could even create an animated spline object by creating
individual spline files to specify the control points of another spline
file, and use this to create a moving object!


5.0  CONTACTING THE AUTHOR
**************************************************************************
If you wish to contact me with bug reports, bug fixes, criticisms, 
comments, suggested improvements, questions, etc. you can reach me by 
email at:

   ccolefax@geocities.com

or by regular mail at:

   Chris Colefax
   P.O. Box 110
   Kuranda, Queensland
   Australia  4872

**************************************************************************

POV-Ray(tm) and Persistence of Vision(tm) are registered trademarks of the
POV-Ray Team(tm)
