                Persistence of Vision Ray Tracer (POV-Ray)

                                Version 2.0

                           User's Documentation
                            

                        Copyright 1993 POV-Ray Team   



2.0   ABOUT POV-Ray
===================

This section describes POV-Ray and explains what a ray tracer does.  It 
also describes where to find the latest version of the POV-Ray software.


2.1   PROGRAM DESCRIPTION -- WHAT IS RAY TRACING?
------------------------------------------------

The Persistence of Vision Ray Tracer (POV-Ray) is a copyrighted freeware 
program that allows a user to easily create fantastic, three dimensional, 
photo-realistic images on just about any computer. POV-Ray reads standard 
ASCII text files that describe the shapes, colors, textures and lighting in 
a scene and mathematically simulates the rays of light moving through the 
scene to produce a photo-realistic image! 

No traditional artistic or programming skills are required to use POV-Ray. 
First, you describe a picture in POV-Ray's scene description language, then 
POV-Ray takes your description and automatically creates an image from it 
with near perfect shading, perspective, reflections and lighting. 

The standard POV-Ray package also includes a collection of sample scene 
files that illustrate the program's features.  Additionally the POV-Ray 
Team distributes several volumes of scenes that have been created by other 
artists using the program. These scenes can be rendered and enjoyed even 
before learning the scene description language. They can also be modified 
to create new scenes. 

3.0   QUICK START
=================

The next section describes how to quickly install POV-Ray and render a 
sample scene on your computer. 


3.1   INSTALLING POV-Ray
------------------------

Specific installation instructions are included with the executable program 
for your computer. In general, there are two ways to install POV-Ray. 

1-- The messy way: Create a directory called POVRAY and copy all POV-Ray 
files into it. Edit and run all files and programs from this directory. 
This method works, but is not recommended.

Or the preferred way:
2-- Create a directory called POVRAY and several subdirectories called  
INCLUDE, DEMO, SCENES, UTIL. The self-extracting archives used in some 
versions of the program will create subdirectories for you.  If you create 
your own, the file tree for this should look something like this:
    \--
      |   
      +POVRAY --
               |
               +INCLUDE
               |
               +DEMO
               |  
               +SCENES
               |  
               +UTIL   

Copy the executable file and docs into the directory POVRAY. Copy the 
standard include files into the subdirectory INCLUDE. Copy the sample scene 
files into the subdirectory SCENES. And copy any POV-Ray related utility 
programs and their related files into the subdirectory UTIL. Your own scene 
files will go into the SCENES subdirectory. Also, you'll need to add the 
directories \POVRAY and \POVRAY\UTIL to your "search path" so the 
executable programs can be run from any directory.

      *Note that some operating systems don't 
      *have an equivalent to the
      *multi-path search command.

The second method is a bit more difficult to set-up, but is preferred. 
There are many files associated with POV-Ray and they are far easier to 
deal with when separated into several directories.


3.2   USING SAMPLE SCENES
-------------------------

A scene file is a standard ASCII text file that contains a description of a 
three dimensional scene in the POV-Ray language.  The scene file text 
describes objects and lights in the scene, and a camera to view the scene. 
Scene files have the file extension .POV and can be created by any word 
processor or editor that can save in standard ASCII text format.

Here's how to make these sample scenes into images you can view on your 
computer. We'll use SIMPLE.POV as an example, just substitute another 
filename to render a different image.

The file SIMPLE.POV was included with the standard scene files and should 
now be in the DEMO directory.  Make that the active directory, and then at 
the command line, type:

  POVRAY +Isimple.pov +V +W80 +H60

POVRAY is the name of your executable, +Ifilename.pov tells POV-Ray what 
scene file it should use as input, and +V tells the program to output its 
status to the text screen as it's working. +W and +H set the width and 
height of the image in pixels. This image will be 80 pixels wide by 60 
pixels high.

POV-Ray will read in the text file SIMPLE.POV and begin working to render 
the image. It will write the image to a file called DATA.TGA. The file 
DATA.TGA contains a 24 bit image of the scene file SIMPLE.POV. Because many 
computers can't display a 24 bit image, you will probably have to convert 
DATA.TGA to an 8 bit format before you can view it on your computer. The 
docs included with your executable lists the specific steps required to 
convert a 24 bit file to an 8 bit file.


3.3.8 INPUT AND OUTPUT FILE NAMES

      +Ifilename  Set the input filename
      +Ofilename  Set output filename

The default input filename is "object.pov". The default output filename is 
"data" and the suffix for your default file type.  The +O switch has no 
effect unless file output is turned on with +F


3.3.10 ANIMATION CLOCK VARIABLE

      +Knnn or -Knnn    Set the "clock" float value

The +K switch may be used to pass a single float value to the program for 
basic animation.  The value is stored in the float identifier "clock".  If 
an object had a "rotate <0,clock,0>" attached then you could rotate the 
object by different amounts over different frames by setting +K10, +K20... 
etc. on successive renderings.


3.3.16 QUALITY SETTINGS

      +Qn or -Qn  Set rendering quality

The +Q option allows you to specify the image rendering quality, for 
quickly rendering images for testing. You may also use -Q with no 
difference.  The parameter can range from 0 to 9. The values correspond to 
the following quality levels:

0,1  Just show quick colors. Ambient lighting only.
     Quick colors are used only at 5 or below.
2,3  Show Diffuse and Ambient light
4,5  Render shadows, use extended lights at 5 but not 4
6,7  Create surface textures
8,9  Compute reflected, refracted, and transmitted rays.

The default is +Q9 (maximum quality) if not specified.


3.3.17 VERBOSE STATISTICS

      +V          Verbose statistics on
      -V          Verbose statistics off

When the +D option is not used, it is often desirable to monitor progress 
of the rendering.  The +V switch turns on verbose reporting while -V turns 
it off.  The format of the output is system dependent.


3.4   DEFAULT PARAMETER FILE AND ENVIRONMENT VARIABLE
-----------------------------------------------------

You may specify the default parameters by modifying the file "povray.def" 
which contains the parameters in the above format. This filename contains a 
complete command line as though you had typed it in, and is processed 
before any options supplied on the command line are recognized. You may put 
commands on more than one line in the "povray.def" file.

Examples:

  POVRAY +Ibox.pov +Obox.tga +V +X +W320 +H200 

     +Ibox.pov = Use the scene file box.pov for input
     +Obox.tga = Output the image as a Targa file to box.tga 
     +V = Show line numbers while rendering.
     +X = Allow key press to abort render.
     +W320 = Set image width to 320 pixels
     +H200 = Set image height to 200 pixels

Some of these parameters could have been put in the POVRAYOPT environment 
variable to save typing:

  SET POVRAYOPT = +V +X +W320 +H200

Then you could just type:

  POVRAY +Ibox.pov +Obox.tga 

Or, you could create a file called POVRAY.DEF in the same directory as the 
scene file.  If POVRAY.DEF contains "+V +X +W320 +H200" then you could also 
type:

  POVRAY +Ibox.pov +Obox.tga 

With the same results. You could also create an option file with a 
different name and specify it on the command line:

For example, if QUICK.DEF contains "+V +X +W80 +H60" then you could also 
type:

  POVRAY +Ibox.pov +Obox.tga QUICK.DEF

When POV-Ray sees QUICK.DEF, it will read it in just as if you typed it on 
the command line.

The order that the options are read in for the IBM-PC version are as 
follows:

  POVRAYOPT environment variable

  POVRAY.DEF in current directory or,
             if not found, in library path

  Command line and command line option files

For example, +V in POVRAY.DEF would override -V in POVRAYOPT. +X on the 
command line would override -X in POVRAY.DEF and so on.

Other computer's versions may read in the POVRAY.DEF file before the 
POVRAYOPT environment variable.  See the documentation on your version.


4.0   BEGINNING TUTORIAL
========================

This section describes how to create a scene using POV-Ray's scene 
description language and how to render this scene.


4.1   YOUR FIRST IMAGE
----------------------

Let's create the scene file for a simple picture. Since ray tracers thrive 
on spheres, that's what we'll render first.


4.1.1 THE POV-Ray COORDINATE SYSTEM

First, we have to tell POV-Ray where our camera is and where it's looking. 
To do this, we use 3D coordinates. The usual coordinate system for POV-Ray 
has the positive Y axis pointing up, the positive X axis pointing to the 
right, and the positive Z axis pointing into the screen as follows:

    ^+Y
    |   /+Z
    |  /
    | /
    |/        +X
    |-------->


The negative values of the axes point the other direction, as follows:


          ^+Y
          |   /+Z
          |  /
          | /
  -X      |/        +X
  <-------|-------->
         /|
        / |
       /  |
    -Z/   |
          v-Y


4.1.2 ADDING STANDARD INCLUDE FILES

Using your personal favorite text editor, create a file called 
"picture1.pov". Now, type in the following (note: The input is case 
sensitive, so be sure to get capital and lowercase letters correct):

      #include "colors.inc"    // The include files contain
      #include "shapes.inc"    // pre-defined scene elements
      #include "textures.inc"

      camera {
        location  <0, 2, -3>
        look_at   <0, 1,  2>
      }

The first include statement reads in definitions for various useful colors. 
The second and third include statements read in some useful shapes and 
textures respectively. When you get a chance, have a look through them to 
see but a few of the many possible shapes and textures available.

You may have as many include files as needed in a scene file. Include files 
may themselves contain include files, but you are limited to declaring 
includes nested only 10 "deep".

Filenames specified in the include statements will be searched for in the 
home (current) directory first, and if not found, will then be searched for 
in directories specified by any "+L" (library path) options active. This 
would facilitate keeping all your "include" (.inc) files such as 
shapes.inc, colors.inc, and textures.inc in an "include" subdirectory, and 
giving an "+L" option on the command line to where your library of include 
files are.


4.1.3 PLACING THE CAMERA

The camera declaration describes where and how the camera sees the scene. 
It gives X, Y, Z coordinates to indicate the position of the camera and 
what part of the scene it is pointing at. You describe X, Y, Z coordinates 
using a 3-part "vector".  A vector is specified by putting 3 numeric values 
between a pair of angle brackets and separating the values with commas.

Briefly, "location <0, 2, -3>" places the camera up two units and back 
three units from the center of the ray tracing universe which is at <0, 0, 
0>. Remember that by default +Z is into the screen and -Z is back out of 
the screen.

Also "look_at <0, 1, 2>" rotates the camera to point at X, Y, Z coordinates 
<0, 1, 2>.  A point 5 units in front of and 1 unit lower than the camera. 
The look_at point should be the center of attention of your image.


4.1.4 DESCRIBING AN OBJECT

Now that the camera is set up to record the scene, let's place a red sphere 
into the scene.  Type the following into your scene file:

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {color Yellow}  // Yellow is pre-defined in COLORS.INC
        }
      }

The first vector specifies center of the sphere.  In this example the X 
coordinate is zero so it is centered left and right.  It is also at Y=1 or 
1 unit up from the origin. The Z coordinate is 2 which is 5 units in front 
of the camera at Z=-3. After the center vector is a comma followed by the 
radius which in this case is 2 units. Since the radius is 1/2 the width of 
a sphere, the sphere is 4 units wide. 


4.1.5 ADDING TEXTURE TO AN OBJECT

Now that we've defined the location and size of the sphere, we need to 
describe the appearance of the surface.  The texture {...} block specifies 
these parameters.  Texture blocks describe the color, bumpiness and finish 
properties of an object.  In this example we will specify the color only.  
This is the minimum we must do.  All other texture options except color 
will use the default values.

The color you define is the way you want it to look if fully illuminated.  
If you were painting a picture of a sphere you would use dark shades of a 
color to indicate the shadowed side and bright shades on the illuminated 
side.  However ray tracing takes care of that for you.  You pick the basic 
color inherent in the object and POV-Ray brightens or darkens it depending 
on the lighting in the scene.  Because we are defining the basic color the 
object actually IS rather than how it LOOKS the parameter is called 
"pigment".

Many types of color patterns are available for use in a pigment {...} 
statement.  The keyword "color" specifies that the whole object is to be 
one solid color rather than some pattern of colors.  The word "Yellow" is a 
color identifier which was previously defined in the standard include file 
"colors.inc".

If no standard color is available for your needs, you may define your own 
color by using the color keyword followed by "red", "green" and "blue" 
keywords specifying the amount of red, green and blue to be mixed.  For 
example a nice shade of pink can be specified by:

      color red 1.0 green 0.8 blue 0.8

The values after each keyword should be in the range 0.0 to 1.0.  Any of 
the three components not specified will default to 0.  A shortcut notation 
may also be used.  The following produces the same shade of pink:

      color rgb <1.0, 0.8, 0.8>

Colors are explained in more detail later.


4.1.6 DEFINING A LIGHT SOURCE

One more detail is needed for our scene.  We need a light source. Until you 
create one, there is no light in this virtual world.  Add the following 
text to your scene file:

      light_source { <2, 4, -3> color White}

The vector specifies the location of the light as 2 units to our right, 4 
units above the origin and 3 units back from the origin. The light_source 
is invisible, it only casts light, so no texture is needed.

That's it!  Close the file and render a small picture of it using this 
command:

      POVRAY +W160 +H120 +P +X +D0 -V -Ipicture1.pov

If your computer does not use the command line, see the executable docs for 
the correct command to render a scene.

You may set any other command line options you like, also. The scene is 
output to the image file DATA.TGA (or some suffix other than TGA if your 
computer uses a different file format). You can convert DATA.TGA to a GIF 
image using the commands listed in the docs included with your executable. 


4.2   MORE TEXTURE OPTIONS
--------------------------

You've now rendered your first picture but it is somewhat boring.  Let's 
add some fancy features to the texture.


4.2.1 SURFACE FINISHES

One of the main features of a ray tracer is its ability to do interesting 
things with surface finishes such as highlights and reflection.  Let's add 
a nice little phong highlight (shiny spot) to the sphere. To do this you 
need a "finish" parameter. Change the definition of the sphere to this:

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {color Yellow}  // Yellow is pre-defined in COLORS.INC
          finish {phong 1}
        }
      }

Now render this the same way you did before. The phong keyword adds a 
highlight the same color of the light shining on the object. It adds a lot 
of credibility to the picture and makes the object look smooth and shiny. 
Lower values of phong will make the highlight less bright. Phong can be 
between 0 and 1.


4.2.2 ADDING BUMPINESS

The highlight you've added illustrates how much of our perception depends 
on the reflective properties of an object.  Ray tracing can exploit this by 
playing tricks on our perception to make us see complex details that aren't 
really there.

Suppose you wanted a very bumpy surface on the object.  It would be very 
difficult to mathematically model lots of bumps.  We can however simulate 
the way bumps look by altering the way light reflects off of the surface.  
Reflection calculations depend on a vector called a "surface normal" 
vector.  This is a vector which points away from the surface and is 
perpendicular to it.  By artificially modifying (or perturbing) this normal 
vector you can simulate bumps.  Change the scene to read as follows and 
render it:

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {color Yellow}  
          normal {bumps 0.4   scale 0.2}
          finish {phong 1}
        }
      }

This tells POV-Ray to use a bump pattern to modify the surface normal.  The 
value 0.4 controls the apparent depth of the bumps.  Usually the bumps are 
about 1 unit wide which doesn't work very well with a sphere of radius 2.  
The scale makes the bumps 1/5th as wide but does not affect their depth. 


4.2.3 CREATING COLOR PATTERNS

You can do more than assign a solid color to an object.  You can create 
complex patterns in the pigment block.  Consider this example:

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {
            wood
            color_map {
              [0.0 color DarkTan]
              [0.9 color DarkBrown]
              [1.0 color VeryDarkBrown]
            }
            turbulence 0.05
            scale <0.2, 0.3, 1>
          }
          finish {phong 1}
        }
      }

The keyword "wood" specifies a pigment pattern of concentric rings like 
rings in wood.  The color_map specifies that the color of the wood should 
blend from DarkTan to DarkBrown over the first 90% of the vein and from 
DarkBrown to VeryDarkBrown over the remaining 10%.  The turbulence slightly 
stirs up the pattern so the veins aren't perfect circles and the scale 
factor adjusts the size of the pattern.

The most of the patterns are set up by default to give you one "feature" 
across a sphere of radius 1.0. A "feature" is very roughly defined as a 
color transition. For example, a wood texture would have one band on a 
sphere of radius 1.0. In this example we scale the pattern using the 
"scale" keyword followed by a vector.  In this case we scaled 0.2 in the x 
direction, 0.3 in the y direction an the z direction is scaled by 1, which 
leaves it unchanged. Scale values larger than 1 will stretch an element. 
Scale values smaller than one will squish an element. And scale value 1 
will leave an element unchanged.


4.2.4 PRE-DEFINED TEXTURES

POV-Ray has some very sophisticated textures pre-defined in the standard 
include files "textures.inc" and "stones.inc".  Some are entire textures 
with pigment, normal and/or finish parameters already defined.  Some are 
just pigments or just finishes.   Change the definition of our sphere to 
the following and then re-render it: 

      sphere {
        <0, 1, 2>, 2
        texture {
          pigment {
            DMFWood4    // Pre-defined from textures.inc 
            scale 4     // Scale by the same amount in all
                        // directions
          }
          finish {Shiny}      // This finish defined in textures.inc
        }
      }

The pigment identifier DMFWood4 has already been scaled down quite small 
when it was defined.  For this example we want to scale the pattern larger.  
Because we want to scale it uniformly we can put a single value after the 
scale keyword rather than a vector of x,y,z scale factors.

Look through the file TEXTURES.INC to see what pigments and finishes are 
defined and try them out. Just insert the name of the new pigment where 
DMFWood1 is now or try a different finish in place of Shiny and re-render 
your file. 

Here is an example of using a complete texture identifier rather than just 
the pieces.

      sphere {
        <0, 1, 2>, 2
        texture { PinkAlabaster }
      }


4.3   MORE SHAPES
-----------------

So far, we've just used the sphere shape. There are many other types of 
shapes that can be rendered by POV-Ray.  First let's make some room in the 
image by changing the sphere from a radius of 2 to a radius of 1 like this:

      sphere {
        <0, 1, 2>, 1 
        texture { ... and so on.


4.3.1 PLANE OBJECT

Let's try out a computer graphics standard - "The Checkered Floor."  Add 
the following object to your .pov file:

      plane {
        <0, 1, 0>, 0 
        pigment {
          checker
            color Red
            color Blue
        }
      }

The object defined here is an infinite plane. The vector <0, 1, 0> is the 
surface normal of the plane (i.e., if you were standing on the surface, the 
normal points straight up.) The number afterward is the distance that the 
plane is displaced along the normal from the origin - in this case, the 
floor is placed at Y=0 so that the sphere at Y=1, radius= 1, is resting on 
it. 

Notice that there is no "texture{...}" statement.  There really is an 
implied texture there.  You might find that continually typing statements 
that are nested like "texture {pigment {...}}" can get to be a tiresome so 
POV-Ray lets you leave out the "texture{...}" under many circumstances.  In 
general you only need the texture block surrounding a texture identifier 
(like the PinkAlabaster example above), or when creating layered textures 
(which are covered later).  

This pigment uses the checker color pattern and specifies that the two 
colors red and blue should be used.

Because the vectors <1,0,0>, <0,1,0> and <0,0,1> are used frequently, POV-
Ray has 3 built-in vector identifiers "x", "y", and "z" respectively that 
can be used as shorthand.  Thus the plane could be defined as:

      plane { 
        y,0 
        pigment {... etc.

Note that you do not use angle brackets around vector identifiers.

Looking at the floor, you'll notice that the ball casts a shadow on the 
floor. Shadows are calculated very accurately by the ray tracer and creates 
precise, sharp shadows.  In the real world, penumbral or "soft" shadows are 
often seen. Later you'll learn how to use extended light sources to soften 
the shadows.


4.3.2 BOX OBJECT

There are several other simple shapes available in POV-Ray.  The most 
common are the box, cylinder and cone.  Try these examples in place of the 
sphere:

      box {
        <-1,0  ,-1>,     // Near lower left corner
        < 1,0.5, 3>      // Far upper right corner
        pigment {
          DMFWood4      // Pre-defined from textures.inc 
          scale 4       // Scale by the same amount in all
                        // directions
        }
        rotate y*20     // Equivalent to "rotate <0,20,0>"
      }

In this example you can see that a box is defined by specifying the 3D 
coordinates of opposite corners.  The first vector must be the minimum 
x,y,z coordinates and the 2nd vector must be the maximum x,y,z values.  Box 
objects can only be defined parallel to the axes.  You can later rotate 
them to any angle.  Note that you can perform simple math on values and 
vectors.  In the rotate parameter we multiplied the vector identifier "y" 
by 20.  This is the same as "<0,1,0>*20" or "<0,20,0>".  


4.3.3 CONE OBJECT

Here's another example:

      cone {
        <0,1,0>,0.3    // Center and radius of one end
        <1,2,3>,1.0    // Center and radius of other end
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }

The cone shape is defined by the center and radius of each end.  In this 
example one end is at location <0,1,0> and has radius of 0.3 while the 
other end is centered at <1,2,3> with radius 1.  If you want the cone to 
come to a sharp point then use a 0 radius.  The solid end caps are parallel 
to each other and perpendicular to the cone axis.  If you want a hollow 
cone with no end caps then add the keyword "open" after the 2nd radius like 
this:

      cone {
        <0,1,0>,0.3    // Center and radius of one end
        <1,2,3>,1.0    // Center and radius of other end
        open           // Removes end caps
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }


4.3.4 CYLINDER OBJECT

You may also define a cylinder like this:

      cylinder {
        <0,1,0>,       // Center of one end
        <1,2,3>,       // Center of other end
        0.5            // Radius
        open           // Remove end caps
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
      }

Finally the standard include file "shapes.inc" contains some pre-defined 
shapes that are about the size of a sphere with a radius of one unit.  You 
can invoke them like this:

      object {
        UnitBox
        pigment {DMFWood4  scale 4 }
        finish {Shiny}  
        scale 0.75
        rotate <-20,25,0>
        translate y
      }

That's the end of our brief tutorial.  We've only scratched the surface.  
The rest of this document provides a reference to all of POV-Ray's 
features.


5.1.4 FLOAT EXPRESSIONS

Many parts of the POV-Ray language require you to specify one or more 
floating point numbers.  A floating point number is a number with a decimal 
point.  Float literals are represented by an optional sign (-), some 
digits, an optional decimal point, and more digits.  If the number is an 
integer you may omit the decimal point and trailing zero.  If it is all 
fractional you may omit the leading zero.  POV-Ray supports scientific 
notation for very large or very small numbers.  The following are all valid 
float literals:

      1.0   -2.0  -4    34    3.4e6       2e-5        .3    0.6

Float identifiers may be declared and used anywhere a float can be used.  
See section 5.1.7 on declaring identifiers.  

Complex float expressions can be created using + - * / ( ) with float 
literals or identifiers.  Assuming the identifiers have been previously 
declared as floats, the following are valid float expressions:

      1+2+3       2*5         1/3         Row*3       Col*5

      (Offset-5)/2            This/That+Other*Thing

Expressions are evaluated left to right with innermost parenthesis 
evaluated first, then unary + or -, then multiply or divide, then add or 
subtract.

There are two built-in float identifiers.  The identifier "version" is the 
current setting of the version compatibility switch (See +MV under command-
line switches).  This allows you to save and restore the previous version 
switch.  For example suppose MYSTUFF.INC is in version 1.0 format.  At the 
top of the file you could put:

  #declare Temp_Vers = version    // Save previous value
  #version 1.0                    // Change to 1.0 mode

  ...   // Version 1.0 stuff goes here...

  #version Temp_Vers              // Restore previous version

The other float identifier is "clock".  Its value is set by the +K command-
line switch. (See +K under command-line switches).  This allows you to do 
limited animation control.  For example you could move an object using:

   translate <0.1*clock,0,0>

and render successive frames with +K1, +K2, +K3 etc.  In each frame the 
object would move 1/10th of a unit.


5.1.5 VECTOR EXPRESSIONS

POV-Ray operates in a 3D x,y,z coordinate system.  Often you will need to 
specify x, y and z values.  A "vector" is a set of three float values used 
for such specification.  Vectors consist of three float expressions that 
are bracketed by angle brackets < and >.  The three terms are separated by 
commas.  For example:

     < 1.0, 3.2, -5.4578 >

The commas are necessary to keep the program from thinking that the 2nd 
term is "3.2-5.4578" and that there is no 3rd term.  If you see an error 
message "Float expected but '>' found instead" it probably means two floats 
were combined because a comma was missing.

The three values correspond to the x, y and z directions respectively. For 
example, the vector <1,2,3> means the point that's 1 unit to the right, 2 
units up, and 3 units in front the center of the "universe" at <0,0,0>. 
Vectors are not always points, though. They can also refer to an amount to 
size, move, or rotate a scene element.

Vectors may also be combined in expressions the same as float values.  For 
example <1,2,3>+<4,5,6> evaluates as <5,7,9>.  Subtraction, multiplication 
and division are also performed on a term-by-term basis.  You may also 
combine floats with vectors.  For example 5*<1,2,3> evaluates as <5,10,15>.

Sometimes POV-Ray requires you to specify floats and vectors side-by-side.  
Thus commas are required separators whenever an ambiguity might arise.  For 
example <1,2,3>-4 evaluates as <-3,-2,-1> but <1,2,3>,-4 is a vector 
followed by a float.

Vector identifiers may be declared and used anywhere a vector can be used.  
See section 5.1.7 on declaring identifiers.

Because vectors almost always refer to the x, y and z coordinates, POV-Ray 
has three built-in vector identifiers "x "y" and "z".  Like all POV-Ray 
keywords they must be lower case.  The vector identifier x is equivalent to 
the vector <1,0,0>.  Similarly y is <0,1,0> and z is <0,0,1>.

Thus an expression like 5*x evaluates to 5*<1,0,0> or <5,0,0>.  The use of 
these identifiers can make the scene file easier to read.


5.1.6 TRANSFORMATIONS

Vectors are used not only as a notation for a point in space but are used 
in the transformations scale, rotate, and translate. Scale sizes a texture 
or object. Translate moves a texture or object. And rotate turns a texture 
or object.


5.1.6.1     Translate

An object or texture pattern may be moved by adding a "translate" 
parameter.  It consists of the keyword "translate" followed by a vector.  
The terms of the vector specify the number of units to move in each of the 
x, y, and z directions.  Translate moves the element relative to it's 
current position. For example,

  sphere { <10, 10, 10>, 1 
    pigment { Green }
    translate <-5, 2, 1>
  }

Will move the sphere from <10, 10, 10> to <5, 12, 11>.  It does not move it 
to absolute location <5, 2, 1>. Translating by zero will leave the element 
unchanged on that axis. For example,

  sphere { <10, 10, 10>, 1 
    pigment { Green }
    translate <0, 0, 0>
  }

Will not move the sphere at all.


5.1.6.2     Scale

You may change the size of an object or texture pattern by adding a "scale" 
parameter.  It consists of the keyword "scale" followed by a vector or a 
single float value.  If a vector is used, terms of the vector specify the 
amount of scaling in each of the x, y, and z directions.  If a float value 
is used, the item is uniformly scaled by the same amount in all directions.

Scale, is used to "stretch" or "squish" an element. Values larger than 1 
stretch the element on that axis. Values smaller than one are used to 
squish the element on that axis. Scale is relative to the current element 
size. If the element has been previously re-sized using scale, then scale 
will size relative to the new size. Multiple scale values may used.


5.1.6.3     Rotate

You may change the orientation of an object or texture pattern by adding a 
"rotate" parameter.  It consists of the keyword "rotate" followed by a 
vector.  The three terms of the vector specify the number of degrees to 
rotate about each of the x, y, and z axes.  

Note that the order of the rotations does matter.  Rotations occur about 
the x axis first, then the y axis, then the z axis.  If you are not sure if 
this is what you want then you should use multiple rotation statements to 
get a correct rotation. You should only rotate on one axis at a time. As 
in,

   rotate <0, 30, 0>  // 30 degrees around Y axis then,
   rotate <-20, 0, 0> // -20 degrees around X axis then,
   rotate <0, 0, 10>  // 10 degrees around Z axis.

Rotation is always performed relative to the axis.  Thus if an object is 
some distance from the axis of rotation, its will not only rotate but it 
will "orbit" about the axis as though it was swinging around on an 
invisible string.  

To work out the rotation directions, you must perform the famous "Computer 
Graphics Aerobics" exercise. Hold up your left hand. Point your thumb in 
the positive direction of the axis of rotation. Your fingers will curl in 
the positive direction of rotation. Similarly if you point your thumb in 
the negative direction of the axis your fingers will curl in the negative 
direction of rotation.  This is the famous "left-hand coordinate system". 

               ^
             +Y|   +Z/ _
               |    /_| |_  _
               |   _| | | |/ \
               |  | | | | |  |
               | /| | | | |  V
     -X        |/ | | | | |    +X
    <----------+--|-|-|-|-|------>
              /|  |       \____
             / |  |         ___|
            /  |  \        /
           /   |   |      /
        -Z/  -Y|
         /     |

In this illustration, the left hand is curling around the X axis. The thumb 
points in the positive X direction and the fingers curl over in the 
positive rotation direction.

If you want to use a right hand system, as some CAD systems such as AutoCAD 
do, the "right" vector in the camera specification needs to be changed. See 
the detailed description of the camera.  In a right handed system you use 
your right hand for the "Aerobics". 


5.1.6.4     Transforming Textures and Objects

When an object is transformed, all textures attached to the object AT THAT 
TIME are transformed as well. This means that if you have a translate, 
rotate, or scale in an object BEFORE a texture, the texture will not be 
transformed. If the scale, translate, or rotate is AFTER the texture then 
the texture will be transformed with the object.  If the transformation is 
INSIDE the "texture { }" statement then ONLY THE TEXTURE is affected.  The 
shape remains the same.  For example:

   sphere { <0, 0, 0>, 1
     texture { White_Marble }  // texture identifier from TEXTURES.INC
     scale 3                   // This scale affects both the 
                               // shape and texture 
   }

   sphere { <0, 0, 0>, 1
     scale 3             // This scale affects the shape only
     texture { White_Marble }  
   }

   sphere { <0, 0, 0>, 1
     texture { 
       White_Marble      
       scale 3           // This scale affects the texture only
     }  
   }

Transformations may also be independently applied to pigment patterns and 
surface normal (bump) patterns.  Note scaling a normal pattern affects only 
the width and spacing.  It does not affect the height or depth.  For 
example:

   box { <0, 0, 0>, <1, 1, 1>
     texture { 
       pigment {
         checker color Red color White
         scale 0.25  // This affects only the color pattern
       }
       normal {
         bumps 0.3   // This specifies apparent height of bumps
         scale 0.2   // Scales diameter and space between bumps but not 
                     //  not the height. Has no effect on color pattern.
       }
       rotate y*45   // This affects the entire texture but not
     }               //  the object. 
   }


5.1.6.5     Transformation Order

Because rotations are always relative to the axis and scaling is relative 
to the origin, you will generally want to create an object at the origin 
and scale and rotate it first.  Then you may translate it into its proper 
position.  It is a common mistake to carefully position an object and then 
to decide to rotate it.  Because a rotation of an object causes it to orbit 
the axis, the position of the object may change so much that it orbits out 
of the field of view of the camera!

Similarly scaling after translation also moves an object unexpectedly. If 
you scale after you translate, the scale will multiply the translate 
amount. For example:

  translate <5, 6, 7>
  scale 4 

Will translate to 20, 24, 28 instead of 5, 6, 7. Be careful when 
transforming to get the order correct for your purposes.



APPENDIX C  SUGGESTED READING
=============================

First, a shameless plug for two books that are specifically about POV-Ray:

     The Waite Group's Ray Tracing Creations
     By Drew Wells & Chris Young
     ISBN 1-878739-27-1
     Waite Group Press
     1993
and
     The Waite Group's Image Lab
     By Tim Wegner
     ISBN 1-878739-11-5
     Waite Group Press
     1992

Image Lab by Tim Wegner contains a chapter about POV-Ray. Tim is the co-
author of the best selling book, Fractal Creations, also from the Waite 
Group. 

Ray Tracing Creations by Drew Wells and Chris Young is an entire book about 
ray tracing with POV-Ray. 

This section lists several good books or periodicals that you should be 
able to locate in your local computer book store or your local university 
library. 

    "An Introduction to Ray tracing"
    Andrew S. Glassner (editor)
    ISBN 0-12-286160-4
    Academic Press
    1989

    "3D Artist" Newsletter
    ("The Only Newsletter about Affordable 
      PC 3D Tools and Techniques")
    Publisher: Bill Allen
    P.O. Box 4787
    Santa Fe, NM 87502-4787
    (505) 982-3532

    "Image Synthesis:  Theory and Practice"
    Nadia Magnenat-Thalman and Daniel Thalmann
    Springer-Verlag
    1987

    "The RenderMan Companion"
    Steve Upstill
    Addison Wesley
    1989

    "Graphics Gems"
    Andrew S. Glassner (editor)
    Academic Press
    1990

    "Fundamentals of Interactive Computer Graphics"
    J. D. Foley and A. Van Dam
    ISBN 0-201-14468-9
    Addison-Wesley
    1983

    "Computer Graphics:  Principles and Practice (2nd Ed.)" 
    J. D. Foley, A. van Dam, J. F. Hughes
    ISBN 0-201-12110-7
    Addison-Wesley,
    1990

    "Computers, Pattern, Chaos, and Beauty"
    Clifford Pickover
    St. Martin's Press

    "SIGGRAPH Conference Proceedings"
    Association for Computing Machinery
    Special Interest Group on Computer Graphics

    "IEEE Computer Graphics and Applications"
    The Computer Society
    10662, Los Vaqueros Circle
    Los Alamitos, CA 90720

    "The CRC Handbook of Mathematical Curves and Surfaces"
    David von Seggern
    CRC Press
    1990

    "The CRC Handbook of Standard Mathematical Tables"
    CRC Press
    The Beginning of Time
