Difference between revisions of "Documentation Talk:Reference Section 1.1"

From POV-Wiki
Jump to navigation Jump to search
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
===Interrupting Options===
 +
<!--<indexentry "Options, interruption">--->
 +
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Test_Abort=</code>bool<!--<indexentry primary "Test_Abort, ini-option"></td>--->
 +
 +
<td width="70%">Turn test for user abort on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+X</code><!--<indexentry "+x"></td>--->
 +
 +
<td>Turn test abort on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-X</code><!--<indexentry "-x"></td>--->
 +
 +
<td>Turn test abort off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Test_Abort_Count=</code>n<!--<indexentry primary "Test_Abort_Count, ini-option"></td>--->
 +
 +
<td>Set to test for abort every n pixels</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+X</code>n</td>
 +
 +
<td>Set to test for abort every n pixels on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-X</code>n</td>
 +
 +
<td>Set to test for abort off (in future test every n pixels)</td>
 +
</tr>
 +
</table>
 +
 +
<p>On some operating systems once you start a rendering you must let it
 +
finish. The <code>Test_Abort=on</code> option or <code>+X</code> switch
 +
causes POV-Ray to test the keyboard for keypress. If you have pressed a key,
 +
it will generate a controlled user abort. Files will be flushed and closed
 +
but only data through the last full row of pixels is saved. POV-Ray exits
 +
with an error code 2 (normally POV-Ray returns 0 for a successful run or 1
 +
for a fatal error).</p>
 +
<p>
 +
When this option is on, the keyboard is polled on every line while parsing
 +
the scene file and on every pixel while rendering. Because polling the
 +
keyboard can slow down a rendering, the <code>
 +
Test_Abort_Count=</code><em>n</em> option or <code>+X</code><em>n</em> switch
 +
causes the test to be performed only every <em>n</em> pixels rendered or
 +
scene lines parsed.</p>
 +
===Resuming Options===
 +
<!--<indexentry "Options, resuming">--->
 +
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Continue_Trace=</code>bool<!--<indexentry primary "Continue_Trace, ini-option"></td>--->
 +
 +
<td width="70%">Sets continued trace on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+C</code><!--<indexentry "+c"></td>--->
 +
 +
<td>Sets continued trace on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-C</code><!--<indexentry "-c"></td>--->
 +
 +
<td>Sets continued trace off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Create_Ini=</code>file<!--<indexentry primary "Create_Ini, ini-option"></td>--->
 +
 +
<td>Generate an INI file to file</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Create_Ini=</code>true</td>
 +
 +
<td>Generate file.ini where file is scene name.</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Create_Ini=</code>false</td>
 +
 +
<td>Turn off generation of previously set file.ini</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+GI</code>file<!--<indexentry "+gi"></td>--->
 +
 +
<td>Same as <code>Create_Ini=</code>file</td>
 +
</tr>
 +
</table>
 +
 +
<p>If you abort a render while it is in progress or if you used the
 +
<code><!--<linkto "End_Row">End_Row</linkto>--->[[Documentation:Reference Section 1#Partial Output Options|End_Row]]</code> option to end the render prematurely, you can use
 +
<code>Continue_Trace=on</code> or <code>+C</code> option to continue the render
 +
later at the point where you left off. This option reads in the previously
 +
generated output file, displays the partial image rendered so far, then
 +
proceeds with the ray-tracing. This option cannot be used if file output is
 +
disabled with <code><!--<linkto "Output_to_file">Output_to_file</linkto>--->[[Documentation:Reference Section 1.1#File Output Options|Output_to_file]]=off</code>
 +
or <code>-F</code>.</p>
 +
<p>
 +
The <code>Continue_Trace</code> option may not work if the <code>Start_Row</code>
 +
option has been set to anything but the top of the file, depending on the output format being used. Also POV-Ray cannot continue the file once it has been opened and saved again by any program</p>
 +
<p>
 +
POV-Ray tries to figure out where to resume an interrupted trace by reading
 +
any previously generated data in the specified output file. All file formats
 +
contain the image size, so this will override any image size settings
 +
specified. Some file formats (namely TGA and PNG) also store information
 +
about where the file started (i. e. <code> +SC</code><em>n</em> and <code>
 +
+SR</code><em>n</em> options), alpha output <code>+UA</code>, and bit-depth
 +
<code>+FN</code><em>n</em>, which will override these settings. It is up to
 +
the user to make sure that all other options are set the same as the original
 +
render.</p>
 +
<p>
 +
The <code>Create_Ini</code> option or <code>+GI</code> switch provides an
 +
easy way to create an INI file with all of the rendering options, so you can
 +
re-run files with the same options, or ensure you have all the same options
 +
when resuming. This option creates an INI file with every option set at the
 +
value used for that rendering. This includes default values which you have
 +
not specified. For example if you run POV-Ray with...</p>
 +
<pre>
 +
POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS
 +
</pre>
 +
 +
<p>POV-Ray will create a file called <code>rerun.ini</code> with all of the
 +
options used to generate this scene. The file is not written until all
 +
options have been processed. This means that in the above example, the file
 +
will include options from both <code>myopts.ini</code> and <code>
 +
moreopts.ini</code> despite the fact that the <code>+GI</code> switch is
 +
specified between them. You may now re-run the scene with...</p>
 +
<pre>
 +
POVRAY RERUN
 +
</pre>
 +
 +
<p>or resume an interrupted trace with</p>
 +
<pre>
 +
POVRAY RERUN +C
 +
</pre>
 +
 +
<p>If you add other switches with the <code>rerun.ini</code> reference, they
 +
will be included in future re-runs because the file is re-written every time
 +
you use it.</p>
 +
<p>
 +
The <code>Create_Ini</code> option is also useful for documenting how a
 +
scene was rendered. If you render <code> waycool.pov</code> with <code>
 +
Create_Ini=on</code> then it will create a file <code>waycool.ini</code> that
 +
you could distribute along with your scene file so other users can exactly
 +
re-create your image.</p>
 +
 +
===Display Output Options===
 +
<!--<indexentry "Options, display">--->
 +
===Display Hardware Settings===
 +
<!--<indexentry "Options, display">--->
 +
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Display=</code>bool<!--<indexentry primary "Display, ini-option"></td>--->
 +
 +
<td width="70%">Turns graphic display on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+D</code><!--<indexentry "+d"></td>--->
 +
 +
<td>Turns graphic display on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-D</code><!--<indexentry "-d"></td>--->
 +
 +
<td>Turns graphic display off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Video_Mode=</code>x<!--<indexentry primary "Video_Mode, ini-option"></td>--->
 +
 +
<td>Set video mode to x; does not affect on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+D</code>x</td>
 +
 +
<td>Set display on; Set mode to x</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-D</code>x</td>
 +
 +
<td>Set display off; but for future use mode x</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Palette=</code>y<!--<indexentry primary "Palette, ini-option"></td>--->
 +
 +
<td>Set display palette to y; does not affect on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+D</code>xy</td>
 +
 +
<td>Set display on; Set mode x; Set palette y</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-D</code>xy</td>
 +
 +
<td>Set display off; use mode x, palette y in future</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Display_Gamma=</code>n.n<!--<indexentry primary "Display_Gamma"><indexentry primary "Display_Gamma, ini-option"></td>--->
 +
 +
<td>Sets the display gamma to n.n</td>
 +
</tr>
 +
</table>
 +
 +
<p>The <code>Display=on</code> or <code>+D</code> switch will turn on the
 +
graphics display of the image while it is being rendered. Even on some
 +
non-graphics systems, POV-Ray may display an 80 by 24 character <em>
 +
&quot;ASCII-Art&quot;</em> version of your image. Where available, the
 +
display may be full, 24-bit true color. Setting <code>Display=off</code> or
 +
using the <code>-D</code> switch will turn off the graphics display which is
 +
the default.</p>
 +
<p>On the Windows platform, the default is <code>Display=on</code>. Turning
 +
display off does not, of course, turn off the actual video display. Instead,
 +
POV-Ray will not open the output window that it normally shows a render in.</p>
 +
<p>The <code>Video_Mode=</code><em>x</em> option sets the display mode or
 +
hardware type chosen where <em>x</em> is a single digit or letter that is
 +
machine dependent. Generally <code>Video_Mode=0</code> means the default or
 +
an auto-detected setting should be used. When using switches, this character
 +
immediately follows the switch. For example the <code>+D0</code> switch will
 +
turn on the graphics display in the default mode.</p>
 +
<p>
 +
The <code> Palette=</code><em>y</em> option selects the palette to be used.
 +
Typically the single character parameter <em>y</em> is a digit which selects
 +
one of several fixed palettes or a letter such <code>G</code> for gray scale,
 +
<code> H</code> for 15-bit or 16-bit high color or <code> T</code> for 24-bit
 +
true color. When using switches, this character is the 2nd character after
 +
the switch. For example the <code>+D0T</code> switch will turn on the
 +
graphics display in the default mode with a true color palette. The <code>
 +
Display_Gamma=</code><em>n.n</em> setting is not
 +
available as a command-line switch.</p>
 +
<p>
 +
The <code> Display_Gamma</code> setting overcomes the problem of images
 +
(whether ray-traced or not) having different brightness when being displayed
 +
on different monitors, different video cards, and under different operating
 +
systems.</p>
 +
<p class="Note"><strong>Note:</strong> the <code>Display_Gamma</code> is a setting based on your
 +
computer's display hardware, and should be set correctly once and not
 +
changed.</p>
 +
<p> The <code> Display_Gamma</code> INI setting works in conjunction
 +
with the new <code> assumed_gamma</code> global setting to ensure that POV
 +
scenes and the images they create look the same on all systems. See section
 +
&quot;<!--<linkto "Assumed_Gamma">Assumed_Gamma</linkto>--->[[Documentation:Reference Section 3.1#Assumed_Gamma|Assumed_Gamma]]&quot; which describes the <code> assumed_gamma</code>
 +
global setting and describes gamma more thoroughly.</p>
 +
<p>
 +
While the <code> Display_Gamma</code> can be different for each system,
 +
there are a few general rules that can be used for setting <code>
 +
Display_Gamma</code> if you do not know it exactly. If the <code>
 +
Display_Gamma</code> keyword does not appear in the INI file, POV-Ray assumes
 +
that the display gamma is 2.2. This is because most PC monitors have a gamma
 +
value in the range 1.6 to 2.6 (newer models seem to have a lower gamma
 +
value). Mac has the ability to do gamma correction inside the system software
 +
(based on a user setting in the gamma control panel). If the gamma control
 +
panel is turned off, or is not available, the default Macintosh system gamma
 +
is 1.8. Many newer PC graphics cards can do hardware gamma correction and
 +
should use the current Display_Gamma setting, usually 1.0.</p>
 +
 +
===Setting your Display Gamma===
 +
<!--<indexentry "gamma, determining your display">--->
 +
<!--<indexentry "Display_Gamma, for your display">--->
 +
 +
<p>The following gamma test image can be used to help you set your <code>Display_Gamma</code>
 +
accurately.</p>
 +
 +
<p>Before viewing the gamma image darken the room and set the monitor
 +
brightness and contrast to maximum.  While viewing a black screen,
 +
lower the brightness gradually until the &quot;background&quot; is no longer
 +
noticeable (ie when it just fades from view).  This may be difficult
 +
on monitors that use overscanning, unless you change the viewable
 +
area settings.</p>
 +
 +
<!--<indexentry "gamma, test image">--->
 +
<p>[[Image:RefImgGamma.gif|Display gamma test image.]]</p>
 +
 +
<p>Now, lower the contrast until the alternating white and black bars
 +
on the left edge of each column are equal in width.  This is trying
 +
to get a 50% gray by using half white and half black.  If this is
 +
not possible, choose a contrast setting which is about in the middle.
 +
While viewing the image from a distance, or with squinted eyes, one
 +
of the numbered &quot;swatches&quot; will best match the gray value approximated
 +
by the white and black bars.  The number in this &quot;swatch&quot; is your
 +
display's actual gamma value.</p>
 +
 +
<p>Normal display gamma values are in the range 2.0 to 2.6.  If your
 +
monitor is usually used in a dim environment, we often use a gamma
 +
value that is 15% - 25% lower than the actual display gamma to give
 +
the images more contrast.  Some systems, such as Macs and SGIs, already
 +
do gamma correction, so they may have display gammas of 1.0 or 1.8.</p>
 +
 +
<p>For scene files that do not contain an <code>assumed_gamma</code> global
 +
setting the INI file option <code>Display_Gamma</code> will not have any
 +
affect on the preview output of POV-Ray or for most output file formats.
 +
However, the <code>Display_Gamma</code> value is used when creating PNG
 +
format output files, and also when rendering the POV-Ray example files
 +
(because they have an <code>assumed_gamma</code>), so it should still be
 +
correctly set for your system to ensure proper results.</p>
 +
===Display Related Settings===
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Pause_When_Done=</code>bool<!--<indexentry primary "Pause_When_Done, ini-option"></td>--->
 +
 +
<td width="70%">Sets pause when done on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+P</code><!--<indexentry "+p"></td>--->
 +
 +
<td>Sets pause when done on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-P</code><!--<indexentry "-p"></td>--->
 +
 +
<td>Sets pause when done off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Verbose=</code>bool<!--<indexentry primary "Verbose, ini-option"></td>--->
 +
 +
<td>Set verbose messages on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+V</code><!--<indexentry "+v"></td>--->
 +
 +
<td>Set verbose messages on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-V</code><!--<indexentry "-v"></td>--->
 +
 +
<td>Set verbose messages off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Draw_Vistas=</code>bool<!--<indexentry primary "Draw_Vistas, ini-option"></td>--->
 +
 +
<td>Turn draw vistas on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+UD</code><!--<indexentry "+ud"></td>--->
 +
 +
<td>Turn draw vistas on</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-UD</code><!--<indexentry "-ud"></td>--->
 +
 +
<td>Turn draw vistas off</td>
 +
</tr>
 +
</table>
 +
 +
<p>On some systems, when the image is complete, the graphics display is
 +
cleared and POV-Ray switches back into text mode to print the final
 +
statistics and to exit. Normally when the graphics display is on, you want to
 +
look at the image awhile before continuing. Using <code>Pause_When_Done=on</code>
 +
or <code>+P</code> causes POV-Ray to pause in  graphics mode until you press a key
 +
to continue. The default is not to pause (<code>-P</code>).</p>
 +
<p>
 +
When the graphics display is not used, it is often desirable to monitor
 +
progress of the rendering. Using <code> Verbose=on</code> or <code>+V</code>
 +
turns on verbose reporting of your rendering progress. This reports the
 +
number of the line currently being rendered, the elapsed time for the current
 +
frame and other information. On some systems, this textual information can
 +
conflict with the graphics display. You may need to turn this off when the
 +
display is on. The default setting is off (<code>-V</code>).</p>
 +
<p>
 +
The option <code>Draw_Vistas=on</code> or <code>+UD</code> was originally a
 +
debugging help for POV-Ray's vista buffer feature but it was such fun we
 +
decided to keep it. Vista buffering is a spatial sub-division method that
 +
projects the 2-D extents of bounding boxes onto the viewing window. POV-Ray
 +
tests the 2-D x, y pixel location against these rectangular areas to
 +
determine quickly which objects, if any, the viewing ray will hit. This
 +
option shows you the 2-D rectangles used. The default setting is off
 +
(<code>-UD</code>) because the drawing of the rectangles can take
 +
considerable time on complex scenes and it serves no critical purpose. See
 +
section &quot;<!--<linkto "Automatic Bounding Control">Automatic Bounding Control</linkto>--->[[Documentation:Reference Section 1.3#Automatic Bounding Control|Automatic Bounding Control]]&quot; for more details.</p>
 +
 +
===Mosaic Preview===
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Preview_Start_Size=</code>n<!--<indexentry primary "Preview_Start_Size, ini-option"></td>--->
 +
 +
<td width="70%">Set mosaic preview start size to n</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+SP</code>n<!--<indexentry "+sp"></td>--->
 +
 +
<td>Same as Preview_Start_Size=n</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>Preview_End_Size=</code>n<!--<indexentry primary "Preview_End_Size, ini-option"></td>--->
 +
 +
<td>Set mosaic preview end size to n</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+EP</code>n<!--<indexentry "+ep"></td>--->
 +
 +
<td>Same as Preview_End_Size=n</td>
 +
</tr>
 +
</table>
 +
 +
<p>Typically, while you are developing a scene, you will do many low
 +
resolution test renders to see if objects are placed properly. Often this low
 +
resolution version does not give you sufficient detail and you have to
 +
render the scene again at a higher resolution. A feature called <em>
 +
&quot;mosaic preview&quot;</em> solves this problem by automatically
 +
rendering your image in several passes.</p>
 +
<p>
 +
The early passes paint a rough overview of the entire image using large
 +
blocks of pixels that look like mosaic tiles. The image is then refined using
 +
higher resolutions on subsequent passes. This display method very quickly
 +
displays the entire image at a low resolution, letting you look for any major
 +
problems with the scene. As it refines the image, you can concentrate on more
 +
details, like shadows and textures. You do not have to wait for a full
 +
resolution render to find problems, since you can interrupt the rendering
 +
early and fix the scene, or if things look good, you can let it continue and
 +
render the scene at high quality and resolution.</p>
 +
<p>
 +
To use this feature you should first select a <code> Width</code> and <code>
 +
Height</code> value that is the highest resolution you will need. Mosaic
 +
preview is enabled by specifying how big the mosaic blocks will be on the
 +
first pass using <code> Preview_Start_Size=</code><em>n</em> or <code>
 +
+SP</code><em>n</em>. The value n should be a number greater than zero that
 +
is a power of two (1, 2, 4, 8, 16, 32, etc.) If it is not a power of two, the
 +
nearest power of two less than n is substituted. This sets the size of the
 +
squares, measured in pixels. A value of 16 will draw every 16th pixel as a
 +
16*16 pixel square on the first pass. Subsequent passes will use half the
 +
previous value (such as 8*8, 4*4 and so on.)</p>
 +
<p>
 +
The process continues until it reaches 1*1 pixels or until it reaches the
 +
size you set with <code> Preview_End_Size=</code><em>n</em> or <code>
 +
+EP</code><em>n</em>. Again the value n should be a number greater than zero
 +
that is a power of two and less than or equal to <code>
 +
Preview_Start_Size</code>. If it is not a power of two, the nearest power of
 +
two less than n is substituted. The default ending value is 1. If you set
 +
<code>Preview_End_Size</code> to a value greater than 1 the mosaic passes
 +
will end before reaching 1*1, but POV-Ray will always finish with a 1*1. For
 +
example, if you want a single 8*8 mosaic pass before rendering the final
 +
image, set <code> Preview_Start_Size=8</code> and <code>
 +
Preview_End_Size=8</code>.</p>
 +
<p>
 +
No file output is performed until the final 1*1 pass is reached. Although
 +
the preliminary passes render only as many pixels as needed, the 1*1 pass
 +
re-renders every pixel so that anti-aliasing and file output streams work
 +
properly. This makes the scene take up to 25% longer than the regular 1*1
 +
pass to render, so it is suggested that mosaic preview not be used for final
 +
rendering. Also, the lack of file output until the final pass means that
 +
renderings which are interrupted before the 1*1 pass can not be resumed
 +
without starting over from the beginning.</p>
 +
===File Output Options===
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Output_to_File=</code>bool<!--<indexentry primary "Output_to_File, ini-option"><indexentry primary "Output_to_File">---></td>
 +
 +
<td width="70%">Sets file output on/off</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+F</code></td>
 +
 +
<td>Sets file output on (use default type)</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>-F</code></td>
 +
 +
<td>Sets file output off</td>
 +
</tr>
 +
</table>
 +
 +
<p>By default, POV-Ray writes an image file to disk. When you are developing
 +
a scene and doing test renders, the graphic preview may be sufficient. To
 +
save time and disk activity you may turn file output off with <code>
 +
Output_to_File=off</code> or <code>-F</code>.</p>
 +
 
===Output File Type===
 
===Output File Type===
 
<table width="100%">
 
<table width="100%">
Line 54: Line 555:
 
<table width="100%">
 
<table width="100%">
 
<tr>
 
<tr>
−
<td width="30%"><code>.. C</code><!--<indexentry primary "Targa output, compressed" "Output, Targa, compressed"><indexentry "+fc"></td>--->
+
<td width="30%"><code>.. C</code><!--<indexentry primary "Targa output, compressed" "Output, Targa, compressed"><indexentry "+fc">---></td>
  
 
<td width="70%"><strong>C</strong>ompressed Targa-24 format (RLE, run length
 
<td width="70%"><strong>C</strong>ompressed Targa-24 format (RLE, run length
Line 61: Line 562:
  
 
<tr>
 
<tr>
−
<td width="30%"><code>.. J</code><!--<indexentry primary "JPEG output, compressed" "Output, JPEG, compressed"><indexentry "+fj"></td>--->
+
<td width="30%"><code>.. J</code><!--<indexentry primary "JPEG output, compressed" "Output, JPEG, compressed"><indexentry "+fj">---></td>
  
 
<td width="70%"><strong>J</strong>PEG format (Note: This format is not loss-free and will generate compression artifacts)</td>
 
<td width="70%"><strong>J</strong>PEG format (Note: This format is not loss-free and will generate compression artifacts)</td>
Line 67: Line 568:
  
 
<tr>
 
<tr>
−
<td><code>.. N</code><!--<indexentry primary "PNG output" "Output, PNG"><indexentry "+fn"></td>--->
+
<td><code>.. N</code><!--<indexentry primary "PNG output" "Output, PNG"><indexentry "+fn">---></td>
  
 
<td>P<strong>N</strong>G (portable network graphics) format</td>
 
<td>P<strong>N</strong>G (portable network graphics) format</td>
Line 73: Line 574:
  
 
<tr>
 
<tr>
−
<td><code>.. P</code><!--<indexentry primary "PPM output" "Output, PPM"><indexentry "+fp"></td>--->
+
<td><code>.. P</code><!--<indexentry primary "PPM output" "Output, PPM"><indexentry "+fp">---></td>
  
 
<td>Unix <strong>P</strong>PM format</td>
 
<td>Unix <strong>P</strong>PM format</td>
Line 79: Line 580:
  
 
<tr>
 
<tr>
−
<td><code>.. S</code><!--<indexentry primary "System-specific output" "Output, system-specific" "Output, BMP" "BMP output"><indexentry "+fs"></td>--->
+
<td><code>.. S</code><!--<indexentry primary "System-specific output" "Output, system-specific" "Output, BMP" "BMP output"><indexentry "+fs">---></td>
  
 
<td><strong>S</strong>ystem-specific such as Mac Pict or Windows BMP</td>
 
<td><strong>S</strong>ystem-specific such as Mac Pict or Windows BMP</td>
Line 85: Line 586:
  
 
<tr>
 
<tr>
−
<td><code>.. T</code><!--<indexentry primary "Targa output, uncompressed" "Output, Targa, uncompressed"><indexentry "+ft"></td>--->
+
<td><code>.. T</code><!--<indexentry primary "Targa output, uncompressed" "Output, Targa, uncompressed"><indexentry "+ft">---></td>
  
 
<td>Uncompressed <strong>T</strong>arga-24 format</td>
 
<td>Uncompressed <strong>T</strong>arga-24 format</td>
Line 95: Line 596:
 
and no longer necessary. PPM, PNG, and system specific formats have been
 
and no longer necessary. PPM, PNG, and system specific formats have been
 
added. PPM format images are uncompressed, and have a simple text header,
 
added. PPM format images are uncompressed, and have a simple text header,
−
which makes it a widely portable image format.  
+
which makes it a widely portable image format.</p>
 +
<p>
 +
PNG is an image format designed not only to replace GIF, but to improve on its shortcomings. PNG offers the highest compression available without loss for high quality applications, such as ray-tracing. The system specific format depends on the platform used and is covered in the appropriate system specific documentation.
 
</p>
 
</p>
−
<p>PNG is an image format
 
−
designed not only to replace GIF, but to improve on its shortcomings. PNG
 
−
offers the highest compression available without loss for high quality
 
−
applications, such as ray-tracing. The system specific format depends on the
 
−
platform used and is covered in the appropriate system specific
 
−
documentation.</p>
 
 
<p>
 
<p>
 
JPEG is particularly good at achieving high compression rates with photographic or photorealistic images, making it one of the most frequently used formats on the Internet. However, it is not loss-free. Images generated with this option will always contain compression artifacts (image defects). If you need to keep a high-quality image you should render using one of the loss-free formats.  
 
JPEG is particularly good at achieving high compression rates with photographic or photorealistic images, making it one of the most frequently used formats on the Internet. However, it is not loss-free. Images generated with this option will always contain compression artifacts (image defects). If you need to keep a high-quality image you should render using one of the loss-free formats.  
 
</p>
 
</p>
 
<p>
 
<p>
−
From POV-Ray 3.7 the JPEG compression quality can be controlled using the 'Compression' ini file option which, if set, needs to be an integer between 0 and 100. If values of 0 or 1 are specified then the default compression quality setting of 95% is used. Otherwise the value specified (2-100) is used as the compression quality setting. A value of 2 produces the smallest file (maximum compression), but looks terrible. A value of 100 produces the largest file (least compression) but can still contain some compression artifacts. Values lower than 0 are clipped to 0. Values greater than 100 are clipped to 100.
+
As of POV-Ray 3.7 the JPEG compression quality can be controlled using the 'Compression' ini file option which, if set, needs to be an integer between 0 and 100. If values of 0 or 1 are specified then the default compression quality setting of 95% is used. Otherwise the value specified (2-100) is used as the compression quality setting. A value of 2 produces the smallest file (maximum compression), but looks terrible. A value of 100 produces the largest file (least compression) but can still contain some compression artifacts. Values lower than 0 are clipped to 0. Values greater than 100 are clipped to 100.
 
</p>
 
</p>
 
<p>
 
<p>
Line 154: Line 651:
 
&quot;<!--<linkto "HF_Gray_16">HF_Gray_16</linkto>--->[[Documentation:Reference Section 3.1#HF_Gray_16|HF_Gray_16]]&quot; will also affect the  
 
&quot;<!--<linkto "HF_Gray_16">HF_Gray_16</linkto>--->[[Documentation:Reference Section 3.1#HF_Gray_16|HF_Gray_16]]&quot; will also affect the  
 
type of data written to the output file.</p>
 
type of data written to the output file.</p>
 +
 +
===Output File Name===
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Output_File_Name=</code>file<!--<indexentry primary "Output_File_Name, ini-option"></td>--->
 +
 +
<td width="70%">Sets output file to file</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+O</code>file<!--<indexentry "+o"></td>--->
 +
 +
<td>Same as <code>Output_File_Name=</code>file</td>
 +
</tr>
 +
</table>
 +
 +
<p>The default output filename is created from the scene name and need not be
 +
specified. The scene name is the input name with all drive, path, and
 +
extension information stripped. For example if the input file name is <code>
 +
c:\povray3\mystuff\myfile.pov</code> the scene name is <code> myfile</code>.
 +
The proper extension is appended to the scene name based on the file type.
 +
For example <code>myfile.tga</code> or <code> myfile.png</code> might be
 +
used.</p>
 +
<p>
 +
You may override the default output name using <code>
 +
Output_File_Name=</code><em>file</em> or <code> +O</code><em>file</em>. For
 +
example:</p>
 +
<pre>
 +
Input_File_Name=myinput.pov
 +
Output_File_Name=myoutput.tga
 +
</pre>
 +
 +
<p>If an output file name of &quot;-&quot; is specified (a single minus
 +
sign), then the image will be written to standard output, usually the screen.
 +
The output can then be piped into another program or to a GUI if desired.</p>
 +
<p>
 +
 +
<!--<indexentry primary "Default Output Directory" "Directory, default output" "Output File, placing in a default directory">--->
 +
If the file specified is actually a path or directory or folder name and not
 +
a file name, then the default output name is used but it is written to the
 +
specified directory. For example:</p>
 +
<pre>
 +
Input_File_Name=myscene.pov
 +
Output_File_Name=c:\povray3\myimages\
 +
</pre>
 +
 +
<p>This will create <code>c:\povray3\myimages\myscene.tga</code> as the
 +
output file.</p>
 +
 +
<h5>Output File Buffer</h5>
 +
<!--<indexentry primary "Buffer_Output">--->
 +
<!--<indexentry "+b">--->
 +
<!--<indexentry "-b">--->
 +
<!--<indexentry primary "Buffer_Size">--->
 +
<p>The output-file buffer options <code>Buffer_Output</code> and <code>Buffer_Size</code> are removed per POV-Ray 3.6</p>
 +
<p class="Note"><strong>Note:</strong> the options are still accepted, but ignored, in order to be backward compatible with old INI files.</p>
 +
 +
===CPU Utilization Histogram===
 +
<p>The CPU utilization histogram is a way of finding out where POV-Ray is
 +
spending its rendering time, as well as an interesting way of generating
 +
heightfields. The histogram splits up the screen into a rectangular grid of
 +
blocks. As POV-Ray renders the image, it calculates the amount of time it
 +
spends rendering each pixel and then adds this time to the total rendering
 +
time for each grid block. When the rendering is complete, the histogram is a
 +
file which represents how much time was spent computing the pixels in each
 +
grid block.</p>
 +
<p>
 +
Not all versions of POV-Ray allow the creation of histograms. The histogram
 +
output is dependent on the file type and the system that POV-Ray is being run
 +
on.</p>
 +
 +
<h5>File Type</h5>
 +
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Histogram_Type=</code>y<!--<indexentry primary "Histogram_Type, ini-option"></td>--->
 +
 +
<td width="70%">Set histogram type to y (Turn off if type is
 +
'<code>X</code>')</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HT</code>y<!--<indexentry "+ht"></td>--->
 +
 +
<td>Same as <code>Histogram_Type=</code>y</td>
 +
</tr>
 +
</table>
 +
 +
<p>The histogram output file type is nearly the same as that used for the
 +
image output file types in &quot;Output File Type&quot;. The available
 +
histogram file types are as follows.</p>
 +
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>+HTC</code><!--<indexentry "+htc"></td>--->
 +
 +
<td width="70%">Comma separated values (CSV) often used in spreadsheets</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HTN</code><!--<indexentry "+htn"></td>--->
 +
 +
<td>PNG (portable network graphics) format grayscale</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HTP</code><!--<indexentry "+htp"></td>--->
 +
 +
<td>Unix PPM format</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HTS</code><!--<indexentry "+hts"></td>--->
 +
 +
<td>System-specific such as Mac Pict or Windows BMP</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HTT</code><!--<indexentry "+htt"></td>--->
 +
 +
<td>Uncompressed Targa-24 format (TGA)</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HTX</code><!--<indexentry "+htx"></td>--->
 +
 +
<td>No histogram file output is generated</td>
 +
</tr>
 +
</table>
 +
 +
<p class="Note"><strong>Note:</strong> <code>+HTC</code> does not generate a compressed Targa-24 format
 +
output file but rather a text file with a comma-separated list of the time
 +
spent in each grid block, in left-to-right and top-to bottom order. The units
 +
of time output to the CSV file are system dependent. See the system specific
 +
documentation for further details on the time units in CSV files.</p>
 +
<p>
 +
The Targa and PPM format files are in the POV heightfield format (see
 +
&quot;<!--<linkto "Height Field">Height Field</linkto>--->[[Documentation:Reference Section 4#Height Field|Height Field]]&quot;), so the histogram information is stored in both the
 +
red and green parts of the image, which makes it unsuitable for viewing. When
 +
used as a height field, lower values indicate less time spent calculating the
 +
pixels in that block, while higher indicate more time spent in that
 +
block.</p>
 +
<p>
 +
PNG format images are stored as grayscale images and are useful for both
 +
viewing the histogram data as well as for use as a heightfield. In PNG files,
 +
the darker (lower) areas indicate less time spent in that grid block, while
 +
the brighter (higher) areas indicate more time spent in that grid block.</p>
 +
 +
===File Name===
 +
<table width="100%">
 +
<tr>
 +
<td width="30%"><code>Histogram_Name=</code>file<!--<indexentry primary "Histogram_Name, ini-option"></td>--->
 +
 +
<td width="70%">Set histogram name to file</td>
 +
</tr>
 +
 +
<tr>
 +
<td><code>+HN</code>file<!--<indexentry "+hn"></td>--->
 +
 +
<td>Same as <code>Histogram_Name=</code>file</td>
 +
</tr>
 +
</table>
 +
 +
<p>The histogram file name is the name of the file in which to write the
 +
histogram data. If the file name is not specified it will default to <code>
 +
histogram.ext</code>, where <code>ext</code> is based on the file type
 +
specified previously. </p>
 +
<p class="Note"><strong>Note:</strong> that if the histogram name is specified the file
 +
name extension should match the file type.</p>
 +
 +
== Output File Type need to be updated... ==
 +
 +
From sources
 +
 +
...T Targa (uncompressed)
 +
 +
...C Targa (compressed)
 +
 +
...N PNG
 +
 +
...J JPEG
 +
 +
...P PPM
 +
 +
...B BPM
 +
 +
...E OpenEXR
 +
 +
...H RadianceHDR
 +
 +
...S System (aka PNG)
 +
 +
The BMP (+FB) is missing in the documentation!
 +
--[[User:Le Forgeron|Le Forgeron]] 17:08, 13 April 2011 (UTC)
 +
 +
:Done: --[[User:Jholsenback|jholsenback]] 13:44, 14 April 2011 (UTC)

Latest revision as of 13:44, 14 April 2011

Interrupting Options

Test_Abort=bool Turn test for user abort on/off
+X Turn test abort on
-X Turn test abort off
Test_Abort_Count=n Set to test for abort every n pixels
+Xn Set to test for abort every n pixels on
-Xn Set to test for abort off (in future test every n pixels)

On some operating systems once you start a rendering you must let it finish. The Test_Abort=on option or +X switch causes POV-Ray to test the keyboard for keypress. If you have pressed a key, it will generate a controlled user abort. Files will be flushed and closed but only data through the last full row of pixels is saved. POV-Ray exits with an error code 2 (normally POV-Ray returns 0 for a successful run or 1 for a fatal error).

When this option is on, the keyboard is polled on every line while parsing the scene file and on every pixel while rendering. Because polling the keyboard can slow down a rendering, the Test_Abort_Count=n option or +Xn switch causes the test to be performed only every n pixels rendered or scene lines parsed.

Resuming Options

Continue_Trace=bool Sets continued trace on/off
+C Sets continued trace on
-C Sets continued trace off
Create_Ini=file Generate an INI file to file
Create_Ini=true Generate file.ini where file is scene name.
Create_Ini=false Turn off generation of previously set file.ini
+GIfile Same as Create_Ini=file

If you abort a render while it is in progress or if you used the End_Row option to end the render prematurely, you can use Continue_Trace=on or +C option to continue the render later at the point where you left off. This option reads in the previously generated output file, displays the partial image rendered so far, then proceeds with the ray-tracing. This option cannot be used if file output is disabled with Output_to_file=off or -F.

The Continue_Trace option may not work if the Start_Row option has been set to anything but the top of the file, depending on the output format being used. Also POV-Ray cannot continue the file once it has been opened and saved again by any program

POV-Ray tries to figure out where to resume an interrupted trace by reading any previously generated data in the specified output file. All file formats contain the image size, so this will override any image size settings specified. Some file formats (namely TGA and PNG) also store information about where the file started (i. e. +SCn and +SRn options), alpha output +UA, and bit-depth +FNn, which will override these settings. It is up to the user to make sure that all other options are set the same as the original render.

The Create_Ini option or +GI switch provides an easy way to create an INI file with all of the rendering options, so you can re-run files with the same options, or ensure you have all the same options when resuming. This option creates an INI file with every option set at the value used for that rendering. This includes default values which you have not specified. For example if you run POV-Ray with...

POVRAY +Isimple.pov MYOPTS +GIrerun.ini MOREOPTS

POV-Ray will create a file called rerun.ini with all of the options used to generate this scene. The file is not written until all options have been processed. This means that in the above example, the file will include options from both myopts.ini and moreopts.ini despite the fact that the +GI switch is specified between them. You may now re-run the scene with...

POVRAY RERUN

or resume an interrupted trace with

POVRAY RERUN +C

If you add other switches with the rerun.ini reference, they will be included in future re-runs because the file is re-written every time you use it.

The Create_Ini option is also useful for documenting how a scene was rendered. If you render waycool.pov with Create_Ini=on then it will create a file waycool.ini that you could distribute along with your scene file so other users can exactly re-create your image.

Display Output Options

Display Hardware Settings

Display=bool Turns graphic display on/off
+D Turns graphic display on
-D Turns graphic display off
Video_Mode=x Set video mode to x; does not affect on/off
+Dx Set display on; Set mode to x
-Dx Set display off; but for future use mode x
Palette=y Set display palette to y; does not affect on/off
+Dxy Set display on; Set mode x; Set palette y
-Dxy Set display off; use mode x, palette y in future
Display_Gamma=n.n Sets the display gamma to n.n

The Display=on or +D switch will turn on the graphics display of the image while it is being rendered. Even on some non-graphics systems, POV-Ray may display an 80 by 24 character "ASCII-Art" version of your image. Where available, the display may be full, 24-bit true color. Setting Display=off or using the -D switch will turn off the graphics display which is the default.

On the Windows platform, the default is Display=on. Turning display off does not, of course, turn off the actual video display. Instead, POV-Ray will not open the output window that it normally shows a render in.

The Video_Mode=x option sets the display mode or hardware type chosen where x is a single digit or letter that is machine dependent. Generally Video_Mode=0 means the default or an auto-detected setting should be used. When using switches, this character immediately follows the switch. For example the +D0 switch will turn on the graphics display in the default mode.

The Palette=y option selects the palette to be used. Typically the single character parameter y is a digit which selects one of several fixed palettes or a letter such G for gray scale, H for 15-bit or 16-bit high color or T for 24-bit true color. When using switches, this character is the 2nd character after the switch. For example the +D0T switch will turn on the graphics display in the default mode with a true color palette. The Display_Gamma=n.n setting is not available as a command-line switch.

The Display_Gamma setting overcomes the problem of images (whether ray-traced or not) having different brightness when being displayed on different monitors, different video cards, and under different operating systems.

Note: the Display_Gamma is a setting based on your computer's display hardware, and should be set correctly once and not changed.

The Display_Gamma INI setting works in conjunction with the new assumed_gamma global setting to ensure that POV scenes and the images they create look the same on all systems. See section "Assumed_Gamma" which describes the assumed_gamma global setting and describes gamma more thoroughly.

While the Display_Gamma can be different for each system, there are a few general rules that can be used for setting Display_Gamma if you do not know it exactly. If the Display_Gamma keyword does not appear in the INI file, POV-Ray assumes that the display gamma is 2.2. This is because most PC monitors have a gamma value in the range 1.6 to 2.6 (newer models seem to have a lower gamma value). Mac has the ability to do gamma correction inside the system software (based on a user setting in the gamma control panel). If the gamma control panel is turned off, or is not available, the default Macintosh system gamma is 1.8. Many newer PC graphics cards can do hardware gamma correction and should use the current Display_Gamma setting, usually 1.0.

Setting your Display Gamma

The following gamma test image can be used to help you set your Display_Gamma accurately.

Before viewing the gamma image darken the room and set the monitor brightness and contrast to maximum. While viewing a black screen, lower the brightness gradually until the "background" is no longer noticeable (ie when it just fades from view). This may be difficult on monitors that use overscanning, unless you change the viewable area settings.

Display gamma test image.

Now, lower the contrast until the alternating white and black bars on the left edge of each column are equal in width. This is trying to get a 50% gray by using half white and half black. If this is not possible, choose a contrast setting which is about in the middle. While viewing the image from a distance, or with squinted eyes, one of the numbered "swatches" will best match the gray value approximated by the white and black bars. The number in this "swatch" is your display's actual gamma value.

Normal display gamma values are in the range 2.0 to 2.6. If your monitor is usually used in a dim environment, we often use a gamma value that is 15% - 25% lower than the actual display gamma to give the images more contrast. Some systems, such as Macs and SGIs, already do gamma correction, so they may have display gammas of 1.0 or 1.8.

For scene files that do not contain an assumed_gamma global setting the INI file option Display_Gamma will not have any affect on the preview output of POV-Ray or for most output file formats. However, the Display_Gamma value is used when creating PNG format output files, and also when rendering the POV-Ray example files (because they have an assumed_gamma), so it should still be correctly set for your system to ensure proper results.

Display Related Settings

Pause_When_Done=bool Sets pause when done on/off
+P Sets pause when done on
-P Sets pause when done off
Verbose=bool Set verbose messages on/off
+V Set verbose messages on
-V Set verbose messages off
Draw_Vistas=bool Turn draw vistas on/off
+UD Turn draw vistas on
-UD Turn draw vistas off

On some systems, when the image is complete, the graphics display is cleared and POV-Ray switches back into text mode to print the final statistics and to exit. Normally when the graphics display is on, you want to look at the image awhile before continuing. Using Pause_When_Done=on or +P causes POV-Ray to pause in graphics mode until you press a key to continue. The default is not to pause (-P).

When the graphics display is not used, it is often desirable to monitor progress of the rendering. Using Verbose=on or +V turns on verbose reporting of your rendering progress. This reports the number of the line currently being rendered, the elapsed time for the current frame and other information. On some systems, this textual information can conflict with the graphics display. You may need to turn this off when the display is on. The default setting is off (-V).

The option Draw_Vistas=on or +UD was originally a debugging help for POV-Ray's vista buffer feature but it was such fun we decided to keep it. Vista buffering is a spatial sub-division method that projects the 2-D extents of bounding boxes onto the viewing window. POV-Ray tests the 2-D x, y pixel location against these rectangular areas to determine quickly which objects, if any, the viewing ray will hit. This option shows you the 2-D rectangles used. The default setting is off (-UD) because the drawing of the rectangles can take considerable time on complex scenes and it serves no critical purpose. See section "Automatic Bounding Control" for more details.

Mosaic Preview

Preview_Start_Size=n Set mosaic preview start size to n
+SPn Same as Preview_Start_Size=n
Preview_End_Size=n Set mosaic preview end size to n
+EPn Same as Preview_End_Size=n

Typically, while you are developing a scene, you will do many low resolution test renders to see if objects are placed properly. Often this low resolution version does not give you sufficient detail and you have to render the scene again at a higher resolution. A feature called "mosaic preview" solves this problem by automatically rendering your image in several passes.

The early passes paint a rough overview of the entire image using large blocks of pixels that look like mosaic tiles. The image is then refined using higher resolutions on subsequent passes. This display method very quickly displays the entire image at a low resolution, letting you look for any major problems with the scene. As it refines the image, you can concentrate on more details, like shadows and textures. You do not have to wait for a full resolution render to find problems, since you can interrupt the rendering early and fix the scene, or if things look good, you can let it continue and render the scene at high quality and resolution.

To use this feature you should first select a Width and Height value that is the highest resolution you will need. Mosaic preview is enabled by specifying how big the mosaic blocks will be on the first pass using Preview_Start_Size=n or +SPn. The value n should be a number greater than zero that is a power of two (1, 2, 4, 8, 16, 32, etc.) If it is not a power of two, the nearest power of two less than n is substituted. This sets the size of the squares, measured in pixels. A value of 16 will draw every 16th pixel as a 16*16 pixel square on the first pass. Subsequent passes will use half the previous value (such as 8*8, 4*4 and so on.)

The process continues until it reaches 1*1 pixels or until it reaches the size you set with Preview_End_Size=n or +EPn. Again the value n should be a number greater than zero that is a power of two and less than or equal to Preview_Start_Size. If it is not a power of two, the nearest power of two less than n is substituted. The default ending value is 1. If you set Preview_End_Size to a value greater than 1 the mosaic passes will end before reaching 1*1, but POV-Ray will always finish with a 1*1. For example, if you want a single 8*8 mosaic pass before rendering the final image, set Preview_Start_Size=8 and Preview_End_Size=8.

No file output is performed until the final 1*1 pass is reached. Although the preliminary passes render only as many pixels as needed, the 1*1 pass re-renders every pixel so that anti-aliasing and file output streams work properly. This makes the scene take up to 25% longer than the regular 1*1 pass to render, so it is suggested that mosaic preview not be used for final rendering. Also, the lack of file output until the final pass means that renderings which are interrupted before the 1*1 pass can not be resumed without starting over from the beginning.

File Output Options

Output_to_File=bool Sets file output on/off
+F Sets file output on (use default type)
-F Sets file output off

By default, POV-Ray writes an image file to disk. When you are developing a scene and doing test renders, the graphic preview may be sufficient. To save time and disk activity you may turn file output off with Output_to_File=off or -F.

Output File Type

Output_File_Type=x Sets file output format to x
+Fxn Sets file output on; sets format x, depth n
-Fxn Sets file output off; but in future use format x, depth n
Output_Alpha=bool Sets alpha output on/off
+UA Sets alpha output on
-UA Sets alpha output off
Bits_Per_Color=n Sets file output bits/color to n

The default type of image file depends on which platform you are using. MS-DOS and most others default to 24-bit uncompressed Targa. Windows defaults to 'sys', which is 24-bit BMP. See your platform-specific documentation to see what your default file type is. You may select one of several different file types using Output_File_Type=x or +Fx where x is one of the following...

.. C Compressed Targa-24 format (RLE, run length encoded)
.. J JPEG format (Note: This format is not loss-free and will generate compression artifacts)
.. N PNG (portable network graphics) format
.. P Unix PPM format
.. S System-specific such as Mac Pict or Windows BMP
.. T Uncompressed Targa-24 format

Note: the obsolete +FD dump format and +FR raw format have been dropped because they were rarely used and no longer necessary. PPM, PNG, and system specific formats have been added. PPM format images are uncompressed, and have a simple text header, which makes it a widely portable image format.

PNG is an image format designed not only to replace GIF, but to improve on its shortcomings. PNG offers the highest compression available without loss for high quality applications, such as ray-tracing. The system specific format depends on the platform used and is covered in the appropriate system specific documentation.

JPEG is particularly good at achieving high compression rates with photographic or photorealistic images, making it one of the most frequently used formats on the Internet. However, it is not loss-free. Images generated with this option will always contain compression artifacts (image defects). If you need to keep a high-quality image you should render using one of the loss-free formats.

As of POV-Ray 3.7 the JPEG compression quality can be controlled using the 'Compression' ini file option which, if set, needs to be an integer between 0 and 100. If values of 0 or 1 are specified then the default compression quality setting of 95% is used. Otherwise the value specified (2-100) is used as the compression quality setting. A value of 2 produces the smallest file (maximum compression), but looks terrible. A value of 100 produces the largest file (least compression) but can still contain some compression artifacts. Values lower than 0 are clipped to 0. Values greater than 100 are clipped to 100.

GIF is good at achieving high compression rates when there are large areas of flat color. This image format is frequently used for banners and logos on the Internet. Most raytraced images contain subtle color changes which do not compress well with GIF compression, but POV-Ray can be used to generate flat-color images using high ambient values and no light sources.

Most of these formats output 24 bits per pixel with 8 bits for each of red, green and blue data. PNG and PPM allow you to optionally specify the output bit depth from 5 to 16 bits for each of the red, green, and blue colors, giving from 15 to 48 bits of color information per pixel. The default output depth for all formats is 8 bits/color (16 million possible colors), but this may be changed for PNG and PPM format files by setting Bits_Per_Color=n or by specifying +FNn or +FPn, where n is the desired bit depth.

Specifying a smaller color depth like 5 bits/color (32768 colors) may be enough for people with 8- or 16-bit (256 or 65536 color) displays, and will improve compression of the PNG file. Higher bit depths like 10 or 12 may be useful for video or publishing applications, and 16 bits/color is good for grayscale height field output (See section "Height Field" for details on height fields).

Targa format also allows 8 bits of alpha transparency data to be output, while PNG format allows 5 to 16 bits of alpha transparency data, depending on the color bit depth as specified above. You may turn this option on with Output_Alpha=on or +UA. The default is off or -UA.

The alpha channel stores a transparency value for each pixel, just like there is also stored a value for red green and blue light for each pixel. In POV-Ray, when the alpha channel is turned on, all areas of the image where the background is partly or fully visible will be partly or fully transparent. Refractions of the background will also be transparent, but not reflections. Also anti-aliasing is taken into account

The philosophy of the alpha channel feature in POV-Ray is that the background color should not be present in the color of the image when the alpha channel is used. Instead, the amount of visible background is kept in the alpha and *only* in the alpha channel. That ensures that images look correct when viewed with the alpha channel.

See section "Using the Alpha Channel" for further details on using transparency in imagemaps in your scene.

In addition to support for variable bit-depths, alpha channel, and grayscale formats, PNG files also store the Display_Gamma value so the image displays properly on all systems (see section "Display Hardware Settings"). The hf_gray_16 global setting, as described in section "HF_Gray_16" will also affect the type of data written to the output file.

Output File Name

Output_File_Name=file Sets output file to file
+Ofile Same as Output_File_Name=file

The default output filename is created from the scene name and need not be specified. The scene name is the input name with all drive, path, and extension information stripped. For example if the input file name is c:\povray3\mystuff\myfile.pov the scene name is myfile. The proper extension is appended to the scene name based on the file type. For example myfile.tga or myfile.png might be used.

You may override the default output name using Output_File_Name=file or +Ofile. For example:

Input_File_Name=myinput.pov
Output_File_Name=myoutput.tga

If an output file name of "-" is specified (a single minus sign), then the image will be written to standard output, usually the screen. The output can then be piped into another program or to a GUI if desired.

If the file specified is actually a path or directory or folder name and not a file name, then the default output name is used but it is written to the specified directory. For example:

Input_File_Name=myscene.pov
Output_File_Name=c:\povray3\myimages\

This will create c:\povray3\myimages\myscene.tga as the output file.

Output File Buffer

The output-file buffer options Buffer_Output and Buffer_Size are removed per POV-Ray 3.6

Note: the options are still accepted, but ignored, in order to be backward compatible with old INI files.

CPU Utilization Histogram

The CPU utilization histogram is a way of finding out where POV-Ray is spending its rendering time, as well as an interesting way of generating heightfields. The histogram splits up the screen into a rectangular grid of blocks. As POV-Ray renders the image, it calculates the amount of time it spends rendering each pixel and then adds this time to the total rendering time for each grid block. When the rendering is complete, the histogram is a file which represents how much time was spent computing the pixels in each grid block.

Not all versions of POV-Ray allow the creation of histograms. The histogram output is dependent on the file type and the system that POV-Ray is being run on.

File Type
Histogram_Type=y Set histogram type to y (Turn off if type is 'X')
+HTy Same as Histogram_Type=y

The histogram output file type is nearly the same as that used for the image output file types in "Output File Type". The available histogram file types are as follows.

+HTC Comma separated values (CSV) often used in spreadsheets
+HTN PNG (portable network graphics) format grayscale
+HTP Unix PPM format
+HTS System-specific such as Mac Pict or Windows BMP
+HTT Uncompressed Targa-24 format (TGA)
+HTX No histogram file output is generated

Note: +HTC does not generate a compressed Targa-24 format output file but rather a text file with a comma-separated list of the time spent in each grid block, in left-to-right and top-to bottom order. The units of time output to the CSV file are system dependent. See the system specific documentation for further details on the time units in CSV files.

The Targa and PPM format files are in the POV heightfield format (see "Height Field"), so the histogram information is stored in both the red and green parts of the image, which makes it unsuitable for viewing. When used as a height field, lower values indicate less time spent calculating the pixels in that block, while higher indicate more time spent in that block.

PNG format images are stored as grayscale images and are useful for both viewing the histogram data as well as for use as a heightfield. In PNG files, the darker (lower) areas indicate less time spent in that grid block, while the brighter (higher) areas indicate more time spent in that grid block.

File Name

Histogram_Name=file Set histogram name to file
+HNfile Same as Histogram_Name=file

The histogram file name is the name of the file in which to write the histogram data. If the file name is not specified it will default to histogram.ext, where ext is based on the file type specified previously.

Note: that if the histogram name is specified the file name extension should match the file type.

Output File Type need to be updated...

From sources

...T Targa (uncompressed)

...C Targa (compressed)

...N PNG

...J JPEG

...P PPM

...B BPM

...E OpenEXR

...H RadianceHDR

...S System (aka PNG)

The BMP (+FB) is missing in the documentation! --Le Forgeron 17:08, 13 April 2011 (UTC)

Done: --jholsenback 13:44, 14 April 2011 (UTC)
Retrieved from "https://wiki.povray.org/content?title=Documentation_Talk:Reference_Section_1.1&oldid=4438"