Category : Printer + Display Graphics
Archive   : CPATH11A.ZIP
Filename : CAMPATH.DOC

+-------------------------------------------------------+
| John Hammerton CamPATH 1.1a Dec 18, 1991 |
+-------------------------------------------------------+

------- CPATH11a.ZIP contains: -------
campath.exe - Version 1.1a executable
campath.doc - This document (same as v1.0)
newstuff.txt - Additions since v1.0

1. Description

A. What it does:

CamPATH is a tool for the PoV Raytracer that helps to create animations.
What it actually generates is a user defined path for the camera to follow
from frame to frame, giving the effect of 'flying' around your scene. It
does this by creating a batch file that runs PoV once for each frame of
animation and alters your camera's LOCATION statement each time. With
version 1.0, you can chose from camera paths like a simple circle or
ellipse, or the more complex lemniscate or limacon. You will be asked for
shape, size and location of the camera path and the number of frames of
animation that you desire. CamPATH will give you an instant preview of
the path, showing the location of the camera for each frame as a point
on a grid so you can visualize how to build your scene, or how to make
the path fit into a scene that you've already done. (More on this later)

B. What it doesn't:

CamPATH does not create data files and does not attempt to show a
'preview' of what the animation will look like from the camera's
point of view. It does not require that you even HAVE a scene yet -
it ONLY creates a batch file to render a series of frames where the
camera moves in a smooth, user-defined path. This program does NOT convert
the resulting Targa files into animation format, nor attempt to play the
animation. Use your favorite post-processing Targa Animator and Player
for this purpose. I suggest Dave's Targa Animator (DTA) by David K. Mason
and Trilobyte's VGA/SVGA .FLI player (PLAY.EXE), both available on YCCMR.

C. What you need:

Since the program doesn't write PoV script, it will work for any version
of PoV or DKB. It requires basic 640x480x16 VGA (mode 12) and doesn't do
anything tricky with interrupts or registers, so it should work with any
version of DOS and machine.

2. Operation

There are no command line options. Simply execute the file and you
are presented with a grid with the axes labeled and the commands below.
will exit to DOS. "5" will give you a two page summary of what
CamPATH does and how to do it. Numbers "1" through "4" create the
corresponding path using your input on size, shape and offset from center.
The default for each question is colored, which will be used if you
press the Enter key, shown in [brackets]. The defaults are usually the
most simple path that can be created from the selected shape. (I don't
recommend saving these default paths directly - they have no OFFSET.)

You will immediately notice that the grid is labeled as X and Z. This
is because the "standard" for PoV is that the Y-axis is the UP direction.
(your .dat file contains the command UP <0 1 0>) The camera will move
through the scene HORIZONTALLY. This means the path's height is FIXED
and is determined by you, while the camera's X and Z position will
constantly change throughout the animation. This way, your camera will fly
through the scene parallel to the floor - a very easy thing to visualize.
(Pretend you're looking down at your scene; the grid is on the FLOOR.)
Each grid line is 50 units apart, with the edges of the VGA screen at
-300 to 300 for the X-direction and -200 to 200 for the Z-direction.
Your paths can be as big as you want, but this first version of CamPATH
will only show the points that fall inside the screen limits. This will
be changed for v2.0, but for now it's good enough for scenes with "small"
dimensions. (Spheres scaled to 10's and 20's and NOT 100's and 200's)

Each point on the screen represents ONE frame of animation. If you
choose 100 frames, then there will be 100 little points on the screen
to draw out the shape of the path. This gives you a feel of how SMOOTH
the animation will be. You can quesstimate the distance between frames
(using the grid for reference) and choose a 'good' number of frames
accordingly. Also notice that on all shapes besides the circle, the
points are not EVENLY spaced about the path - but rather, they bunch-up
around the tight curves and are spaced-out in the long stretches. This
is a feature of the SINE's and COSINE's used to create the paths - and
makes for VERY nice animations that actually accelerate and decelerate
as they twist, turn and loop around! The effect is most nifty.

When you're satisfied with a path that you've created, simply answer
'YES' to SAVE this path. The screen will clear and you will be asked a
series of tough questions that the program MUST know before it can
create it's batch file. If you become confused or simply forget the
answers, sensible defaults are provided at no additional cost.
The interrogation looks like this:

"Name for the batch file (anim.bat)"
This is the name for the file that CamPATH is about to create.
This is the file you will execute to begin rendering all the frames.

"Name for the include file (campath.inc)"
This is the file that will contain the DECLAREd variables that move
the camera's position for each frame. (INCLUDE "campath.inc")
(or #include "campath.inc" for PV-Ray)

"Name of the datafile to animate (test.dat)"
Enter the name of the datafile to animate if you have one or
pick the name you will call it once you have one. It won't check
either way - it just needs to tell the raytracer what it is.


"Name of the definition file (trace.def)"
PoV uses a file called trace.def to store it's command line defaults
like resolution and image quality. You may want to create a "test.def"
or an "anim.def" that contains the specific options for THIS animation.
(pvray.def is the default definition file for PoV-Ray)

"Name of your executable file (pvray.exe)"
Enter the name you use to do a trace. (filename AND extension, please)
(this can be pvpro.exe or pvw386.exe or WHATEVER)

"Up to 4 letters for the TGA output files (anim)"
Each frame will be in Targa format, numbered 0001, 0002, etc...
So the default is anim0001.tga, anim0002.tga, etc.
(just enter between 1 and 4 letters at the prompt)

You can then Create the batch file, Re-enter all these inputs,
or abort this SAVE completely. Choosing CREATE will blank the screen,
show the grid and axes, and write the file to the current directory while
charting it's progress on-screen. When it's done - CamPATH will present
you with a summary of what you've created and a reminder of how to get
the animation going. It will explain how to place the camera's
XPOS and ZPOS variables into your datafile's LOCATION command, how to
INCLUDE the .inc file into your datafile, and how to begin rendering
all the frames automatically. It will do this using the filenames that
you supplied, so you know exactaly what to do and where to do it.

3. Starting Suggestions

If you hate reading and want to play with the thing - go to it!
For starters just draw some nice simple paths and offset them so
they rotate around or pass by (0,0) but not THROUGH (0,0). Generally
note where the path lies (use the grid), give it about 90 frames,
and save it. Then go write a datafile that contains...

INCLUDE "campath.inc" {or whatever you told it your .inc would be}

VIEW_POINT
LOCATION < XPOS 70 ZPOS > {The 70 is the FIXED HEIGHT of the path}

UP < 0 1 0 > {The Y-axis is the UP direction}
RIGHT < 1.33333 0 0 > {Whatever you usually use here}
LOOK_AT < 0 20 0 > {Look at X=0,Z=0 like you did when you
END_VIEW_POINT made the path, and look at a height of 20}

...then just put some simple objects around <0 20 0>, perhaps a nice
green and yellow checkered floor like PLANE <0 1 0> 0 END_PLANE,
and a LIGHT_SOURCE and you're done. Make sure your definition file
(trace.def) is at -w80 -h50 (or something small) and type the name
of the batch file. The batch file will AGAIN remind you of what you
need to have done and where to do it. Pressing return will start the
process of rendering all the frames, automatically. When it's done,
compile the targas into an animation file and take a look with a player.
If you put objects too close to the camera's path, then some frames
may be obscured or trashed. This is why you want to offset the path from
(0,0) and make that the scene's center. If the majority of your scene
was junk, then your objects are too darn big for the path or the
camera's height (70) just wasn't enough. You can experiment with the
different paths - personally, I think the SINGLE LIMACON with 2 loops
is a wild ride, (this is what I used in my TABLE-CP.ZIP sample animation)
and you can LOOK_AT anything you want. You could even remove the LOOK_AT
command and put a DIRECTION <0 0 1> in the datafile, and then your camera
would always look straight down the +Z axis while it moves around the
scene. But now we're getting into...

4. In-Depth Suggestions

I've not done a WHOLE LOT of testing yet. I've not even mastered
a good lemniscate orbit scene with a lot of objects. However, I have
learned what works and what doesn't and not all of it so obvious.

A. If the camera path ever passes directly over it's LOOK_AT (say, at 0,0)
that frame will be garbage. The technical reason is that you're
tipping the camera over, face first, past it's vertical - and when it
gets past that point it has to snap around to conform to the UP<0 1 0>
vector. Any path that even gets NEAR passing right above it's LOOK_AT
will give this very undesirable effect. You can easily avoid this by:
1. offset the path when you create it and LOOK_AT (0,0) or
2. leave the path with no offset and LOOK_AT some far away point.

B. If the camera gets very close to an object, the object will come out
distorted in that frame and may not look right. If the camera goes
INTO a solid object, those frames will be garbage. You can avoid these
two VERY COMMON problems by imagining your scene when drawing the
path and making it big enough. (or offset far enough away from things)
I usually use the middle square of the grid as my object boundary - it's
a 100x100 square and if your path is way the heck away from it
and your object(s) are inside, then you're fine. The single, 1 loop
limacon is great if you make it big (say, 300x300) and LOOK_AT the
center of the inner loop and place some objects there.

C. The green and yellow checkered floor will be your best friend
once again for a while. It makes an EXCELLENT reference for the
animation because it shows movement so well. Then put a nice Cube on
top of that to LOOK_AT from your fixed height. This simple scene
traces lightning fast at 80x50 and is a really good starting point for
'feeling' what a path is like before getting complex.

D. ALWAYS make sure that XPOS and ZPOS are in the LOCATION command before
you run the batch file. I've mentioned this so often because if you
forget, there will be no VARIABLES in the datafile, so PoV will
trace the same darn frame (fixed camera LOCATION) over and over.

E. Give your LIGHT_SOURCES an ALPHA 1.0 in the COLOR definition.
You'd be surprised at how often you SEE one of your little white
lightsources go cruising by in the background.

F. Making paths with more than 5 or 6 loops is not very practical
(especially for both kinds of limacons) because for each loop you
need that many more frames to keep the animation SMOOTH. For instance,
do a circle path at 200x200 then a single, 2 loop limacon at 200x200 -
both at 120 frames. Notice how the circle's points are very closely
spaced and the limacon gets very spread-out. You'd need about 180
frames for the limacon to become as SMOOTH as the circle.
(oh, but THAT limacon path is definitely worth the extra frames!)

G. The lemniscates aren't all that useful yet. Since all the petals
pass over one point, it becomes tough to create a good scene that
avoids all those crossings. CamPATH v2.0 may allow you to make
lemniscates that have an inner 'hole' of any radius so you can
do fly-by's of an object from all those different directions.
BUG: The 6-petaled rose does not work. It actually does 3 petals,
then goes over the same 3 instead of "filling-in" the gaps. Sorry.

H. Feel free to substitute XPOS and ZPOS into objects or lightsources
instead of the camera. You can get some funky things happening
that way. With any luck, the next version will probably have this
as an option BEFORE you create the batch file. *** Actaully, as of
v1.1a you can do this with the independent variables instead...
see the NEWSTUFF.TXT file for more info. ***

* I. DO NOT use the DIRECTION command in your VIEW_POINT statement if you
are already using a LOOK_AT. This will only confuse the raytracer;
since you're doing a total rotation (or two or three) - you end up
looking in ALL directions, eventually corrupting the vectors.

5. Questions, Comments, Fortune Telling...

If you try and try and can't seem to get anything great - please send
me a message and I'll put some test scenes w/batch's on the board.

I am still at work on v2.0, so if you have an idea for a new path or
a suggestion on how to fix something you hate about this version -
please let me know. If you want to fool with the v1.0 QuickBASIC code -
go right ahead. Be warned, it's simple but not very tidy.

ACHTUNG! This first version IS A TOY! It took maybe two days to write
the code and about two weeks to tweak and test. I just wanted to throw my
ideas onto other YCCMR folks for input as quickly as possible. I already
know what v2.0 will look like. v1.0 has no interface, no help and no nice
way to gradually alter the shape and size of a path. And you're stuck with
only XZ movement, with a fixed height. Version 2.0 will definitely be
somewhat 3-dimensional and I expect that if I keep at it, it may be fully 3D
- meaning that a lissajous camera path is very possible! (but who knows
what THAT sucker will look like to preview, or how to make it non-cyclic?)

6. Disclaimer:

I've done nothing unusual in my code and I've given you a copy
(campath.bas) so you can verify this. The program does not use any
interrupts or bios calls or strange video page swapping. It opens and
writes a single batch file and has no delete function. It could have
been written by a 10 year-old in a couple of hours. OKAY, but I still have
to say it. I cannot be held liable for any damage that may result from the
use or misuse of this program. There. I feel better. You probably don't.