Section 2.4.6
POV-Ray Related Books and CD-ROMs

The following items were produced by POV-Team members. Although they are only current to POV-Ray 2.2 they will still be helpful. Steps are being taken to update the POV-Ray CDROM to version 3.0, with a new version expected around October 1996.

The books listed below have been recently listed as out-of-print but may still be found in some bookstores or libraries (Visit http://www.dnai.com:80/waite/ for more details).

  Ray Tracing Creations, 2d Ed.
  Chris Young and Drew Wells
  ISBN 1-878739-69-7
  Waite Group Press 1994
    700 pages with color insert and POV-Ray 2.2 on 3.5" MS-DOS disk.

  Ray Tracing Worlds with POV-Ray
  Alexander Enzmann, Lutz Kretzschmar, Chris Young,
  ISBN 1-878739-64-6
  Waite Group Press 1994
    Includes Moray 1.5x modeller and POV-Ray 2.2 on 3.5" MS-DOS disks.

  Ray Tracing for the Macintosh CD
  Eduard Schwan
  ISBN 1-878739-72-7
  Waite Group Press, 1994
    Comes with a CD-ROM full of scenes, images, and QuickTime movies,
    and an interactive keyword reference. Also a floppy with POV-Ray for
    those who don't have a CD ROM drive.

'The Official POV-Ray CDROM' The Official POV-Ray CDROM: The Official POV-Ray CDROM is a compilation of images, scene source, program source, utilities and tips on POV-Ray and 3D graphics from the Internet and Compuserve. This CD is aimed not only at those who want to create their own images or do general 3D programming work, but also at those who want simply to experience some high-quality renderings done by some of the best POV-Ray artists, and to learn from their source code. The CDROM contains over 500 ray-traced images.

It's a good resource for those learning POV-Ray as well as those who are already proficient, and contains a Microsoft Windows-based interactive tutorial. The disk comes with a fold-out poster and reference sheet. The CD is compatible with DOS/Windows and Macintosh formats.

The CDROM is available for free retrieval and browsing on the World Wide Web at http://www.povray.org/pov-cdrom. For more details you may also visit http://www.povray.org/povcd.


Section 3
Quick Start

The next section describes how to quickly install POV-Ray and render sample scenes on your computer. It is assumed that you are using an IBM-PC compatible computer with MS-DOS. For other platforms you must refer to the specific documentation included in archive that contains POV-Ray.

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

[ 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:

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.


Section 3.2
Basic Usage

Notice: If you did not install the program using the install.exe system, the examples and instructions given here may not work! The installation process configures povray.ini and several important batch files. Without these files configured, the examples herein may not work.

POV-Ray's basic purpose is to read a scene description written in the POV language and to write an image file. The scene files are plain ASCII text files that you create using a text editor. Dozens of sample files are included with this package to illustrate the various features.

You invoke POV-Ray by typing a command at the MS-DOS prompt. The command is povray and it must be followed by one or more command line switches. Each switch begins with a plus or minus sign. Blanks separate the switches. The switches may be upper or lower case.

Note: The examples in this documentation assume you installed POV-Ray in the c:\povray3 directory. The installer will let you install POV-Ray anywhere and will properly configure it for the drive and directory you specified. You just substitute that drive and directory anywhere we tell you to use c:\povray3. Change to that directory now. Then type the following command line and press [ENTER]

  POVRAY +ISHAPES +D1

The +I command (for input) tells the program what file to read as input. If you don't give an extension on the file name, .pov is assumed. Thus +Ishapes tells it to read in shapes.pov to be rendered.

The +D switch (for display) tells the program to turn the graphic preview display on. A -D would turn it off. The number "1" tells it what type of display to use. Type "1" is the old fashioned standard generic VGA at 320 by 200 resolution and just 256 colors. This is pretty much guaranteed to work on any VGA video system.

There are other options in effect besides those you typed on the command line. They are stored in a file called povray.ini which was created by the install system. POV-Ray automatically looks for this file in the same directory where povray.exe resides. See "INI Files" and "Using INI Files" for more information on povray.ini and other INI files.

When you enter the command shown above, you will see brightly colored geometric shapes begin to appear as POV-Ray calculates the color of each pixel row by row. You will probably be disappointed with the graphic display results. That is because this is only a preview display. The actual image is in full 24-bit color but we cannot display that high quality using simple VGA with a fixed set of 256 colors. If your hardware supports the VESA interface standard or you have a VESA TSR driver loaded, try running with +DG rather than +D1. This will give you access to all of the various modes your video hardware can use. If you have 15-bit or 16- bit high color capability try +DGH or if you have 24-bit true color capability try +DGT to see the image in all its glory. See section "Display Types" below for more information on graphics preview.

When the program finishes, you will hear beeps. After admiring the image, press [ENTER]. You will see a text screen of statistics. If the text is too much to fit on the screen you may press [CURSOR UP] or [CURSOR DOWN] keys to read more text. Notice that there are tabs at the bottom of the screen. Press [CURSOR LEFT] or [CURSOR RIGHT] keys to view other interesting text information. Press [ENTER] again to exit POV-Ray.

If you do not have high color or true color ability you will have to view the image file to see the real colors. The image file shapes.tga is written to your current directory. By default POV-Ray creates files in TGA format. This is a standard format for storing 24-bit true-color images. You will need an image viewing program to view the file. Such programs are usually available from the same place where you obtained POV-Ray but a viewer is not included in this package.

If you cannot view TGA files you may add the switch +FN and POV-Ray will output PNG (Portable Network Graphic) format. If PNG format viewer is not available then type the following

  T2G SHAPES

and press [ENTER]. This will run a batch file that invokes the tga2gif program. The program will read your shapes.tga file, create an optimal 256 color palette and write a GIF format file shapes.gif. Most image viewing programs support GIF.


Section 3.2.1
Running Files in Other Directories

Normally POV-Ray only looks in the current directory for the files it needs. It does not search your MS-DOS path for data files; it only searches for programs. In the sample scene you just ran, file shapes.pov was in the current directory so this was no problem. That scene also needed other files but your povray.ini file tells POV-Ray other places to search for necessary files.

If you allowed the install system to update your autoexec.bat file, then you can change to any drive or directory and can run POV-Ray from that directory. You will also be able to use the batch files and utilities that came with this package in any directory. For future reference let's call the "use-c:\povray3-in-your-path-plan" as plan one.

There are some circumstances where you may not want to put c:\povray3 in your path. There is a limit of 128 characters in your path statement and you may not have room for it. Try rendering the shapes example from a different directory. If it doesn't work, then you forgot to re-boot your system so the new path takes effect. If after re-booting it still doesn't work, it probably means your path is too full. You will have to adopt a different plan.

Chances are, you already have several directories in your path. Most systems have c:\DOS, c:\windows or some directory such as c:\utility already in the path. We have provided several small batch files that you can copy to that directory. For future reference we'll call the "put-batch-files-in-a-directory-already-on-the-path-plan" as plan two.

At any DOS prompt, type the word path and press [ENTER]. It will show you what directories are already on your path. Then copy the following files from your c:\povray3 directory to any of the directories already on your path. The files are:

  RUNPOV.BAT RERUNPOV.BAT RUNPHELP.BAT T2G.BAT

Once you have copied these files, try the following example. In this case, do not invoke the program with the command povray. Instead use runpov as follows:

  cd \POVRAY3\POV3DEMO\SHOWOFF
  RUNPOV +ISUNSET3 +D1

This changes to the \povray3\pov3demo\showoff directory where the file sunset3.pov is found. It runs the file runpov.bat. That batch file is set up to run POV-Ray even if it is not on the DOS path. It also passes the switches along to POV-Ray. These batch files have other uses, even if you are using plan one as described above or plan three as described below. For more on these batch files, see "Batch Files".

All of the early examples in this document assumed you were running POV-Ray from the directory where it was installed such as c:\povray3. This approach of always using the installation directory is in fact plan three. If you are using this method, you need to tell POV-Ray where else to look for files. In the case of sunset3.pov you could do this:

  POVRAY +IC:\POVRAY3\POV3DEMO\SHOWOFF\SUNSET3 +D1

However some scenes need more than one file. For example the directory drums2 that can be found under \povray3\povscn\level3 contains three files: drums.pov, drums.inc and rednewt.gif all of which are required for that one scene. In this case you should use the +L switch (for library) to add new library paths to those that POV-Ray will search. You would render the scene with this command.

  POVRAY +L\POVRAY3\POVSCN\LEVEL3\DRUMS2 +IDRUMS +D1

Section 3.2.2
INI Files

There were more options used in these renderings than just the switches +I, +D, and +L that you specify. When you run the program, POV- Ray automatically looks for the file povray.ini in whatever directory that povray.exe is in. The povray.ini file contains many options that control how POV-Ray works. We have set this file up so that it is especially easy to run your first scene with minimal problems. The file should be placed in the same directory as povray.exe and it will automatically read when POV-Ray is run. If you ever move povray.exe to a different directory, be sure to move povray.ini too.

Complete details on all of the available switches and options that can be given on the command line or in povray.ini are given in "POV-Ray Options".

You may also create INI files of your own with switches or options similar to povray.ini. If you put a file name on the command line without a plus or minus sign before it, POV-Ray reads it as an INI file. Try this...

  POVRAY RES120 +ISHAPES +D1

This causes POV-Ray to look for a file called res120.ini which we have provided. It sets your resolution to 120 by 90 pixels for a quick preview. The following INI files have been provided for you.

RES120.INISets resolution to 120 by 90.
RES320.INISets resolution to 320 by 200.
RES640.INISets resolution to 640 by 480.
RES800.INISets resolution to 800 by 600.
RES1K.INISets resolution to 1024 by 768.
LOW.INISets low quality at 120 by 90.
SLOW.INITurns on radiosity and anti-aliasing; very slow but beautiful.
TGAFLI.INI TGAFLC.INICreate an FLI/FLC animation from TGA images.
PNGFLI.INI PNGFLC.INICreate an FLI/FLC animation from DTA images.
ZIPFLI.INI ZIPFLC.INICreate an FLI/FLC animation from zipped images. See "ANIMATION TIPS" below.

You can create your own custom INI's which can contain any command in the reference guide.


Section 3.2.3
Alternatives to POVRAY.INI

The povray.ini file is supposed to hold your favorite global default options that you want to use all the time. You should feel free to edit it with new options that suit your needs. However it must be located in the same directory as povray.exe or it won't be found. The DOS path isn't searched nor will +L commands help because povray.ini is processed before any command line switches.

If your povray.exe resides on a CD-ROM then you can't edit the povray.ini on the CD. There is an alternative. You may use an environment variable to specify an alternative global default.

In your autoexec.bat file add a line similar to this:

  set POVINI=D:\DIRECT\FILE.INI

which sets the POVINI environment variable to whatever drive, directory and INI file you choose. If you specify any POVINI environment variable then povray.ini is not read. This is true even if the file you named doesn't exist. Note that you are specifying an entire path and file name. This is not a pointer to a directory containing povray.ini. It is a pointer to the actual file itself.

Note that the POVRAYOPT environment variable in previous versions of POV-Ray is no longer supported.


Section 3.2.4
Batch Files

We've already described how the file runpov.bat can be used as an alternative to running POV-Ray directly. runpov.bat also has one other use. It uses the +GI switch to create a file called rerun.ini. This makes it very easy to run the same file over again with the same parameters. When creating your own scene files you will probably make dozens of test renders. This is a very valuable feature. Here is how it works... Suppose you render a scene as follows:

  RUNPOV +IMYSCENE +D1 RES120

This renders myscene.pov at 120 by 90 resolution. Note there is no such scene. This is hypothetical. After viewing it, you noticed a mistake which you fixed with your text editor. To rerun the scene type:

  RERUNPOV

and that's all. It will rerun the same scene you just ran. Suppose you want more detail on the next run. You can add more switches or INI files. For example:

  RERUNPOV RES320

will rerun at higher resolution. Subsequent uses of rerunpov will be at 320 by 200 until you tell it differently. As another example, the +A switch turns on anti-aliasing. Typing "rerunpov +A" reruns with anti- aliasing on. All subsequent reruns will have it on until you do a "rerunpov -A" to turn it off. Note if you do another runpov it starts over from your povray.ini defaults and it overwrites the old rerun.ini.

Two other batch files are included. runphelp.bat is only used as an alternative way to run povhelp from another directory. If you used installation plan two then use runphelp.bat rather than povhelp.exe. This batch file serves no other purpose.

Finally t2g.bat invokes the tga2gif.exe program for converting TGA files to GIF files. You could run \FILE {tga2gif} directly but its default parameters do not generally produce the best results. If you use T2G instead, it adds some command line switches which work better. For a full list of switches available for tga2gif, type tga2gif with no parameters and it will display the available switches and options.


Next Section
Table Of Contents