The first concept we'll need to know is the INI file settings, Initial_Frame and Final_Frame. These are very handy settings that will allow us to render a particular number of frames and each with its own unique frame number, in a completely hands free way. It is of course, so blindingly simple that it barely needs explanation, but here's an example anyway. We just add the following lines to our favorite INI file settings
and we'll initiate an automated loop that will generate 20 unique frames. The settings themselves will automatically append a frame number onto the end of whatever we have set the output file name for, thus giving each frame an unique file number without having to think about it. Secondly, by default, it will cycle the clock variable up from 0 to 1 in increments proportional to the number of frames. This is very convenient, since, no matter whether we are making a five frame animated GIF or a 300 frame MPEG sequence, we will have a clock value which smoothly cylces from exactly the same start to exactly the same finish.
Next, about that clock. In our example with the rolling ball code, we saw that sometimes we want the clock to cycle through values other than the default of 0.0 to 1.0. Well, when that's the case, there are setting for that too. The format is also quite simple. To make the clock run, as in our example, from 0.0 to 2.0, we would just add to your INI file the lines
Now, suppose we were developing a sequence of 100 frames, and we detected a visual glitch somewhere in frames, say 51 to 75. We go back over our code and we think we've fixed it. We'd like to render just those 25 frames instead of redoing the whole sequence from the beginning. What do we change?
If we said make Initial_Frame = 51, and Final_Frame = 75, we're wrong. Even though this would re-render files named with numbers 51 through 75, they will not properly fit into our sequence, because the clock will begin at its initial value starting with frame 51, and cycle to final value ending with frame 75. The only time Initial_Frame and Final_Frame should change is if we are doing an essentially new sequence that will be appended onto existing material.
If we wanted to look at just 51 through 75 of the original animation, we need two new INI settings
Added to settings from before, the clock will still cycle through its values proportioned from frames 1 to 100, but we will only be rendering that part of the sequence from the 51st to the 75th frames.
This should give us a basic idea of how to use animation. Although, this introductory tutorial doesn't cover all the angles. For example, the last two settings we just saw, subset animation, can take fractional values, like 0.5 to 0.75, so that the number of actual frames will not change what portion of the animation is being rendered. There is also support for efficient odd-even field rendering as would be useful for animations prepared for display in interlaced playback such as television (see the reference section for full details).
With POV-Ray 3 now fully supporting a complete host of animation options, a whole fourth dimension is added to the raytracing experience. Whether we are making a FLIC, AVI, MPEG, or simply an animated GIF for our web site, animation support takes a lot of the tedium out of the process. And don't forget that phase and clock can be used to explore the range of numerous texture elements, as well as some of the more difficult to master objects (hint: the julia fractal for example). So even if we are completely content with making still scenes, adding animation to our repetoire can greatly enhance our understanding of what POV-Ray is capable of. Adventure awaits!
povray is the name of the program and it is followed by several switches. Each switch begins with a plus or minus sign. The +I switch with the filename 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. The +W and +H switches set the width and height of the image in pixels. This image will be 80 pixels wide by 60 pixels high.
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.
Switches may be specified in upper or lower case. They are read left to right but in general may be specified in any order. If you specify a switch more than once, the previous value is generally overwritten with the last specification. The only exception is the +L switch for setting library paths. Up to ten unique paths may be specified.
Almost all +/- switches have an equivalent option which can be used in an INI file which is described in the next section. A detailed description of each switch is given in the option reference section.
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:
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:
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...
For example the INI equivalent of the switch +Isimple.pov is...
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.
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:
When you specify the INI file you should follow it with the section label in brackets. For example...
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.
To set the environment variable under MS-DOS you might put the following line in your autoexec.bat file...
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.
The notation and terminology used is described in the tables below.
| Keyword=bool | turn Keyword on if bool equals true, yes, on or 1 and turn it off if it is any other value. |
| Keyword=true | do this option if true, yes, on or 1 is specified. |
| Keyword=false | do this option if false, no, off or 0 is specified. |
| Keyword=file | any 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. |
| n | any integer such as in +W320 |
| n.n | any float such as in Clock=3.45 |
| 0.n | any float < 1.0 even if it has no leading 0 |
| s | any string of text |
| x or y | any single character |
| path | any 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.
| Clock=n.n | Sets "clock" float identifier to n.n |
| +Kn.n | Same 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.
| Initial_Frame=n | Sets initial frame number to n |
| Final_Frame=n | Sets final frame number |
| Initial_Clock=n.n | Sets initial clock value |
| Final_Clock=n.n | Sets final clock value |
| +KFIn | Same as Initial_Frame=n |
| +KFFn | Same as Final_Frame=n |
| +KIn.n | Same as Initial_Clock=n.n |
| +KFn.n | Same 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.
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...
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".