Reference Section 1.3Documentation Talk
There are seven distinct text streams that POV-Ray uses for output. On some versions each stream is designated by a particular color. Text from these streams are displayed whenever it is appropriate so there is often an intermixing of the text. The distinction is only important if you choose to turn some of the streams off or to direct some of the streams to text files. On some systems you may be able to review the streams separately in their own scroll-back buffer.
Here is a description of each stream.
Banner: This stream displays the program's sign-on banner, copyright, contributor's list, and some help screens. It cannot be turned off or directed to a file because most of this text is displayed before any options or switches are read. Therefore you cannot use an option or switch to control it. There are switches which display the help screens. They are covered in section "Help Screen Switches".
Debug: This stream displays debugging messages. It was primarily designed for developers but this and other streams may also be used by the user to display messages from within their scene files. See section "Text Message Streams" for details on this feature. This stream may be turned off and/or directed to a text file.
Fatal: This stream displays fatal error messages. After displaying this text, POV-Ray will terminate. When the error is a scene parsing error, you may be shown several lines of scene text that leads up to the error. This stream may be turned off and/or directed to a text file.
Render: This stream displays information about what options you have specified to render the scene. It includes feedback on all of the major options such as scene name, resolution, animation settings, anti-aliasing and others. This stream may be turned off and/or directed to a text file.
Statistics: This stream displays statistics after a frame is rendered. It includes information about the number of rays traced, the length of time of the processing and other information. This stream may be turned off and/or directed to a text file.
Status: This stream displays one-line status messages that
explain what POV-Ray is doing at the moment. On some systems this stream is
displayed on a status line at the bottom of the screen. This stream cannot be
directed to a file because there is generally no need to. The text displayed
Verbose option or
+V switch is output to
this stream so that part of the status stream may be turned off.
Warning: This stream displays warning messages during the parsing of scene files and other warnings. Despite the warning, POV-Ray can continue to render the scene. You will be informed if POV-Ray has made any assumptions about your scene so that it can proceed. In general any time you see a warning, you should also assume that this means that future versions of POV-Ray will not allow the warned action. Therefore you should attempt to eliminate warning messages so your scene will be able to run in future versions of POV-Ray. This stream may be turned off and/or directed to a text file.
Console Text Output
|Turn console display of debug info text on/off|
|Turn console display of fatal error text on/off|
|Turn console display of render info text on/off|
|Turn console display of statistic text on/off|
|Turn console display of warning text on/off|
|Turn on/off all debug, fatal, render, statistic and warning text to console.|
You may suppress the output to the console of the debug, fatal, render,
statistic or warning text streams. For example the
Statistic_Console=off option or the
-GS switch can turn
off the statistic stream. Using
+GS you may
turn it on again. You may also turn all five of these streams on or off at
once using the
All_Console option or
Note: that these options take effect immediately when specified. Obviously any error or warning messages that might occur before the option is read are not be affected.
Directing Text Streams to Files
|Echo debug info text to DEBUG.OUT|
||Turn off file output of debug info|
||Echo debug info text to file|
|Echo fatal text to FATAL.OUT|
||Turn off file output of fatal|
||Echo fatal info text to file|
|Echo render info text to RENDER.OUT|
||Turn off file output of render info|
||Echo render info text to file|
|Echo statistic text to STATS.OUT|
||Turn off file output of statistics|
||Echo statistic text to file|
|Echo warning info text to WARNING.OUT|
||Turn off file output of warning info|
||Echo warning info text to file|
|Echo all debug, fatal, render, statistic, and warning text to ALLTEXT.OUT|
||Turn off file output of all debug, fatal, render, statistic, and warning text.|
||Echo all debug, fatal, render, statistic, and warning text to file|
You may direct a copy of the text streams to a text file for the debug,
fatal, render, statistic, or warning text streams. For example the
Statistic_File=s option or the
switch. If the string s is
true or any of the other
true strings then that stream is redirected to a file with
a default name. Valid
true values are
1. If the value is
false the direction to a text file is turned off. Valid
false values are
0. Any other string specified turns on file output
and the string is interpreted as the output file name.
Similarly you may specify such a true, false or file name string after a
switch such as
+GSfile. You may also direct all five
streams to the same file using the
All_File option or
+GA switch. You may not specify the same file for two or more streams
because POV-Ray will fail when it tries to open or close the same file
Note: that these options take effect immediately when specified. Obviously any error or warning messages that might occur before the option is read will not be affected.
|Allows you to turn off classes of warnings.|
Level 0 turns off all warnings. Level 5 turns off all language version related warnings. The default is level 10 and it enables all warnings. All other levels are reserved and should not be specified.
Help Screen Switches
|Show help screen 0 if this is the only switch|
Note: there are no INI style equivalents to these options.
After displaying the help screens, POV-Ray terminates. Because
some operating systems do not permit a question mark as a command line switch
you may also use the
Note: this switch is
also used to specify the height of the image in pixels. Therefore the
+H switch is only interpreted as a help switch if it is the only
switch on the command line.
Graphical interface versions of POV-Ray such as Mac or Windows have extensive online help.
There is more than one way to trace a ray. Sometimes there is a trade-off between quality and speed. Sometimes options designed to make tracing faster can slow things down. This section covers options that tell POV-Ray how to trace rays with the appropriate speed and quality settings.
|Set quality value to n (0 <= n <= 11)|
Quality=n option or
switch allows you to specify the image rendering quality. You may choose to
lower the quality for test rendering and raise it for final renders. The
quality adjustments are made by eliminating some of the calculations that are
normally performed. For example settings below 4 do not render shadows.
Settings below 8 do not use reflection or refraction. The duplicate values
allow for future expansion. The values correspond to the following quality
||Just show quick colors. Use full ambient lighting only. Quick colors are used only at 5 or below.|
||Show specified diffuse and ambient light.|
||Render shadows, but no extended lights.|
||Render shadows, including extended lights.|
||Compute texture patterns, compute photons|
||Compute reflected, refracted, and transmitted rays.|
||Compute media and radiosity|
The default is 9 if not specified.
Automatic Bounding Control
|Turn bounding on/off|
|Turn bounding on; Set threshold to 25 or previous amount|
|Turn bounding off|
|Set bound threshold to n|
||Turn bounding on; bound threshold to n|
||Turn bounding off; set future threshold to n|
|Turn light buffer on/off|
|Turn light buffer on|
|Turn light buffer off|
|Turn vista buffer on/off|
|Turn vista buffer on|
|Turn vista buffer off|
POV-Ray uses a variety of spatial sub-division systems to speed up
ray-object intersection tests. The primary system uses a hierarchy of nested
bounding boxes. This system compartmentalizes all finite objects in a scene
into invisible rectangular boxes that are arranged in a tree-like hierarchy.
Before testing the objects within the bounding boxes the tree is descended
and only those objects are tested whose bounds are hit by a ray. This can
greatly improve rendering speed. However for scenes with only a few objects
the overhead of using a bounding system is not worth the effort. The
Bounding=off option or
-MB switch allows you to force
bounding off. The default value is on.
+MBn switch allows you to set the minimum number of objects
necessary before bounding is used. The default is
means that if your scene has fewer than 25 objects POV-Ray will automatically
turn bounding off because the overhead is not worth it. Generally it is
a good idea to use a much lower threshold like
Additionally POV-Ray uses systems known as vista buffers and light buffers to further speed things up. These systems only work when bounding is on and when there are a sufficient number of objects to meet the bounding threshold. The vista buffer is created by projecting the bounding box hierarchy onto the screen and determining the rectangular areas that are covered by each of the elements in the hierarchy. Only those objects whose rectangles enclose a given pixel are tested by the primary viewing ray. The vista buffer can only be used with perspective and orthographic cameras because they rely on a fixed viewpoint and a reasonable projection (i. e. straight lines have to stay straight lines after the projection).
The light buffer is created by enclosing each light source in an imaginary box and projecting the bounding box hierarchy onto each of its six sides. Since this relies on a fixed light source, light buffers will not be used for area lights.
Reflected and transmitted rays do not take advantage of the light and vista buffer.
The default settings are
+UL. The option to turn
these features off is available to demonstrate their usefulness and as
protection against unforeseen bugs which might exist in any of these bounding
In general, any finite object and many types of CSG of finite objects will properly respond to this bounding system. In addition blobs and meshes use an additional internal bounding system. These systems are not affected by the above switch. They can be switched off using the appropriate syntax in the scene file (see "Blob" and "Mesh" for details).
Text objects are split into individual letters that are bounded using the bounding box hierarchy. Some CSG combinations of finite and infinite objects are also automatically bound. The end result is that you will rarely need to add manual bounding objects as was necessary in earlier versions of POV-Ray unless you use many infinite objects.
Removing User Bounding
|Turn unnecessary bounds removal on/off|
|Turn unnecessary bounds removal on|
|Turn unnecessary bounds removal off|
|Turn split bounded unions on/off|
|Turn split bounded unions on|
|Turn split bounded unions off|
Early versions of POV-Ray had no system of automatic bounding or spatial
sub-division to speed up ray-object intersection tests. Users had to manually
create bounding boxes to speed up the rendering. Since version 3.0, POV-Ray
has had more sophisticated automatic bounding than any previous version. In
many cases the manual bounding on older scenes is slower than the new
automatic systems. Therefore POV-Ray removes manual bounding when it knows it
will help. In rare instances you may want to keep manual bounding. Some older
scenes incorrectly used bounding when they should have used clipping. If
POV-Ray removes the bounds in these scenes the image will not look right. To
turn off the automatic removal of manual bounds you should specify
Remove_Bounds=off or use
-UR. The default is
One area where the jury is still out is the splitting of manually bounded
unions. Unbounded unions are always split into their component parts so that
automatic bounding works better. Most users do not bound unions because they
know that doing so is usually slower. If you do manually bound a union we
presume you really want it bound. For safety sake we do not presume to remove
such bounds. If you want to remove manual bounds from unions you should
Split_Unions=on or use
+SU. The default is
|Turns anti-aliasing on/off|
|Turns aa on with threshold 0.3 or previous amount|
|Turns anti-aliasing off|
|Sets aa-sampling method (only
|Sets anti-aliasing threshold|
||Sets aa on with aa-threshold at n.n|
||Sets aa off (aa-threshold n.n in future)|
|Sets aa-jitter on/off|
|Sets aa-jitter on with 1.0 or previous amount|
|Sets aa-jitter off|
|Sets aa-jitter amount to n.n. If n.n <= 0 aa-jitter is set off|
||Sets aa-jitter on; jitter amount to n.n. If n.n <= 0 aa-jitter is set off|
||Sets aa-jitter off (jitter amount n.n in future)|
|Sets aa-depth (1 <= n <= 9)|
The ray-tracing process is in effect a discrete, digital sampling of the image with typically one sample per pixel. Such sampling can introduce a variety of errors. This includes a jagged, stair-step appearance in sloping or curved lines, a broken look for thin lines, moiré patterns of interference and lost detail or missing objects, which are so small they reside between adjacent pixels. The effect that is responsible for those errors is called aliasing.
Anti-aliasing is any technique used to help eliminate such errors or to
reduce the negative impact they have on the image. In general, anti-aliasing
makes the ray-traced image look smoother. The
Antialias=on option or
+A switch turns on POV-Ray's
When anti-aliasing is turned on, POV-Ray attempts to reduce the errors by shooting more than one viewing ray into each pixel and averaging the results to determine the pixel's apparent color. This technique is called super-sampling and can improve the appearance of the final image but it drastically increases the time required to render a scene since many more calculations have to be done.
POV-Ray gives you the option to use one of two alternate super-sampling
Sampling_Method=n option or
+AMn switch selects either type
1 or type
2. Selecting one of those methods does not turn anti-aliasing on. This
has to be done by using the
+A command line switch or
Type 1 is an adaptive, non-recursive, super-sampling method. It is adaptive because not every pixel is super-sampled. Type 2 is an adaptive and recursive super-sampling method. It is recursive because the pixel is sub-divided and sub-sub-divided recursively. The adaptive nature of type 2 is the variable depth of recursion.
In the default, non-recursive method (
+AM1), POV-Ray initially
traces one ray per pixel. If the color of a pixel differs from its neighbors
(to the left or above) by at least the set threshold value then the pixel is
super-sampled by shooting a given, fixed number of additional rays. The
default threshold is 0.3 but it may be changed using the
Antialias_Threshold=n.n option. When the switches are used,
the threshold may optionally follow the
+A. For example
+A0.1 turns anti-aliasing on and sets the threshold to 0.1.
The threshold comparison is computed as follows. If r1, g1, b1 and r2, g2, b2 are the rgb components of two pixels then the difference between pixels is computed by
diff = abs(r1-r2) + abs(g1-g2) + abs(b1-b2)
If this difference is greater than the threshold then both pixels are super-sampled. The rgb values are in the range from 0.0 to 1.0 thus the most two pixels can differ is 3.0. If the anti-aliasing threshold is 0.0 then every pixel is super-sampled. If the threshold is 3.0 then no anti-aliasing is done. Lower threshold means more anti-aliasing and less speed. Use anti-aliasing for your final version of a picture, not the rough draft. The lower the contrast, the lower the threshold should be. Higher contrast pictures can get away with higher tolerance values. Good values seem to be around 0.2 to 0.4.
When using the non-recursive method, the default number of super-samples is
nine per pixel, located on a 3*3 grid. The
Antialias_Depth=n option or
controls the number of rows and columns of samples taken for a super-sampled
pixel. For example
+R4 would give 4*4=16 samples per pixel.
The second, adaptive, recursive super-sampling method starts by tracing four rays at the corners of each pixel. If the resulting colors differ more than the threshold amount additional samples will be taken. This is done recursively, i.e. the pixel is divided into four sub-pixels that are separately traced and tested for further subdivision. The advantage of this method is the reduced number of rays that have to be traced. Samples that are common among adjacent pixels and sub-pixels are stored and reused to avoid re-tracing of rays. The recursive character of this method makes the super-sampling concentrate on those parts of the pixel that are more likely to need super-sampling (see figure below).
The maximum number of subdivisions is specified by the
Antialias_Depth=n option or
This is different from the adaptive, non-recursive method where the total
number of super-samples is specified. A maximum number of n
subdivisions results in a maximum number of samples per pixel that is given
by the following table.
||Number of additional samples per super-sampled pixel for the non-recursive method
||Maximum number of samples per super-sampled pixel for the recursive
Note: the maximum number of samples in the recursive case is hardly ever reached for a given pixel. If the recursive method is used with no anti-aliasing each pixel will be the average of the rays traced at its corners. In most cases a recursion level of three is sufficient.
Another way to reduce aliasing artefacts is to introduce noise into the
sampling process. This is called jittering and works because the
human visual system is much more forgiving to noise than it is to regular
patterns. The location of the super-samples is jittered or wiggled a tiny
amount when anti-aliasing is used. Jittering is used by default but it may be
turned off with the
Jitter=off option or
The amount of jittering can be set with the
Jitter_Amount=n.n option. When using switches the jitter
scale may be specified after the
+Jn.n switch. For
+J0.5 uses half the normal jitter. The default amount of
1.0 is the maximum jitter which will insure that all super-samples remain
inside the original pixel.
Note: the jittering noise is random and non-repeatable so you should avoid using jitter in animation sequences as the anti-aliased pixels will vary and flicker annoyingly from frame to frame.
If anti-aliasing is not used one sample per pixel is taken regardless of the super-sampling method specified.
Statistic_File changes in beta?
Has the Statistic_File option changed in beta? In 3.6 I have it set to a custom file path, but in 3.7 it says "Cannot open file." SharkD 00:57, 22 June 2010 (UTC)
- The Documentation_Talk namespace is usually reserved for offering corrections to the current documentation set(s) to make it ready for v3.7 not for asking questions. I followed up to your post about this matter in the appropriate news sever group --jholsenback 10:12, 22 June 2010 (UTC)
- In Tracing options, please consider adding a section for Render_Pattern and one for Render_Step
POV-Ray provides a mechanism to specify the order of render block via either an INI-style option Render_Pattern=n or on the command-line +RPn, where n is an integer between 0 and 5. This represents the various orders for the distribution of the blocks to to the render threads. The default value is 0. If you specify a value that is greater than the maximum number of pattern, it reverts to the default. Using a different Render_Pattern has only an effect on the preview of the rendered image, as the first blocks might be placed differently, but does not change the final picture once the render has been completed.
Pattern 2: The top row is processed first, starting at each corner and meeting at the center of the row, then the bottom row is processed the same way. The last block is at the very center of the image.
Render Block Step
Whatever the chosen pattern (with +RP), the number of the next processed block can be incremented by more than 1, to jumps over blocks, via either an INI-style option Render_Block_Step=n or on the command-line +RSn, where n is a positive non zero integer. The provided value n get reduced automatically to a smaller value if the provided value would lead to a situation where the some blocks would not get rendered.
Assuming a picture made of 40 blocks, with +RS9, the order of block numbers would be: 0, 9, 18, 27, 36, 5, 14, 23, 32, 1, 10, 19, 28, 37, 6, 15, 24, 33, 2, 11, 20, 29, 38, 7, 16, 25, 34, 3, 12, 21, 30, 39, 8, 17, 26, 35, 4, 13, 22, 31.
The same 40 blocks with +RS8 would in fact uses +RS7 instead. As would a +RS2 in fact be reduced to +RS1 (the default).
- both the above sub-sections have been added starting here: --jholsenback 16:48, 11 November 2010 (UTC)
- Apparently I get the depth of header wrong (Render Pattern & Render Block Step) should be a level higher (to match Render Block Size)--Le Forgeron 18:23, 12 November 2010 (UTC)
- Nope I adjusted it, as all those attributes seemed to be related enough to group together. Size, Pattern, Step seems like the appropriate progression. --jholsenback 10:59, 13 November 2010 (UTC)