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.

A: Controls anti-aliasing (edge smoothing) of the image
B: Controls the size of the output buffer
C: Used to continue a incomplete render of an image
D: Controls display of the image during rendering
E or ER: Sets the ending row for partial renders
EC: Sets the ending column for partial renders
F: Sets to format of the output image
H: Specifies the height of the image (in pixels)
I: Specifies the name of the scene file being rendered
J: Controls jitter during anti-aliasing
K: Specifies a value for the clock variable
L: Specify a path to search for files in
MB: Controls POV-Ray's use of automatic bounding
MS: Controls the size of POV-Ray's internal symbol table
MV: Used to modify the default value of the version parameter
O: Specifies a filename to render the scene to
P: Controls whether POV-Ray waits for a keypress after rendering
Q: Controls the rendering quality
R: Controls the number of extra rays used for anti-aliasing
S or SR: Sets the starting row for partial renders
SC: Sets the starting column for partial renders
V: Controls the display of verbose statistics while rendering
W: Specifies the width of the output image (in pixels)
X: Controls whether or not POV-Ray can be interrupted once started (only available in certain versions)

A: anti-aliasing

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 every pixel.

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

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.

J: jitter

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.

K: clock

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

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 as well.

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 an image.

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.

+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.
+Q4: Enables shadow calculations.
+Q5: 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).

The following images are of the same scene, rendered at quality settings 1, 3, 5, 7, and 9, respectively.

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.

V: verbose

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.

Reference Index