| 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 doesn't 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 don't 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.
Future versions of POV-Ray will include some system of temporary files or buffers which will eliminate these inefficiencies and limitations. Mosaic preview is still a very useful feature for test renderings.
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.
The default type of image file depends on which platform you are using. MS-DOS and most others default to 24-bit uncompressed Targa. 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...
Note that the obsolete +FD dump format and +FR raw format have been dropped from POV-Ray 3.0 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 a new 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 allows 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 format files by setting Bits_Per_Color=n or by specifying +FNn, 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. See section "Using the Alpha Channel" for further details on transparency.
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.
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:
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.
The Buffer_Output and Buffer_Size options and the +B switch allows you to assign large buffers to the output file. This reduces the amount of time spent writing to the disk. If this parameter is not specified, then as each row of pixels is finished, the line is written to the file and the file is flushed. On most systems, this operation ensures that the file is written to the disk so that in the event of a system crash or other catastrophic event, at least a part of the picture has been stored properly and retrievable on disk. The default is not to use any buffer.
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.
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.
Note that +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.
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 histgram.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.
The histogram grid size gives the number of times the image is split up in both the horizontal and vertical directions. For example
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 that 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.
You will probably always set this option but if you do not the default input filename is object.pov. If you do not have an extension then .pov is assumed. On case-sensitive operating systems both .pov and .POV are tried. A full path specification may be used (on MS-DOS systems +Ic:\povray3\mystuff\myfile.pov is allowed for example). In addition to specifying the input file name this also establishes the scene name.
The scene name is the input name with drive, path and extension stripped. In the above example the scene name is myfile. This name is used to create a default output file name and it is referenced other places.
If you use "-" as the input file name the input will be read from standard input. Thus you can pipe a scene created by a program to POV-Ray and render it without having a scene file.
Under MS-DOS you can try this feature by typing.
POV-Ray looks for files in the current directory. If it does not find a file it needs it looks in various other library directories which you specify. POV-Ray does not search your operating system path. It only searches the current directory and directories which you specify with this option. For example the standard include files are usually kept in one special directory. You tell POV-Ray to look there with...
You must not specify any final path separators ("\" or "/") at the end.
Multiple uses of this option switch do not override previous settings. Up to ten unique paths may be specified. If you specify the exact same path twice it is only counts once. The current directory will be searched first followed by the indicated library directories in the order in which you specified them.
Section 6.2.2.3
File Output OptionsOutput_to_File=bool Sets file output on/off +F Sets file output on (use default type) -F Sets file output off
Section 6.2.2.3.1
Output File TypeOutput_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' +FC Compressed Targa-24 format (RLE, run length encoded) +FN New PNG (portable network graphics) format +FP Unix PPM format +FS System-specific such as Mac Pict or Windows BMP +FT Uncompressed Targa-24 format
Section 6.2.2.3.2
Output File NameOutput_File_Name=file Sets output file to file +Ofile Same as Output_File_Name=file
Section 6.2.2.3.3
Output File BufferBuffer_Output=bool Turn output buffering on/off +B Turn output buffering on -B Turn output buffering off Buffer_Size=n Set output buffer size to 'n' kilobytes. If n is zero, no buffering. If n < system default, the system default is used. +Bn Turn buffer on, set size n -Bn Turn buffer off, but for future set size n
Section 6.2.2.4
CPU Utilization Histogram
Section 6.2.2.4.1
File TypeHistogram_Type=x Set histogram type to x (turn off if type is 'X') +HTx Same as Histogram_Type=x +HTC Comma separated values (CSV) often used in spreadsheets +HTN New 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
Section 6.2.2.4.2
File NameHistogram_Name=file Set histogram name to file +HNfile Same as Histogram_Name=file
Section 6.2.2.4.3
Grid SizeHistogram_Grid_Size=xx.yy Set histogram grid to xx by yy +HSxx.yy Same as Histogram_Grid_Size=xx.yy
Section 6.2.3
Scene Parsing Options
Section 6.2.3.1
Input File NameInput_File_Name=file Sets input file name to file +Ifile Same as Input_File_Name=file
Section 6.2.3.2
Library PathsLibrary_Path=path Add path to list of library paths +Lpath Same as Library_Path=path
Table Of Contents