Difference between revisions of "Reference:File Output Options"
Jholsenback (talk | contribs) m (changes from talk page) |
Jholsenback (talk | contribs) m (updated see also) |
||
Line 318: | Line 318: | ||
<p class="Note"><strong>Note:</strong> Specifying <code>File_Gamma=BT709</code> or <code>File_Gamma=BT2020</code> only affects the <em>transfer function</em> used. Specifically, it does <em>not</em> affect the digital representation of nominal black and white, which remain at 0 and 255 (presuming 8-bit encoding), respectively, as opposed to 16 and 235 for full-fledged ITU-R BT-709 encoding.</p> | <p class="Note"><strong>Note:</strong> Specifying <code>File_Gamma=BT709</code> or <code>File_Gamma=BT2020</code> only affects the <em>transfer function</em> used. Specifically, it does <em>not</em> affect the digital representation of nominal black and white, which remain at 0 and 255 (presuming 8-bit encoding), respectively, as opposed to 16 and 235 for full-fledged ITU-R BT-709 encoding.</p> | ||
− | See | + | <p>See also: [[Documentation:Tutorial Section 3.3#Gamma in Output Images|Gamma in Output Images]] for additional information.</p> |
==CPU Utilization Histogram== | ==CPU Utilization Histogram== | ||
<p>The CPU Utilization Histogram feature has been removed as of POV-Ray v3.7.</p> | <p>The CPU Utilization Histogram feature has been removed as of POV-Ray v3.7.</p> |
Revision as of 19:17, 31 December 2016
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 |
+F xn |
Sets file output on; sets format x, depth n |
-F xn |
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 |
Compression= n |
Sets compression parameter for file types that support it. |
Note: As of version 3.7 the default output file type for all supported platforms is PNG. You may select one of several different file types by using Output_File_Type=
x or +F
x where x is one of the following:
.. B |
Universal Bitmap image file format |
.. C |
Compressed Targa-24 format (RLE, run length encoded) |
.. E |
OpenEXR High Dynamic-Range format |
.. H |
Radiance High Dynamic-Range format |
.. 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 format: See the notation at the end of this section. |
.. T |
Uncompressed Targa-24 format |
New as of version 3.7.1, instead of Output_File_Type=C
you can also use Output_File_Type=T Compression=1
to choose RLE-encoded Targa 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.
New Prior to version 3.7.1, PPM output always created the compact raw (binary) format. The Compression=0
ini setting can now be used to select the plain (ASCII) format instead.
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.
Note: Chroma sub-sampling has been disabled in JPEG output, and there has been a reduction in the default quality setting.
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 85% 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.
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 +FN
n or +FP
n,
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.
Note: In version 3.7 alpha handling for image file output has changed. Effectively, the background now requires a filter
or transmit
value in order for alpha transparency to work properly.
Previous versions of POV-Ray always wrote associated alpha for output, this has been changed on a per-file-format basis as follows:
- PNG will use straight alpha as per specification.
- OpenEXR will use associated alpha as per specifications.
- TGA and BMP 32-bit RGBA will use straight alpha, retaining file input compatibility for now, until a final decision has been made on these formats.
In addition to support for variable bit-depths, alpha channel, and grayscale
formats, PNG files also store the File_Gamma
value so the
image displays properly on all systems.
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.
The Radiance Synthetic Imaging System or .hdr image format was originally developed to aid lighting designers and architects by predicting the light levels and appearance of a space prior to construction. The OpenEXR or .exr image file format was developed by Industrial Light & Magic™ for use in computer imaging applications.
Most image formats now include metadata (BMP is a notable exception). This metadata contains the POV-Ray version, render date/time (GMT), platform (e.g. x86_64-pc-win), and compiler used to build the POV-Ray executable.
Note: System-specific or type "s" output file format is being retained for legacy support reasons. Windows and Unix mapping remains the same, BMP and TGA respectively, however on Macintosh it has been changed to PNG, and a warning is issued when type "s" is used.
Output File Name
Output_File_Name= file |
Sets output file to file |
+O file |
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 +O
file. 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.png
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.
Output File Dithering
Dither= bool |
Turns output file dithering on/off |
Dither_Method= xx |
Selects the output file dithering method, where xx is listed below: |
+/-TH xx |
Command line equivalent |
B2
..B4
: Bayer pattern dithering using 2x2, 3x3 or 4x4 patterns, respectivelyD1
: Simple 1-dimensional error diffusion ditheringD2
: Simple 2-dimensional error diffusion dithering (needs extra memory for 2 pixel rows)FS
: Floyd-Steinberg error diffusion dithering (needs extra memory for 2 pixel rows)
The default is -THfs
i.e: dithering is off, with Floyd-Steinberg being the default if only +TH
is specified.
Dithering works for all file formats except JPEG (where dithering would be counter-productive) and OpenEXR (which provides sufficient precision to make dithering obsolete). These file formats simply ignore the setting.
Note: While dithering does help to reduce color banding, it may instead lead to artifacts in prints, due to interference with the printing device's own dithering algorithms; in that case, choosing a different dither method may help.
Output File Gamma
File_Gamma= x.x |
Sets output file gamma to n.n |
File_Gamma=sRGB |
Selects the sRGB transfer function instead of a power-law output file gamma |
File_Gamma=BT709 |
New in version 3.7.1, selects the ITU-R BT.709 transfer function instead of a power-law output file gamma |
File_Gamma=BT2020 |
New in version 3.7.1, selects the ITU-R BT.2020 transfer function instead of a power-law output file gamma |
Many file formats traditionally have no clearly specified gamma handling policy, and require images to be gamma pre-corrected for whatever target system they are to be displayed on. For such file formats (currently all except PNG, OpenEXR and Radiance HDR), the File_Gamma
setting specifies the target display gamma for which to pre-correct (typically a value in the range from 1.6 to around 2.5, with 2.2 being the most commonly used), and will have an influence on the brightness and saturation of the image when displayed.
Some other file formats do have a clearly specified gamma handling policy, but allow for gamma encoding with an arbitrary gamma value (currently only PNG). For such formats, File_Gamma
specifies the decoding gamma or, in other words, the inverse of the encoding gamma to use, and will have no effect on the brightness and saturation of the image when displayed with contemporary software; the setting will however affect the likelihood of banding artifacts.
The parameter has no effect on file formats mandating linear storage of color values (currently OpenEXR and Radiance HDR).
Alternatively to a numeric value, sRGB
can be specified, instructing POV-Ray to employ the sRGB transfer function, which is similar but not quite identical to a power-law gamma curve with a gamma of 2.2. sRGB
is also the default on all platforms currently supported. New in version 3.7.1, BT709
or BT2020
can also be specified, instructing POV-Ray to employ the transfer function specified in ITU-R BT.709 or ITU-R BT.2020, respectively, which are similar but not quite identical to a power-law gamma curve with a gamma of roughly 1.9. When generating Netpbm PPM output, BT709
is the effective default.
Note: Specifying File_Gamma=BT709
or File_Gamma=BT2020
only affects the transfer function used. Specifically, it does not affect the digital representation of nominal black and white, which remain at 0 and 255 (presuming 8-bit encoding), respectively, as opposed to 16 and 235 for full-fledged ITU-R BT-709 encoding.
See also: Gamma in Output Images for additional information.
CPU Utilization Histogram
The CPU Utilization Histogram feature has been removed as of POV-Ray v3.7.