Documentation Talk:Tutorial Section 2.2
Setting POV-Ray Options
POV-Ray was originally created as a command-line program for operating systems without graphical interfaces, dialog boxes and pull-down menus. Most versions of POV-Ray still use command-line switches to tell it what to do. This documentation assumes you are using the command-line version. If you are using Macintosh, MS-Windows or other GUI versions, there will be dialog boxes or menus which do the same thing. There is system-specific documentation for each system describing the specific commands.
There are two distinct ways of setting POV-Ray options (other than through the GUI interface, if applicable) : command line switches and INI file keywords. Both are explained in detail in the following sections.
Command Line Switches
Command line switches consist of a
+ (plus) or
- (minus) sign, followed by one or more alphabetic characters and
possibly a numeric value. Here is a typical command line with switches.
POVRAY +Isimple.pov +V +W80 +H60
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 is working. The
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
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.
- 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
Using INI Files
Note: although the term 'INI file' is used by POV-Ray, this was implemented before the widespread acceptance of Microsoft Windows, and while POV-Ray's INI files are almost identical to those of Windows, there are some minor differences (the foremost being that it is legal to have multiple instances of the same item in a section). INI files are used on all platform versions of POV-Ray, not just on the Windows platform.
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
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.
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
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
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
Library_Path=path options. Up to 25 unique paths may be
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
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
res.ini and skips all options until it finds
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.
If a file or path contains blanks the whole file and path specification has to be put in quotes. You may either use a double-quote oir a single-quote, but you have to use the same at the beginning and end. For example:
+I"my file.pov" +I'my file.pov' Input_File="my file.pov" Input_File='my file.pov'
By using either single or double quotes it is possible to specify files whose name or path contains either as part of the name. For example:
+I"file's.pov" +I'my "big" file.pov' Input_File="file's.pov" Input_File='my "big" file.pov'