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

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

[ Note that the generic word "directory" is used throughout.  Your 
operating system may use another word (subdirectory, folder, etc.) ]

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.

This section describes how to render a sample scene file. You can use these 
steps to render any of the sample scene files included in the sample scenes 
archive. 

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.

Quite a few example scenes are provided with this distribution in the 
example scenes archive. The scenes in the standard archives are designed to 
illustrate and teach you the features of the program.  Additionally the 
POV-Ray Team distributes several volumes of scenes in its ongoing series 
"The POV-Ray Scene Library"  These scene files range from very simple to 
very complex. They have been created by users of POV-Ray all over the 
world, and were picked to give examples of the variety of features in POV-
Ray. Many of them are stunning in their own right. 

The scenes were graciously donated by the artists because they wanted to 
share what they had created with other users. Feel free to use these scenes 
for any purpose. You can just marvel at them as-is, you can study the scene 
files to learn the artists techniques, or you can use them as a starting 
point to create new scenes of your own.

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.

   Note: The sequence of commands is not the same for
         every version of POV-Ray. There should be a 
         document with the executable describing the
         specific commands to render a file.

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.

The following section gives a detailed description of the command-line 
options.

The command-line parameters may be specified in any order. Repeated 
parameters overwrite the previous values except for the +L switch which 
defines include file library paths.  Up to 10 +L paths may be specified.  
Default parameters may also be specified in a file called "povray.def" or 
by the environment variable "POVRAYOPT". 

Switches may be specified in upper or lower case.  Switches must be 
preceded by a + (plus) or - (minus).  In switches which toggle a feature, 
the plus turns it on and minus turns it off.  For example +P turns on the 
"pause for keypress when finished" option while -P turns it off.  Other 
switches are used to specify values and do not toggle a feature.  Either 
plus or minus may be used in that instance.  For example +W320 sets the 
width to 320 pixels.  You could also use -W320 and get the same results.  
More examples follow this table.

Table 1 Command Line Parameters
Parameter......|.....Range........|...Description........................
-------------------------------------------------------------------------
+Annn          | 0.0 to 3.0       | Render picture with anti-aliasing,or 
               |                  | "smoothing", on.  Lower values cause 
               |                  | more smoothing.
+A             |                  | Use default 0.3 anti-aliasing
-A             |                  | Turn anti-aliasing off (default)
+Bnnn or -Bnnn | Varies w/ sys    | Output file buffer size.
+C             |                  | Continue an aborted partial image. 
-C             |                  | Start rendering from first line.
+Dxxx          | Varies w/sys     | Display image graphically while 
               |                  | rendering (Not available on all vers).
+Enn or +ERnn  | 1 to 32,767      | End row for tracing
               |  or 0.0 to 1.0   | a portion of a scene.
+ECnn          | 1 to 32,767      | End column for tracing
               |  or 0.0 to 1.0   | a portion of a scene.
+FT            |                  | Output Targa format file 
+FD            |                  | Output dump format file 
+FR            |                  | Output raw format file 
-F             |                  | Disable file output.
+Hnnn          | 1 to 32,767      | Height of image in pixels.
+Ifilespec     | Varies w/ sys    | Input scene file name, generally ends 
               |                  | in .pov.
+Jnnn.nnn      | 0.0 to 1.0       | Set amount of jitter for anti-aliasing
+J             |                  | Use anti-aliasing jitter 1.0 (default)
-J             |                  | Turn off anti-aliasing jitter 
+Knnn.nnn      | any real value   | Set "clock" float value for animation
+Lpathspec     | Varies w/ sys    | Library path: POV-Ray will search for 
               |                  | files in the directory listed here.
               |                  | Multiple lib paths may be specified.
-MB            |                  | Turn off bounding slabs
+MBnnn         | 0 to 32,767      | Use bounding slabs if more than nnn
               |                  | objects in scene.
+MSnnn         | 300 or more      | Set symbol table size (default 1000)
+MVn.m         | 1.0 or 2.0       | Set version compatibility mode
+Ofilespec     | Varies w/ sys    | Output image filename.
+P             |                  | Pause and wait for keypress after 
               |                  | tracing image.
-P             |                  | Don't pause
+Qn            |   0 to 9         | Image quality: 9 highest(default) to
               |                  | 0 lowest.
+Rn or -Rn     |   1 to 9         | Use n*n rays for anti-aliasing. Default 
               |                  | of 3 gives 9 rays; 4 gives 16 rays etc.
+Snn or +SRnn  | 1-32,768         | Start row for tracing
               |  or 0.0 to 1.0   | a portion of a scene.
+SCnn          | 1-32,768         | Start column for tracing
               |  or 0.0 to 1.0   | a portion of a scene.
+Vnn           | Varies w/sys     | Display verbose image stats while
               |                  | rendering. 
-V             |                  | No stats during rendering
+Wnnn          | 1-32,768         | Width of image in pixels.
+X             |                  | Allow abort with keypress.(IBM-PC).
-X             |                  | Disable abort with keypress.(IBM-PC).
--------------------------------------------------------------

      +Annn       Anti-alias with tolerance level nnn.
      +A          Anti-alias with tolerance level 0.3
      -A          Don't anti-alias (default)
      +Jn.nn      Scale factor for jittering
      +J          Jitter AA with scale 1.0 (default)
      -J          Turn off jittering
      +Rn or -Rn  Use n*n rays when anti-aliasing (default 3)

Anti-aliasing is a technique used to make the ray traced image look 
smoother. Often the color difference between two objects creates a "jaggy" 
appearance. When anti-aliasing is turned on, POV-Ray attempts to "smooth" 
the jaggies by shooting more rays into the scene and averaging the results. 
This technique can really improve the appearance of the final image. Be 
forewarned though, anti-aliasing drastically slows the time required to 
render a scene since it has do many more calculations to "smooth" the 
image. Lower numbers mean more anti-aliasing and also more time. Use anti-
aliasing for your final version of a picture, not the rough draft.

The +A option enables adaptive anti-aliasing. The number after the +A 
option determines the threshold for the anti-aliasing. 

If the color of a pixel differs from its neighbor (to the left or above) by 
more than the threshold, then the pixel is subdivided and super-sampled. If 
r1,g1,b1 and r2,g2,b2 are the rgb components of two pixels then the 
difference between pixels is computed by:

    diff=abs(r1-r2)+abs(g1-g2)+abs(b1-b2)

The rgb values are in the range 0.0 to 1.0 thus the most two pixels can 
differ is 3.0.  If the anti-aliasing threshold is 0.0, then every pixel is 
super-sampled. If the threshold is 3.0, then no anti-aliasing is done. 

The lower the contrast, the lower the threshold should be. Higher contrast 
pictures can get away with higher tolerance values.

Good values seem to be around 0.2 to 0.4.

The super-samples are jittered to introduce noise and to eliminate moire 
interference patterns. Note that the jittering "noise" is non-random and 
repeatable in nature, based on an object's 3-D orientation in space. Thus, 
it's okay to use anti-aliasing for animation sequences, as the anti-aliased 
pixels won't vary and flicker annoyingly from frame to frame.  The +Jnn.nn 
switch scales down the amount of jitter from its default value 1.0.  For 
example +J0.5 uses half the normal jitter.  Values over 1.0 jitter outside 
the pixel bounds and are not recommended.  Use -J to turn off jittering.

The +R switch controls the number of rows and columns of rays per pixel 
with anti-aliasing.  The default value 3 gives 3x3=9 rays per pixel.

The jittering and multiple rays are only used when +A is on.

      +Bnnn       Use an output file buffer of nnn kilobytes. 
      -Bnnn       Same as +Bnnn

The +B option allows you to assign large buffers to the output file. This 
reduces the amount of time spent writing to the disk. If this parameter is 
not specified, then as each scanline is finished, the line is written to 
the file and the file is flushed. On most systems, this operation insures 
that the file is written to the disk so that in the event of a system crash 
or other catastrophic event, at least part of the picture has been stored 
properly and retrievable on disk. (see also the +C option below.)  A value 
of +B30 is a good value to use to speed up small renderings.  A value of 
+B0 defaults to a small system-dependent buffer size.  Note neither +B0 nor 
-B turns this feature off.  Once a buffer is set, subsequent +B commands 
can change its size but cannot turn it off.

      +C          Continue partially complete rendering
      -C          Render from beginning (default)

If you abort a render while it's in progress or if you used the +E or +ER 
options to end the render prematurely, you can use the +C option to 
continue the render when you get back to it. This option reads in the 
previously generated output file, displays the image to date on the screen, 
then proceeds with the ray tracing. This option cannot be used if file 
output is disabled with -F.  It does not work with +S, +SR, +SC or +EC 
switches.

      +D          Use preview display
      -D          Turn preview display off (default)

If the +D option is used and your computer supports a graphic display, then 
the image will be displayed while the program performs the ray tracing. On 
most systems, the picture displayed is not as good as the one created by 
the post-processor because it does not try to make optimum choices for the 
color registers. 

The +D parameters are system-dependent and are listed in the executable 
documentation.

      +Snnn or +SRnnn   Start tracing at row number nnn.
      +SCnnn            Start tracing at column number nnn.
      +Ennn or +ERnnn   End tracing at row number nnn.
      +ECnnn            End tracing at column number nnn.

When doing test rendering it is often convenient to define a rectangular 
section of the whole screen so you can quickly check out one area of the 
image.  The +S and +E switches let you define starting and ending rows and 
columns for partial renderings.

The +S and +E options also allow you to begin and end the rendering of an 
image at a specific scan line so you can render groups of scanlines on 
different systems and concatenate them later.

WARNING: Image files created on with different executables on the same or 
different computers may not look exactly the same due to different random 
number generators used in some textures. If you are merging output files 
from different systems, make sure that the random number generators are the 
same. If not, the textures from one will not blend in with the textures 
from the other. 

Note if the number following +SR, +SC, +ER or +EC is a greater 1 then it is 
interpreted as a number of pixels.  If it is a decimal value between 0.0 
and 1.0 then it is interpreted as a percent of the total width or height of 
the image.  For example: +SR0.75 +SC0.75 starts on a row 75% down from the 
top at a column 75% from the left and thus renders only the lower-right 25% 
of the image.

      +FT         Uncompressed Targa-24 format (IBM-PC Default)
      +FD         Dump format (QRT-style)
      +FR         Raw format - one file each for Red, Green and Blue. 
      +F          Use default file type for your system
      -F          Turn off file output

Normally, you don't need to specify any form of +F option. The default 
setting will create the correct format image file for your computer. The 
docs included with the executable specify which format is used.

You can disable image file output by using the command line option -F. This 
is only useful if your computer has display options and should be used in 
conjunction with the +P option. If you disable file output using -F, there 
will be no record kept of the image file generated. This option is not 
normally used.

Unless file output is disabled (-F) POV-Ray will create an image file of 
the picture. This output file describes each pixel with 24 bits of color 
information. Currently, three output file formats are directly supported.  
They are +FT - Uncompressed Targa-24 format (IBM-PC Default), +FD - Dump 
format (QRT-style) and +FR - Raw format - one file each for Red, Green and 
Blue. 

      +Hnnn or -Hnnn    Set height of image in pixels
      +Wnnn or -Wnnn    Set width of image in pixels

These switches set the height and width of the image in pixels.  This 
specifies the image size for file output.  The preview display with the +D 
option will generally attempt to pick a video mode to accommodate this size 
but the +D settings do not in any way affect the resulting file output.

      +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

IBM-PC default file type is Targa, so the file is "data.tga".

Amiga uses dump format and the default outfile name is "data.dis".

Raw mode writes three files, "data.red", "data.grn" and "data.blu". On IBM-
PC's, the default extensions for raw mode are ".r8", ".g8", and ".b8" to 
conform to Piclab's "raw" format. Piclab is a widely used free-ware image 
processing program. Normally, Targa files are used with Piclab, not raw 
files.

      +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.

      +Lpathspec  Specify on of 10 library search paths

The +L option may be used to specify a "library" pathname to look in for 
include, parameter and image files. Multiple uses of the +L switch do not 
override previous settings.  Up to ten +L options may be used to specify a 
search path. The home (current) directory will be searched first followed 
by the indicated library directories in order.

      -MB         Turn off bounding slabs
      +MBnnn      Use bounding slabs if more than nnn objects in scene.

New in POV-Ray 2.0 is a spatial sub-division system called bounding slabs.  
It compartmentalizes all of the objects in a scene into rectangular slabs 
and computes which slabs a particular ray hits before testing the objects 
within the slab.  This can greatly improve rendering speed.  However for 
scenes with only a few objects the overhead of using slabs is not worth the 
effort.  The +MB switch sets the minimum number of objects before slabs are 
used.  The default is +MB25.  The -MB switch turns off slabs completely.

      +MSnnn or -MSnnn        Sets symbol table size (default 1000)

POV-Ray allocates a fixed number of spaces in its symbol table for declared 
identifiers.  The default of 1000 may be increased if you get a "Too many 
symbols" error message.

      +MVn.n or -MVn.n        Set version compatibility mode

While many language changes have been made for POV-Ray 2.0, most version 
1.0 syntax still works.  One new feature in 2.0 that is incompatible with 
any 1.0 scene files is the parsing of float expressions.  Setting +MV1.0 
turns off expression parsing as well as many warning messages so that 
nearly all 1.0 files will still work.  The "#version" language directive 
also can be used to change modes within scene files.  The +MV switch 
affects only the initial setting.

      +P          Pause when image is complete so preview image can
                  be seen.
      -P          Do not pause.  (default)

Normally when preview display is on you want to look at the image awhile 
before continuing.  The +P switch pauses and waits for you to press a key 
before going on.

      +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.

      +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.

      +X          Allow abort with keypress
      -X          Disable abort with keypress

On the IBM-PC versions only, when you specify the +X switch then any 
keypress will abort rendering.  The -X switch disables this feature.

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.