Q: I get a floating point error on certain pictures. What's wrong?

A: The ray tracer performs many thousands of floating point operations when 
tracing a scene. If checks were added to each one for overflow or 
underflow, the program would be much slower. If you get this problem, first 
look through your scene file to make sure you're not doing something like:

- Scaling something by 0 in any dimension. 
  Ex: scale <34, 2, 0> will generate a warning.
- Making the look_at point the same as the location in the camera
- Looking straight down at the look_at point
- Defining triangles with two points the same (or nearly the same)
- Using a roughness value of zero (0).

If it doesn't seem to be one of these problems, please let us know. If you 
do have such troubles, you can try to isolate the problem in the input 
scene file by commenting out objects or groups of objects until you narrow 
it down to a particular section that fails. Then try commenting out the 
individual characteristics of the offending object.


Q: Are planes 2D objects or are they 3D but infinitely thin? 

A: Neither. Planes are 3D objects that divide the world into two half-
spaces. The space in the direction of the surface normal is considered 
outside and the other space is inside. In other words, planes are 3D 
objects that are infinitely thick. For the plane, plane { y, 0 }, every 
point with a positive Y value is outside and every point with a negative Y 
value is inside.
                            ^
                            |
                            |
                            |  Outside
                     _______|_______
                         Inside

Q: I'd like to go through the program and hand-optimize the assembly code 
in places to make it faster. What should I optimize? 

A: Don't bother. With hand optimization, you'd spend a lot of time to get 
perhaps a 5-10% speed improvement at the cost of total loss of portability. 
If you use a better ray-surface intersection algorithm, you should be able 
to get an order of magnitude or more improvement. Check out some books and 
papers on ray tracing for useful techniques. Specifically, check out 
"Spatial Subdivision" and "Ray Coherence" techniques.


Q: Objects on the edges of the screen seem to be distorted. Why? 

A: If the direction vector of the camera is not very long, you may get 
distortion at the edges of the screen. Try moving the location back and 
raising the value of the direction vector. 


Q: How do you position planar image maps without a lot of trial and error?

A: By default, images will be mapped onto the range 0,0 to 1,1 in the 
appropriate plane. You should be able to translate, rotate, and scale the 
image from there.


Q: How do you calculate the surface normals for smooth triangles? 

A:  There are two ways of getting another program to calculate them for 
you. There are now several utilities to help with this.

1) Depending on the type of input to the program, you may be able to 
calculate the surface normals directly. For example, if you have a program 
that converts B-Spline or Bezier Spline surfaces into POV-Ray format files, 
you can calculate the surface normals from the surface equations.

2) If your original data was a polygon or triangle mesh, then it's not 
quite so simple. You have to first calculate the surface normals of all the 
triangles. This is easy to do - you just use the vector cross-product of 
two sides (make sure you get the vectors in the right order). Then, for 
every vertex, you average the surface normals of the triangles that meet at 
that vertex.  These are the normals you use for smooth triangles. Look for 
the utilities such as RAW2POV.  RAW2POV has an excellent bounding scheme 
and the ability to specify a smoothing threshold.


Q: When I render parts of a picture on different systems, the textures 
don't match when I put them together. Why?

A: The appearance of a texture depends on the particular random number 
generator used on your system. POV-Ray seeds the random number generator 
with a fixed value when it starts, so the textures will be consistent from 
one run to another or from one frame to another so long as you use the same 
executables. Once you change executables, you will likely change the random 
number generator and, hence, the appearance of the texture. There is an 
example of a standard ANSI random number generator provided in IBM.C, 
include it in your machine-specific code if you are having consistency 
problems.


Q: I created an object that passes through its bounding volume. At times, I 
can see the parts of the object that are outside the bounding volume. Why 
does this happen? 

A: Bounding volumes are not designed to change the shape of the object. 
They are strictly a realtime improvement feature. The ray tracer trusts you 
when you say that the object is enclosed by a bounding volume. The way it 
uses bounding volumes is very simple: If the ray hits the bounding volume 
(or the ray's origin is inside the bounding volume),when the object is 
tested against that ray. Otherwise, we ignore the object. If the object 
extends beyond the bounding volume, anything goes. The results are 
undefined. It's quite possible that you could see the object outside the 
bounding volume and it's also possible that it could be invisible. It all 
depends on the geometry of the scene. If you want this effect use a 
clipped_by volume instead of bounded_by or use clipped_by { bounded_by } if 
you wish to clip and bound with the same object.

There are a number of excellent shareware CAD style modelers available on 
the DOS platform now that will create POV-Ray scene files.  The online 
systems mentioned elsewhere in this document are the best places to find 
these.

Hundreds of special-purpose utilities have been written for POV-Ray; data 
conversion programs, object generators, shell-style "launchers", and more. 
It would not be possible to list them all here, but again, the online 
systems listed will carry most of them. Most, following the POV-Ray spirit, 
are freeware or inexpensive shareware.

Some extremely elaborate scenes have been designed by drafting on graph 
paper.  Raytracer Mike Miller recommends graph paper with a grid divided in 
tenths, allowing natural decimal conversions.

Start out with a "boilerplate" scene file, such as a copy of BASICVUE.POV, 
and edit that.  In general, place your objects near and around the "origin" 
(0, 0, 0) with the camera in the negative z direction, looking at the 
origin.  Naturally, you will break from this rule many times, but when 
starting out, keep things simple.

For basic, boring, but dependable lighting, place a light source at or near 
the position of the camera.  Objects will look flat, but at least you will 
see them.  From there, you can move it slowly into a better position.

To see a quick version of your picture, render it very small. With fewer 
pixels to calculate the ray tracer can finish more quickly. -w160 -h100 is 
a good size.

Use the +Q "quality" switch when appropriate.

If there is a particular area of your picture that you need to see in high 
resolution, perhaps with anti-aliasing on (perhaps a fine-grained wood 
texture), use the +SC, +EC. +SR, and +ER switches to isolate a "window".

If your image contains a lot of inter-reflections, set max_trace_level to a 
low value such as 1 or 2.  Don't forget to put it back up when you're 
finished!

"Turn off" any unnecessary lights.  Comment out extended light and 
spotlight keywords when not needed for debugging.  Again, don't forget to 
put them back in before you retire for the night with a final render 
running!

If you've run into an error that is eluding you by visual examination, it's 
time to start bracketing your file.  Use the block comment characters ( 
/* ... */ ) to disable most of your scene and try to render again.  If you 
no longer get an error, the problem naturally lies somewhere within the 
disabled area.  Slow and methodical testing like this will eventually get 
you to a point where you will either be able to spot the bug, or go quietly 
insane.  Maybe both.

If you seem to have "lost" yourself or an object (a common experience for 
beginners) there are a few tricks that can sometimes help:

     1) Move your camera way back to provide a long range view.
     This may not help with very small objects which tend to
     be less visible at a distance, but it's a nice trick to keep
     up your sleeve.

     2) Try setting the ambient value to 1.0 if you suspect that
     the object may simply be hidden from the lights.  This will
     make it self-illuminated and you'll be able to see it even
     with no lights in the scene.

     3) Replace the object with a larger, more obvious "stand-in"
     object like a large sphere or box.  Be sure that all the
     same transformations are applied to this new shape so that
     it ends up in the same spot.

When animating objects with solid textures, the textures must move with the 
object, i.e. apply the same rotate or translate functions to the texture as 
to the object itself. This is now done automatically if the transformations 
are placed _after_ the texture block.

Example:
      shape { ...
        pigment { ... }
        scale < ... >
      }
Will scale the shape and pigment texture by the same amount.

While:
      shape { ...
        scale < ... >
        pigment { ... }
      }
Will scale the shape, but not the pigment.

Constants can be declared for most of the data types in the program 
including floats and vectors. By writing these to #include files, you can 
easily separate the parameters for an animation into a separate file.

Some examples of declared constants would be:
   #declare Y_Rotation = 5.0 * clock
   #declare ObjectRotation = <0, Y_Rotation, 0>
   #declare MySphere = sphere { <0, 0, 0>, 1.1234 }

Other examples can be found scattered throughout the sample scene files.

DOS users: Get ahold of DTA.EXE (Dave's Targa Animator) for 
creating .FLI/.FLC animations.  AAPLAY.EXE and PLAY.EXE are common viewers 
for this type of file.

When moving the camera in an animation (or placing one in a still image, 
for that matter) avoid placing the camera directly over the origin.  This 
will cause very strange errors.  Instead, move off center slightly and 
avoid hovering directly over the scene.

Wood is designed like a "log", with growth rings aligned along the z axis.  
Generally these will look best when scaled down by about a tenth (to a 
unit-sized object). Start out with rather small value for the turbulence, 
too (around 0.05 is good for starters).

The marble texture is designed around a pigment primitive that is much like 
an x-gradient.  When turbulated, the effect is different when viewed from 
the "side" or from the "end".  Try rotating it by 90 degrees on the y axis 
to see the difference.

You cannot get specular highlights on a totally black object. Try using a 
very dark gray, say Gray10 or Gray15, instead.

Try using POV-Ray itself to create images for height_fields:

      camera { location <0, 0, -2> }
      plane { z, 0
         finish { ambient 1 }    // needs no light sources
         pigment { bozo }        // or whatever.  Experiment.
      }

That's all you'll need to create a .tga file that can then be used as a 
height field in another image!

By making the direction vector in the camera longer, you can achieve the 
effect of a tele-photo lens. Shorter direction vectors will give a kind of 
wide-angle affect, but you may see distortion at the edges of the image.  
See the file "fov.inc" in the \POVRAY\INCLUDE directory for some predefined
field-of-view values.

If your spheres and circles aren't round, try increasing the direction 
vector slightly.  Often a value of 1.5 works better than the 1.0 default 
when spheres appear near the edge of the screen.

If you are importing images from other systems, you may find that the 
shapes are backwards (left-to-right inverted) and no rotation can make them 
correct.

Often, all you have to do is negate the terms in the right vector of the 
camera to flip the camera left-to-right (use the "right-hand" coordinate 
system).  Some programs seem to interpret the coordinate systems 
differently, however, so you may need to experiment with other camera 
transformations if you want the y and z vectors to work as POV-Ray does.

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

The following is legal information pertaining to the use of the Persistence 
of Vision Ray Tracer a.k.a POV-Ray. It applies to all POV-Ray source files,  
executable (binary) files, scene files, documentation files contained in 
the official POV archives.  (Certain portions refer to custom versions of 
the software,  there are specific rules listed below for these versions 
also.)  All of these are referred to here as "the software". 

THIS NOTICE MUST ACCOMPANY ALL OFFICIAL OR CUSTOM PERSISTENCE OF VISION 
FILES. IT MAY NOT BE REMOVED OR MODIFIED. THIS INFORMATION PERTAINS TO ALL 
USE OF THE PACKAGE WORLDWIDE.  THIS DOCUMENT SUPERSEDES ALL PREVIOUS 
LICENSES OR DISTRIBUTION POLICIES.


                        IMPORTANT LEGAL INFORMATION

Permission is granted to the user to use the Persistence of Vision 
Raytracer and all associated files in this package to create and render 
images. The use of this software for the purpose of creating images is 
free. The creator of a scene file and the image created from the scene 
file, retains all rights to the image and scene file they created and may 
use them for any purpose commercial or non-commercial.  

The user is also granted the right to use the scenes files and include 
files distributed in the INCLUDE and DEMO sub-directories of the POVDOC 
archive when creating their own scenes.  Such permission does not extend to 
files in the POVSCN archive.  POVSCN files are for your enjoyment and 
education but may not be the basis of any derivative works.

This software package and all of the files in this archive are copyrighted 
and may only be distributed and/or modified according to the guidelines 
listed below.  The spirit of the guidelines below is to promote POV-Ray as 
a standard ray tracer, provide the full POV-Ray package freely to as many 
users as possible, prevent POV-Ray users and developers from being taken 
advantage of, enhance the life quality of those who come in contact with 
POV-Ray.  This legal document was created so these goals could be realized.  
You are legally bound to follow these rules, but we hope you will follow 
them as a matter of ethics, rather than fear of litigation.

No portion of this package may be separated from the package and 
distributed separately other than under the conditions specified in the 
guidelines below.  

This software may be bundled in other software packages according to the 
conditions specified in the guidelines below.

This software may be included in software-only compilations using media 
such as, but not limited to, floppy disk, CD-ROM, tape backup, optical 
disks, hard disks, or memory cards.  There are specific rules and 
guidelines listed below for the provider to follow in order to legally 
offer POV-Ray with a software compilation.

The user is granted the privilege to modify and compile the source for 
their own personal use in any fashion they see fit.  What you do with the 
software in your own home is your business.

If the user wishes to distribute a modified version of the software (here 
after referred to as a "custom version") they must follow the guidelines 
listed below.  These guidelines have been established to promote the growth 
of POV-Ray and prevent difficulties for users and developers alike.  Please 
follow them carefully for the benefit of all concerned when creating a 
custom version.  

You may not incorporate any portion of the POV-Ray source code in any 
software other than a custom version of POV-Ray.  However authors who 
contribute source to POV-Ray may still retain all rights to use their 
contributed code for any purpose as described below.

The user is encouraged to send enhancements and bug fixes to the POV-Team, 
but the team is in no way required to utilize these enhancements or fixes.  
By sending material to the POV-Team, the contributor asserts that he owns 
the materials or has the right to distribute these materials.  He 
authorizes the POV-Team to use the materials any way they like.  The 
contributor still retains rights to the donated material, but by donating 
you grant equal rights to the POV-Team.  The POV-Team doesn't have to use 
the material, but if we do, you do not acquire any rights related to POV-
Ray.  We will give you credit if applicable.


                    GENERAL RULES FOR ALL DISTRIBUTION

The permission to distribute this package under certain very specific 
conditions is granted in advance, provided that the above and following 
conditions are met.

These archives must not be re-archived using a different method without the 
explicit permission of the POV-Team.  You may rename the archives only to 
meet the file name conventions of your system or to avoid file name 
duplications but we ask that you try to keep file names as similar to the 
originals as possible.  (For example:POVDOC.ZIP to POVDOC20.ZIP)

You must distribute a full package of archives as described in the next 
section.

Non-commercial distribution (such as a user copying the software for a 
personal friend or colleague and not charging money or services for that 
copy) has no other restrictions.  This does not include non-profit 
organizations or computer clubs. These groups should use the 
Shareware/Freeware distribution company rules below.

The POV-Team reserves the right to withdraw distribution privileges from 
any group, individual, or organization for any reason.


                       DEFINITION OF "FULL PACKAGE"

POV-Ray is contained in 4 archives for each hardware platform.  1) An 
executable archive, 2) A documentation archive, 3) Sample scene archives, 
4) Source code archive.

A "full package" is defined as one of the following bundle options:
   1  All archives (executable, docs, scenes, source)
   2  User archives (executable, docs, scenes but no source)
   3  Programmer archives (source, docs, scenes but no executable)

POV-Ray is officially distributed for IBM-PC compatibles running MS-Dos; 
Apple Macintosh; and Commodore Amiga.  Other systems may be added in the 
future.

Distributors need not support all platforms but for each platform you 
support you must distribute a full package.  For example an IBM-only BBS 
need not distribute the Mac versions.


              CONDITIONS FOR DISTRIBUTION OF CUSTOM VERSIONS

You may distribute custom compiled versions only if you comply with the 
following conditions.

     Mark your version clearly on all modified files stating this to be a 
modified and unofficial version.
     Make all of your modifications to POV-Ray freely and publicly 
available.
     You must provide all POV-Ray support for all users who use your custom 
version.  The POV-Ray Team is not obligated to provide you or your users 
any technical support.
     You must provide documentation for any and all modifications that you 
have made to the program that you are distributing.
     Include clear and obvious information on how to obtain the official 
POV-Ray.
     Include contact and support information for your version.  Include 
this information in the DISTRIBUTION_MESSAGE macros in the source file 
FRAME.H and insure that the program prominently displays this information.  
Include all credits and credit screens for the official version.
     Include a copy of this document.


                    CONDITIONS FOR COMMERCIAL BUNDLING

Vendors wishing to bundle POV-Ray with commercial software or with 
publications must first obtain explicit permission from the POV-Ray Team.  
This includes any commercial software or publications, such as, but not 
limited to, magazines, books, newspapers, or newsletters in print or 
machine readable form.

The POV-Ray Team will decide if such distribution will be allowed on a 
case-by-case basis and may impose certain restrictions as it sees fit.  The 
minimum terms are given below. Other conditions may be imposed.

     Purchasers of your product must not be led to believe that they are
paying for POV-Ray.  Any mention of the POV-Ray bundle on the box, in
advertising or in instruction manuals must be clearly marked with a
disclaimer that POV-Ray is free software and can be obtained for free or
nominal cost from various sources.
     Include clear and obvious information on how to obtain the official
POV-Ray.
     Include a copy of this document.
     You must provide all POV-Ray support for all users who acquired POV-
Ray through your product.  The POV-Ray Team is not obligated to provide you
or your customers any technical support.
     Include a credit page or pages in your documentation for POV-Ray.
     If you modify any portion POV-Ray for use with your hardware or
software, you must follow the custom version rules in addition to these
rules.
     Include contact and support information for your product.
     Must include official documentation with product.


         CONDITIONS FOR SHAREWARE/FREEWARE DISTRIBUTION COMPANIES

Shareware and freeware distribution companies may distribute the archives 
under the conditions following this section. 

You must notify us that you are distributing POV-Ray and must provide us 
with information on how to contact you should any support issues arise. 

No more than five dollars U.S. ($5) can be charged per disk for the copying 
of this software and the media it is provided on. Space on each disk must 
used completely.  The company may not put each archive on a separate disk 
and charge for three disks if all three archives will fit on one disk. If 
more than one disk is needed to store the archives then more than one disk 
may be used and charged for.

Distribution on high volume media such as backup tape or CD-ROM is 
permitted if the total cost to the user is no more than $0.10 per megabyte 
of data.  For example a CD-ROM with 600 meg could cost no more than $60.00.


                 CONDITIONS FOR ON-LINE SERVICES AND BBS'S

On-line services and BBS's may distribute the POV-Ray archives under the 
conditions following this section. 

The archives must be all be easily available on the service and should be 
grouped together in a similar on-line area.  

It is strongly requested that BBS operators remove prior versions of POV-
Ray to avoid user confusion and simplify or minimize our support efforts.

The on-line service or BBS may only charge standard usage rates for the 
downloading of this software. A premium may not be charged for this 
package. I.E. CompuServe or America On-Line may make these archives 
available to their users, but they may only charge regular usage rates for 
the time required to download. They must also make the all of the archives 
available in the same forum, so they can be easily located by a user.

                                DISCLAIMER

This software is provided as is without any guarantees or warranty.  
Although the authors have attempted to find and correct any bugs in the 
package, they are not responsible for any damage or losses of any kind 
caused by the use or misuse of the package. The authors are under no 
obligation to provide service, corrections, or upgrades to this package.

We love to hear about how you're using and enjoying the program. We also 
will do our best try to solve any problems you have with POV-Ray and 
incorporate good suggestions into the program.

If you have a question regarding commercial use of, distribution of, or 
anything particularly sticky, please contact Chris Young, the development 
team coordinator. Otherwise, spread the mail around. We all love to hear 
from you!

The best method of contact is e-mail through CompuServe for most of us. 
America On-Line and Internet can now send mail to CompuServe, also, just 
use the Internet address and the mail will be sent through to CompuServe 
where we read our mail daily. 

Please do not send large files to us through the e-mail without asking 
first. We pay for each minute on CompuServe and large files can get 
expensive. Send a query before you send the file, thanks!

Chris Young
(Team Coordinator. Worked on everything.)
CIS: 76702,1655
Internet 76702.1655@compuserve.com
US Mail:
  3119 Cossell Drive
  Indianapolis, IN 46224 U.S.A.


Drew Wells 
(Former team leader. Worked on everything.)
CIS: 73767,1244
Internet: 73767.1244@compuserve.com
AOL: Drew Wells
Prodigy: SXNX74A (Not used often)


Other authors and contributors in alphabetical order:
-----------------------------------------------------
David Buck
(Original author of DKBTrace)
(Primary developer, quadrics, docs)
INTERNET:(preferred) dbuck@ccs.carleton.ca
CIS: 70521,1371

Aaron Collins
(Co-author of DKBTrace 2.12)
(Primary developer, IBM-PC display code,phong) 
CIS: 70324,3200

Alexander Enzmann
(Primary developer, Blobs, quartics, boxes, spotlights) 
CIS: 70323,2461
INTERNET: xander@mitre.com

Dan Farmer
(Primary developer, docs, scene files)
CIS:70703,1632

Douglas Muir
(Bump maps and height fields)
CIS: 76207,662
Internet:dmuir@media-lab.media.mit.edu

Bill Pulver
(Time code and IBM-PC compile)
CIS: 70405,1152

Charles Marslette
(IBM-PC display code)
CIS: 75300,1636

Mike Miller
(Artist, scene files, stones.inc)
CIS: 70353,100

Jim Nitchals
(Mac version, scene files)
CIS: 73117,3020
AppleLink: jimn8
Internet: 73117.3020@compuserve.com

Eduard Schwan
(Mac version, docs)
CIS: 71513,2161
AppleLink: JL.Tech
Internet: 71513.2161@compuserve.com

Randy Antler
(IBM-PC display code enhancements)
CIS: 71511,1015

David Harr
(Mac balloon help)
CIS: 72117,1704

Scott Taylor
(Leopard and Onion textures)
CIS: 72401,410
 
Chris Cason
(colour X-Windows display code)
CIS: 100032,1644

Dave Park 
(Amiga support; added AGA video code)
CIS: 70004,1764