2.1.2.4 File Output Options

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.

2.1.2.4.1 Output File Type

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

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.

2.1.2.4.2 Output File Name

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.

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

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

2.1.2.4.5 File Type

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.

2.1.2.4.6 File Name

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.

2.1.2.4.7 Grid Size

The histogram grid size gives the number of times the image is split up in both the horizontal and vertical directions. For example

 povray +Isample +W640 +H480 +HTN +HS160.120 +HNhistogram.png

will split the image into 160*120 grid blocks, each of size 4*4 pixels, and output a PNG file, suitable for viewing or for use as a heightfield. Smaller numbers for the grid size mean more pixels are put into the same grid block. With CSV output, the number of values output is the same as the number of grid blocks specified. For the other formats the image size is identical to the rendered image rather than the specified grid size, to allow easy comparison between the histogram and the rendered image. If the histogram grid size is not specified, it will default to the same size as the image, so there will be one grid block per pixel.

Note: on systems that do task-switching or multi-tasking the histogram may not exactly represent the amount of time POV-Ray spent in a given grid block since the histogram is based on real time rather than CPU time. As a result, time may be spent for operating system overhead or on other tasks running at the same time. This will cause the histogram to have speckling, noise or large spikes. This can be reduced by decreasing the grid size so that more pixels are averaged into a given grid block.