Section 6.1.2
Using INI Files

Because it is difficult to set more than a few options on a command line, you have the ability to put multiple options in one or more text files. These initialization files or INI files have .ini as their default extension. Previous versions of POV-Ray called them default files or DEF files. You may still use existing DEF files with this version of POV-Ray.

The majority of options you use will be stored in INI files. The command line switches are recommended for options which you will turn off or on frequently as you perform test renderings of a scene you are developing. The file povray.ini is automatically read if present. You may specify additional INI files on the command-line by simply typing the file name on the command line. For example:

POVRAY MYOPTS.INI

If no extension is given, then .ini is assumed. POV-Ray knows this is not a switch because it is not preceded by a plus or minus. In fact a common error among new users is that they forget to put the +I switch before the input file name. Without the switch, POV-Ray thinks that the scene file simple.pov is an INI file. Don't forget! If no plus or minus precedes a command line switch, it is assumed to be an INI file name.

You may have multiple INI files on the command line along with switches. For example:

POVRAY MYOPTS +V OTHER

This reads options from myopts.ini, then sets the +V switch, then reads options from other.ini.

An INI file is a plain ASCII text file with options of the form...

Option_keyword=VALUE ; Text after semicolon is a comment

For example the INI equivalent of the switch +Isimple.pov is...

Input_File_Name=simple.pov

Options are read top to bottom in the file but in general may be specified in any order. If you specify an option more than once, the previous values are generally overwritten with the last specification. The only exception is the Library_Path=path options. Up to ten unique paths may be specified.

Almost all INI-style options have equivalent +/- switches. The option reference section gives a detailed description of all POV-Ray options. It includes both the INI-style settings and the +/- switches.

The INI keywords are not case sensitive. Only one INI option is permitted per line of text. You may also include switches in your INI file if they are easier for you. You may have multiple switches per line but you should not mix switches and INI options on the same line. You may nest INI files by simply putting the file name on a line by itself with no equals sign after it. Nesting may occur up to ten levels deep.

For example:

; This is a sample INI file. This entire line is a comment. ; Blank lines are permitted. Input_File_Name=simple.pov ;This sets the input file name +W80 +H60 ; Traditional +/- switches are permitted too MOREOPT ; Read MOREOPT.INI and continue with next line +V ; Another switch ; That's all folks!

INI files may have labeled sections so that more than one set of options may be stored in a single file. Each section begins with a label in [] brackets. For example:

; RES.INI ; This sample INI file is used to set resolution. +W120 +H100 ; This section has no label. ; Select it with "RES" [Low] +W80 +H60 ; This section has a label. ; Select it with "RES[Low]" [Med] +W320 +H200 ; This section has a label. ; Select it with "RES[Med]" [High] +W640 +H480 ; Labels are not case sensitive. ; "RES[high]" works [Really High] +W800 +H600 ; Labels may contain blanks

When you specify the INI file you should follow it with the section label in brackets. For example...

POVRAY RES[Med] +Imyfile.pov

POV-Ray reads res.ini and skips all options until it finds the label Med. It processes options after that label until it finds another label and then it skips. If no label is specified on the command line then only the unlabeled area at the top of the file is read. If a label is specified, the unlabeled area is ignored.

Section 6.1.3
Using the POVINI Environment Variable

The environment variable POVINI is used to specify the location and name of a default INI file that is read every time POV-Ray is executed. If POVINI is not specified a default INI file may be read depending on the platform used. If the specified file does not exist a warning message is printed.

To set the environment variable under MS-DOS you might put the following line in your autoexec.bat file...

set POVINI=c:\povray3\default.ini

On most operating systems the sequence of reading options is as follows:

1.Read options from default INI file specified by the POVINI environment variable or platform specific INI file.
2.Read switches from command line (this includes reading any specified INI/DEF files).

The POVRAYOPT environment variable supported by previous POV-Ray versions is no longer available.

Section 6.2
Options Reference

As explained in the previous section, options may be specified by switches or INI-style options. Almost all INI-style options have equivalent +/- switches and most switches have equivalent INI-style option. The following sections give a detailed description of each POV-Ray option. It includes both the INI-style settings and the +/- switches.

The notation and terminology used is described in the tables below.

Keyword=boolturn Keyword on if bool equals true, yes, on or 1 and turn it off if it is any other value.
Keyword=truedo this option if true, yes, on or 1 is specified.
Keyword=falsedo this option if false, no, off or 0 is specified.
Keyword=fileany valid file name. Note: some options prohibit the use of any of the above true or false values as a file name. They are noted in later sections.

nany integer such as in +W320
n.nany float such as in Clock=3.45
0.nany float < 1.0 even if it has no leading 0
sany string of text
x or yany single character
pathany directory name, drive optional, no final path separator ("\" or "/", depending on the operating system)

Unless otherwise specifically noted, you may assume that either a plus or minus sign before a switch will produce the same results.

Section 6.2.1
Animation Options

POV-Ray 3.0 greatly improved its animation capability with the addition of an internal animation loop, automatic output file name numbering and the ability to shell out to the operating system to external utilities which can assemble individual frames into an animation. The internal animation loop is simple yet flexible. You may still use external programs or batch files to create animations without the internal loop as you may have done in POV-Ray 2.

Section 6.2.1.1
External Animation Loop

Clock=n.nSets "clock" float identifier to n.n
+Kn.nSame as Clock=n.n

The Clock=n.n option or the +Kn.n 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.0, +K20.0... etc. on successive renderings. It is up to the user to repeatedly invoke POV-Ray with a different Clock value and a different Output_File_Name for each frame.

Section 6.2.1.2
Internal Animation Loop

Initial_Frame=nSets initial frame number to n
Final_Frame=nSets final frame number
Initial_Clock=n.nSets initial clock value
Final_Clock=n.nSets final clock value
+KFInSame as Initial_Frame=n
+KFFnSame as Final_Frame=n
+KIn.nSame as Initial_Clock=n.n
+KFn.nSame as Final_Clock=n.n

The internal animation loop new to POV-Ray 3.0 relieves the user of the task of generating complicated sets of batch files to invoke POV-Ray multiple times with different settings. While the multitude of options may look intimidating, the clever set of default values means that you will probably only need to specify the Final_Frame=n or the +KFFn option to specify the number of frames. All other values may remain at their defaults.

Any Final_Frame setting other than -1 will trigger POV-Ray's internal animation loop. For example Final_Frame=10 or +KFF10 causes POV-Ray to render your scene 10 times. If you specified Output_File_Name=file.tga then each frame would be output as file01.tga, file02.tga, file03.tga etc. The number of zero-padded digits in the file name depends upon the final frame number. For example +KFF100 would generate file001.tga through file100.tga. The frame number may encroach upon the file name. On MS-DOS with an eight character limit, myscene.pov would render to mysce001.tga through mysce100.tga.

The default Initial_Frame=1 will probably never have to be changed. You would only change it if you were assembling a long animation sequence in pieces. One scene might run from frame 1 to 50 and the next from 51 to 100. The Initial_Frame=n or +KFIn option is for this purpose.

Note that if you wish to render a subset of frames such as 30 through 40 out of a 1 to 100 animation, you should not change Frame_Initial or Frame_Final. Instead you should use the subset commands described in section "Subsets of Animation Frames".

Unlike some animation packages, the action in POV-Ray animated scenes does not depend upon the integer frame numbers. Rather you should design your scenes based upon the float identifier clock. By default, the clock value is 0.0 for the initial frame and 1.0 for the final frame. All other frames are interpolated between these values. For example if your object is supposed to rotate one full turn over the course of the animation, you could specify rotate 360*clock*y. Then as clock runs from 0.0 to 1.0, the object rotates about the y-axis from 0 to 360 degrees.

The major advantage of this system is that you can render a 10 frame animation or a 100 frame or 500 frame or 329 frame animation yet you still get one full 360 degree rotation. Test renders of a few frames work exactly like final renders of many frames.

In effect you define the motion over a continuous float valued parameter (the clock) and you take discrete samples at some fixed intervals (the frames). If you take a movie or video tape of a real scene it works the same way. An object's actual motion depends only on time. It does not depend on the frame rate of your camera.

Many users have already created scenes for POV-Ray 2 that expect clock values over a range other than the default 0.0 to 1.0. For this reason we provide the Initial_Clock=n.n or +KIn.n and Final_Clock=n.n or +KFn.n options. For example to run the clock from 25.0 to 75.0 you would specify Initial_Clock=25.0 and Final_Clock=75.0. Then the clock would be set to 25.0 for the initial frame and 75.0 for the final frame. In-between frames would have clock values interpolated from 25.0 through 75.0 proportionally.

Users who are accustomed to using frame numbers rather than clock values could specify Initial_Clock=1.0 and Final_Clock=10.0 and Frame_Final=10 for a 10 frame animation.

For new scenes, we recommend you do not change the Initial_Clock or Final_Clock from their default 0.0 to 1.0 values. If you want the clock to vary over a different range than the default 0.0 to 1.0, we recommend you handle this inside your scene file as follows...

#declare Start = 25.0 #declare End = 75.0 #declare My_Clock = Start+(End-Start)*clock

Then use My_Clock in the scene description. This keeps the critical values 25.0 and 75.0 in your .pov file.

Note that more details concerning the inner workings of the animation loop are in the section on shell-out operating system commands in section "Shell-out to Operating System".

Next Section
Table Of Contents