Reference: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

There has been a Change as of version 3.7 regarding the default output file type. For all supported platforms the default is now PNG.

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
Grayscale_Output=bool	Sets grayscale output on/off (PNG and PPM only)
Greyscale_Output=bool	Same as Grayscale_Output=bool
+Fxgn	Sets file output on; sets format x, sets grayscale if applicable, depth n
-Fxgn	Sets file output off; but in future use format x, sets grayscale if applicable, 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. A Change in version 3.8 allows values ranging from 1 to 16.
Compression=n	Sets compression parameter for file types that support it.

You may select one of several different file types by using Output_File_Type=x or +Fx where x is one of the following:

B or b	Universal Bitmap image file format
C or c	Compressed Targa-24 format (RLE, run length encoded)
E or e	OpenEXR High Dynamic-Range format
H or h	Radiance High Dynamic-Range format
J or j	JPEG format (Note: This format is not loss-free and will generate compression artifacts)
N or n	PNG (portable network graphics) format
P or p	Unix PPM format
S or s	System-specific format: See the notation at the end of this section.
T or t	Uncompressed Targa-24 format

Grayscale output can be used to generate heightfields for use in other POV-Ray scenes, by using Grayscale_Output=true as an INI option, or +Fxg for output type x as a command-line option. For example, +Fng for PNG and +Fpg for PPM (technically PGM) grayscale output. By default this option is off.

With Grayscale_Output=true, the output file will be in the form of a grayscale image that can be used to generate heightfields, as the height at any point is dependent on the brightness of the pixel. The brightness of a pixel is calculated in the same way that color images are converted to grayscale images: height = 0.3 * red + 0.59 * green + 0.11 * blue.

Previously, the grayscale PPM (technically PGM) output file format always used linear output. A Change in v3.8 will match that of the regular non-grayscale PPM format. That is File_Gamma will be honored if specified, otherwise the ITU-R BT.709 gamma transfer function will be applied.

In previous versions PPM output always created the compact raw (binary) format. A Change in version 3.8 now allows the use of INI setting Compression=0 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.

See also: Height Field for a description of how POV-Ray heightfields are stored for each file type.

Previously, specifying a bit-depth for grayscale file output was simply ignored and the bit-depth was forced to 16 bits per channel. A Change in version 3.8 now allows for a bit-depth setting.

It should also be noted that with previous versions setting the Grayscale_Output=true INI option would not cause the preview display, if used, to be grayscale. A Change in version 3.8 now shows a grayscale image on the preview display as well.

Currently PNG, and PPM are the only file formats that support grayscale output.

Last but not least, when choosing output file options it may be helpful to consider the following:

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

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 1 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. New as of version 3.8, instead of Output_File_Type=C you can also use Output_File_Type=T Compression=1 to choose RLE-encoded Targa format.

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.

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
+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.png as the output file.

Output File Buffer

The output-file buffer options Buffer_Output and Buffer_Size are removed per POV-Ray v3.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:
+/-THxx	Command line equivalent

Ordered dithering algorithms:

• B2..B4: Bayer pattern dithering using 2x2, 3x3 or 4x4 patterns, respectively
• BN: Blue noise pattern dithering using a 64x64 pattern. New in version 3.8
• BNX: same as BN but using the pattern's inverse for the R and B channels. New in version 3.8

Error diffusion dithering algorithms:

• AT: Atkinson error diffusion dithering. New in version 3.8
• BK: Burkes error diffusion dithering. New in version 3.8
• D1: Simple 1-dimensional error diffusion dithering
• D2: Sierra Lite error diffusion dithering
• FS: Floyd-Steinberg error diffusion dithering
• JN: Jarvis-Judice-Ninke error diffusion dithering. New in version 3.8
• S2: Two-Row Sierra error diffusion dithering. New in version 3.8
• S3: Three-Row Sierra error diffusion dithering. New in version 3.8
• ST: Stucki error diffusion dithering. New in version 3.8

As always file output dithering is off by default, however a Change in version 3.8 now sets the default dithering method from FS to BN if only +TH is specified.

In version 3.7 the display preview window used Bayer 4x4 dithering. A Change in version 3.8 has switched that to the recently added blue noise pattern.

New in version 3.8 dithering is now fully supported for Radiance HDR output files.

New in version 3.8 file output dithering is now fully gamma-aware. The overall apparent brightness of the resulting image is faithfully reproduced.

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.8, selects the ITU-R BT.709 transfer function instead of a power-law output file gamma
File_Gamma=BT2020	New in version 3.8, 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.8, 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.