The Online POV-Ray Tutorial
Command Line Parameter Reference
This section covers the various command-line parameters which POV-Ray will
accept. POV-Ray checks command line parameters in a non-case-sensitive
fashion. This means, for example, that +a is the same as +A.
Some options are toggles, some are specifiers. With the toggles, specifying
a "+" before the letter turns the option on, while specifying a "-" before it
will turn it off. Examples of toggles are A, J, and MB. With specifiers,
a value for a parameter is specified. Here, either "+" or "-" can be used
before the letter. The argument for the specifier follows the parameter
without a space. "-Ifoo.pov" for example.
Any command line parameter which is not preceded by a "+" or a "-" is assumed
to be the name of a command file from which further options will be read.
Valid command line parameters are listed below.
- Controls anti-aliasing (edge smoothing) of the image
- Controls the size of the output buffer
- Used to continue a incomplete render of an image
- Controls display of the image during rendering
- E or ER
- Sets the ending row for partial renders
- Sets the ending column for partial renders
- Sets to format of the output image
- Specifies the height of the image (in pixels)
- Specifies the name of the scene file being rendered
- Controls jitter during anti-aliasing
- Specifies a value for the clock variable
- Specify a path to search for files in
- Controls POV-Ray's use of automatic bounding
- Controls the size of POV-Ray's internal symbol table
- Used to modify the default value of the version parameter
- Specifies a filename to render the scene to
- Controls whether POV-Ray waits for a keypress after rendering
- Controls the rendering quality
- Controls the number of extra rays used for anti-aliasing
- S or SR
- Sets the starting row for partial renders
- Sets the starting column for partial renders
- Controls the display of verbose statistics while rendering
- Specifies the width of the output image (in pixels)
- Controls whether or not POV-Ray can be interrupted once started (only available in certain versions)
The "A" parameter is a toggle that controls anti-aliasing of the rendered
image. "+A" turns on anti-aliasing, "-A" turns it off. The default is "-A".
Anti-aliasing works by determining how different two adjacent pixels are,
and if they are too different, POV-Ray shoots extra rays into the scene
(it supersamples the pixel) and colors the pixel with the averaged value.
Note that because anti-aliasing requires extra rays to be traced, it
drastically increases the amount of time to render the scene. It's not
uncommon for anti-aliasing to double or triple the rendering time of a scene.
Thus, it's a good idea to only use this option for final images, or right
before you go to bed for the night.
The following scenes and zoom-ins should should make anti-aliasing more clear.
The first has no anti-aliasing, the second was rendered with "+A -J".
The "distance" between two colors is determined by summing the absolute values
of the differences of each color component (phew!). For example, if you
have two colors <0.2, 0.6, 0.8> and <0.3, 0.3, 0.9>, the difference
will be 0.5 (0.1 + 0.3 + 0.1). If the distance between two colors is greater
than the threshold (0.3 by default), then the pixels will be anti-aliased.
This threshold can be changed by specifying a float with the "+A". For example,
"+A1.5" will only anti-alias if the distance between two colors is greater
than 1.5. The maximum threshold is 3.0, which effectively turns off
anti-aliasing. Setting the threshold to 0.0 will make POV-Ray anti-alias
The number of rays used to supersample a pixel can be controlled with the
R parameter. You can introduce a random jitter into
the supersampling rays with the J parameter.
B: buffer size
The value of this parameter controls how many pixels POV-Ray should calculate
between disk writes. By default, POV-Ray will write to the disk after every
line is calculated. The POV-Ray authors recommend +B30 as a good value
for speeding up small renders. Note that "-B" cannot be used to turn off
the output buffer.
C: continue interrupted render
This is a toggle which can be used to get POV-Ray to continue work on a
partially completed render. This is useful for when you have a trace which
is taking a particularly long time to render, and you need to do something
else with the computer for a while. You can interrupt the trace
(see the X parameter), do what you need to do, and then
restart with "+C". The default value of this toggle is "-C" (start anew).
D: display image
The D parameter controls whether or not POV-Ray displays the image as it
renders it. The parameter for D is system dependent, and display-while-render
is not supported across all platforms. There should be system specific
documentation with POV-Ray that details this parameter for your particular
E: ending row
The E and ER parameters are used to tell POV-Ray to stop tracing after
a certain row. E and ER are functionally equivalent. If their parameter
is an integer, it specifies the row number on which to stop. If it is
a float, it specifies a fraction of the image to render. This is useful
for debugging a scene when you are only interested in a part of it. For example,
if your image is 256 pixels high (see the H parameter),
"+E192" and "+E0.75" will have the same effect. This is useful in concert
with some or all of S, SC, and EC
to render a rectangular portion of an image.
EC: ending column
The EC parameter is used set the ending column for a partial image render.
If the value for the parameter is an integer, POV-Ray interprets it to be
the absolute number of the stopping column. If the value is a number
betweem 0.0 and 1.0, POV-Ray interprets it to be a fraction the image
width. For example, if your image is 256 pixels wide,
"-EC160" and "-EC0.625" have the same effect. This parameter can be used
in concert with E, S, and SC
to specify a rectangular region of the image to render.
F: output file type
The F parameter is used to control the file output format. Three file
output types are supported, Truevision Targas, Dumps, and raw data output.
These can be specified using the "+FT", "+FD", and "+FR". Of these,
the Targas are probably the most useful and widely supported. You can
disable file output by specifying "-F". It's a good idea to have F or
D enabled (or both), otherwise you'll just spend a lot
of time doing nothing.
H: image height
The H parameter is used to specify the height of the output image in
pixels. If not specified, it will default to 100. This parameter can
take any value between 1 and 32,767 (inclusive). For example, specifying
"-H768" will render an image that is 768 pixels high. To avoid weird
distortion effects, it's a good idea to have the ratio of H and
W be the same as the ratio of the up
and right vectors in the camera.
I: input file
The I parameter is used to specify the file from which POV-Ray will read
the scene description. By convention, input files have the extension
".pov", but this is not required. If no I parameter is specified, POV-Ray
will try to read from "object.pov". If you wanted to render the file
"shmoo.pov", you would specify "-Ishmoo.pov". As this parameter is not a
toggle, both "+" and "-" work equally well in specifying it.
The J toggle controls the use of jitter when anti-aliasing
an image. When "+J" is specified (this is the default when +A is given),
POV-Ray will randomly perturb the extra rays it uses to do the anti-aliasing.
This serves to break up edges and prevent annoying moire patterns along
anti-aliased edges. J can also take a parameter between 0.0 and 1.0 which
controls how much jittering will be done. The default is 1.0. Values
greater than 1.0 aren't recommended because they cause supersampling rays
to be jittered outside the pixel.
The first image below was anti-aliased without jittering, the second, with.
Although it's difficult to tell the difference, you'll notice that the zoom-in
on the second image is a bit different from the zoom-in of the first.
To set the jitter to something lower, you could try "+J0.5". "-J" will
turn off pixel jittering.
The K parameter is used to specify a value for the clock
variable. This is useful for creating simple animations, but won't help
too much with more complex stuff. It takes any floating point number as
a parameter. If not specified, the value of the clock variable will be zero.
For example, to set the value of the clock variable to "3.14159", you would
give the parameter "+K3.14159".
L: library paths
The L parameter is used to specify search paths for the various features
of POV-Ray. When searching for an external file, POV-Ray will first look
in the current directory, and then any directories given with the L
parameter. You can use this to specify up to ten different search directories.
These search directories are used for including files,
or for images used in height fields,
image maps, bump
maps, and material maps. For example,
you had your include files in the subdirectory "include" and your image maps
in a subdirectory "images", you could tell POV-Ray to search those two directories
when appropriate by giving the parameters "-Linclude -Limages".
MB: control automatic bounding
This parameter is used to control POV-Ray's use of things called bounding
slabs. When a scene reaches a predetermined complexity (defined by the
number of objects in the scene), POV-Ray will divide them up and group them
with these bounding slabs. These are very efficient bounding
objects, and can speed a render greatly. However, for scenes which aren't
very complex, the overhead involved in computing the slabs outweights any
benefits. The value of the MB parameter is used to set the object threshold
for the use of bounding slabs. By default it is 25, and this is a good
limit. If you wanted to turn the threshold up to 50, you would issue the
parameter "+MB50". "-MB" will turn off the use of bounding slabs.
MS: control symbol table size
This parameter is used to control the size of POV-Ray's internal symbol table.
Space in this table is allocated for everything that is declared
in a scene file. Note that the standard include files tend to have a great
number of declared identifiers, and this can cause the symbol table
to fill up more quickly than you would expect. The default symbol table will
hold 1000 symbols. If you get a "Too many symbols" error message, you need to
either decrease the number of declares in your scene, or increase the size
of the symbol table (the latter being the easier of the two). To increase
the size of the symbol table to 2000 symbols, give the parameter "-MS2000".
"+MS2000" will work just as well.
MV: set version
The MV parameter is used to tell POV-Ray what version scene files it's reading.
Two values can be specified for this parameter, 1.0 and 2.0. The default
is 2.0, which is the syntax covered in this tutorial. However, if you want
to render a scene which uses v1.0 syntax, you can use this parameter to get
POV-Ray to recognize it. Note that there have been some changes to the
language which will not be fixed with this parameter. Inside the scene file
you can change the version with the #version
O: set output filename
The O parameter is used to tell POV-Ray what file to output to when
file output is enabled. If not specified, it will default
to "-Odata.tga". If the file you specify already exists, it will be
overwritten. If, for example, you wanted to send the output to "shmoo.tga",
you would give the parameter "-Oshmoo.tga". "+Oshmoo.tga" will work just
P: wait for keypress
The P parameter is a toggle which tells POV-Ray whether or not to wait for
a keypress after it's done rendering. The default value is "-P" (don't
wait for keypress). "+P" is useful for pausing when you're displaying
Q: set rendering quality
The Q parameter is used to tell POV-Ray what quality you want to render the
image at. The default value is 9 (highest) quality. Rendering lower quality
images is useful for debugging a scene. Lower quality settings will
disable mroe and more features, resulting a quicker and quicker and render.
This parameter can take a value from 0 (low quality, quick render) to 9
(high quality, not-as-quick render). The following list summarizes the
effects of the different quality settings.
The following images are of the same scene, rendered at quality settings 1,
3, 5, 7, and 9, respectively.
- +Q0, +Q1
- Use quick colors (or gray scale) to
color objects. Ambient light only. No shadows, no shading, no reflections,
no transmission, no refraction, and area lights are rendered as point lights.
- +Q2, +Q3
- Enables diffuse lighting and shading of objects.
- Enables shadow calculations.
- Enables area lights.
- +Q6, +Q7
- Stops using quick colors, and instead
colors objects based on their assigned textures.
- +Q8, +Q9
- Enables reflection and transparency calculations (including refraction).
R: number of supersampling rays
The R parameter is used to control how many rays POV-Ray will supersample
with when it is anti-aliasing. The default value is
3, which means that POV-Ray will use a 3x3 grid of rays. Giving the parameter
"+R5" will tell POV-Ray to use a 5x5 grid. Normally, the default value is
sufficient to make a scene look nice. You shouldn't need to use high values
of R. Note that since the number of extra rays increases with the square of
this number, setting it much beyond 5 or 6 is a bad idea unless you're
going on vacation for a week.
The following two images show the difference between "+R3" (default) and "+R5",
respectively, when anti-aliasing. Although the two zoomed-in images don't look to different,
the second normal size image has softer, better looking edges. These softer edges
are even more apparent when the image is still in 24-bit color (as opposed to the
8-bits supported by .GIFs).
S: starting row
The S or SR parameter is used to specify a starting row for a partial image
render. If the value given for this parameter is an integer, POV-Ray assumes
you're giving a line number, and will start rendering at the specified row.
If the value is instead between 0.0 and 1.0, POV-Ray interprets it as
a fraction of the image height. For example, if your image is
256 pixels high, then the arguments "-S64" and "-S0.25"
will have the same effect. Note that "+S" will work just as well in both
these cases. This parameter is useful in conjunction with E,
SC, and EC for specifying a rectangular
portion of the image to render.
SC: starting column
The SC parameter is used to specify the starting column for partial image
renders. If the value given for this parameter is an integer, it is assumed
to be the absolute column number on which to begin. If it is a number
betweem 0.0 and 1.0, it is interpreted to be a fraction of the total
image width. For example, if your image is 256 pixels
wide, then "-SC32" and "-SC0.125" are the same. This parameter is useful
to use with S, E, and EC
to render a rectangular portion of an image.
The V parameter allows you to control the verbose reporting of statistics
while rendering. This is only useful when you aren't displaying
the image. "+V" gives a report of how much of the image has rendered,
while "-V" turns that reporing off. The default value is "-V".
W: image width
The W parameter is used to specify the width of the rendered image. If you
don't specify a width, it will default to 100 pixels. The image
width can be anywhere from 1 to 32,767 pixels. As an example, to set the
width of the image to 1024 pixels, you would give "-W1024". "+W1024" will
work just as well. To avoid weird image distortion, it's a good idea to
make the ratio between the W and H values the same as the
ratio between the right and up
vectors in the camera.
X: allow interrupt
In certain versions (the DOS version, for example) the "+X" option will allow you
to halt the rendering by hitting a key. "-X" will make it so that the only
way to stop the trace is to reboot the computer. "-X" is useful for when
you're starting a long trace and you don't want anyone to accidently
stop it. If you do stop an trace (when in +X mode), you can restart it later
with the C option.