KF.jar
====

KF stands for KeyFramer, and is to be used to generate POV-Ray files on a Key Frame animation basis.

Key Frame animation works by you the animator generating a start point and an end point for the animation, the KF application then fills in the blanks spaces in between.

For instance, you might have a scene where an elbow join starts with a Z rotation value of 0 and ends with Z rotation value of 25.  You can use KF to generate all of the POV-Ray files in between for an animation.

Example files are included with this file.

"KF.jar" is the Java program.
"Script.kfs" is the script for the animation.
"test.pov" is a sample scene file.

If you run the example, it will explain more than could possibly be put into words.  So here is how to run the sample on Windows ( the author does not know any other OS ).  In the following example do not type any of the quotes!

1. Create a folder called "KeyFrame".
2. Copy "KF.jar","test.pov" and "Script.kfs" into the "KeyFrame" folder.
3. Click "Start" then "Run", enter "cmd" into the box that appears and finally click "OK".  
4. Type "cd..", and press enter.  Keep doing this until the prompt says "c:\>"
5. Type "cd" followed by a space and then the path to the folder you created in step 1, e.g. "cd c:\KeyFrame", and press enter.
6. Type "KF.jar" followed by a space and the path to the folder you created in step 1.  You should have something like  "KF.jar c:\KeyFrame".  Press Enter.
7. 65 POV-ray files are created each slightly differn't, if you then render all of these you will see the animation ( somewhat uninspiring ).

What is rendered by the example is a moving sphere. Lets see how that was done.  Open the "test.pov" file and see whats in there.

A few includes, a camera, lightsource and the sphere.  Did you notice the following extract...

#############
                rotate <0,TextSpin,0>                                                                
                }
	translate <Xpos,Ypos,Zpos>
#############

... TextSpin, Xpos,Ypos and Zpos are not defined in the file!  These are animation points defined in the script file.  When generating all of the POV-ray files the program substitutes these with appropriate values.

Open the Script file ( with Notepad ), and I'll explain each part of it.

All of the lines that begin with an uppercase word are interpreted by the KF program and all others are ignored.

The only valid key words are "SOURCE", "FILENUMBER", "FRAMES", "ANIMATIONPOINT".  The program IS case sensitive.

SOURCE
=====
This is the name of the POV-Ray file that is going to be scanned as the template for generating all of the files for the animation.  

FILENUMBER
========
This number is used as the starting point for naming each of the generated POV-Ray files.

FRAMES
=====
The number of frames (POV-Ray files) to be generated.

ANIMATIONPOINT
===========
This is the meat of the script file.  Lets look at the example file supplied.

ANIMATIONPOINT:Ypos:1:20:10:-10

The above line tells the program to look for a piece of text in the SOURCE file that matches "Ypos".  The next two numbers indicate a span of frames, in this example, 1 through 20.  The final two numbers specify a range of values to replace "Ypos" with.  So in frame 1 ( the first ) the text "Ypos" will be replaced with "10".  In each subsequent frame the value will be altered slightly until in frame 20 "Ypos" will be replaced by "-10".

In the example file the FRAMES value is set to 65, so once the frame number reaches 21 all subsequent values for "Ypos" will remain at "-10".

Heres a more complex example.

ANIMATIONPOINT:Xpos:1:30:-10:5:31:60:5:28

The program will replace all occurances of "Xpos" with a value.  Note that here we have 8 numbers instead of 4 as in the previous example.

For frames 1 through to 30 the value of "Xpos" will slide from "-10" to "5", then for frames 31 to 60 the value of "Xpos" will slide from "5" to "28".

So this ANIMATIONPOINT has two ranges of values.  You can add as many ranges of values as you wish to an ANIMATIONPOINT by adding groups of four numbers to the script line.

Another example.

ANIMATIONPOINT:Zpos:1:65:0:-7

You can probaly guess that this example aplies to frames 1 through 65 and the value of "Zpos" moves from "0" in frame 1 to "-7" in frame 65.

Another example.

ANIMATIONPOINT:TextSpin:30:65:0:180

This example differs because it only applies to frames 30 through 65.  So the each occurance of "TextSpin" in frames 1 to 29 will be replaced with a value of 0.  Then from frames 30 to 65 "TextSpin" will slide through values "0" to "180".


It is possible to generate an entire Walk Cycle by creating ANIMATIONPOINT's from Hips, Knees and ankles.



This is version 1 of the application.  Its biggest limitation is that it is simply straight line key framing.  This due to the limited mathamatical knowledge of the author.  I'd like to add a weighting scheme to the ANIMATIONPOINT's so that I could specify a range of values and slide the value down a curve rather than the straight line it is now.  For instance if I was animating an Elbow move, I want the amount of movement to slow towards the end of the movement, this would make it more natural.  If you know how to do that please contact me at the address below!

If you have any questions about this stuff then you can try contacting me at "codesabeach@hotmail.co.uk".









