A .pov scene is read by one program, povray, which parses the scene and writes an image (or a series of images). This page covers how it is started, what it reads on start-up (povray.conf and povray.ini), the sample INI files that come with it, the exit status, the image formats on both sides, the front ends and editors around it, the folder of sample scenes, and how it is built from source on Unix.
Running povray
povray +Iscene.pov [+Oimage] [+/-switch ...] [option=value ...] [settings.ini]Every switch has an INI form and the reverse; the full list is on INI options and switches. A bare argument is read by its ending: a name that ends in .pov is the scene, a name that ends in a path separator is a library path, and anything else is an INI file (file.ini[Section] reads only that section). Options are not case sensitive, they cannot hold spaces (write +FN, not +F N), and they cannot be combined (+SC is not +S +C). If an option is given more than once the last value wins, except +L (library path), which adds up.
povray +Iscene.pov +W640 +H480 +A0.3 +Q9
povray +Iscene.pov +KFF30 -D +FN
povray scene.pov Output_File_Name=out/ Declare=RAD=0
povray myoptions.ini +Iscene.pov
povray 'quickres.ini[640x480, No AA]' +Iscene.pov'"quickres.ini[640x480, No AA]"'); without them the program stops with "Failed to parse command-line option".Exit status
| Code | Meaning |
|---|---|
| 0 | the run finished |
| 1 | an error: a bad option, a file that cannot be opened, a fatal error such as a parse error |
| 2 | a user abort (Control-C or SIGINT saves the part of the image that is finished, then exits) |
The man page says only "0 if OK, 1 if minor problems, above 1 for serious trouble"; the program returns the three values above. The shell command options can change the code (INI options and switches).
Unix extras
| Switch or variable | Meaning |
|---|---|
-h, -help, --help, -? | usage text |
-version, --version, --V, --generation | the version, or the short generation number |
-benchmark, --benchmark | renders the built-in benchmark scene (needs the library files to be installed; +WTn sets the thread count) |
POVINI | file name of the INI file to read instead of the default search |
POVINC | one more library path, added after the INI files |
POV_TEMP_DIR | directory for temporary files |
HOME | the home directory, used for ~/.povray/3.8/ and %HOME% in povray.conf |
The man page also says that +I- reads the scene from standard input. The program built from the 3.8 source here does not: it reports "Cannot find file '-'" (an output name of - does write the image to standard output). The display uses a preview window when the program was built with the SDL library, and a rough text-graphics view otherwise.
The man page, povray.conf and povray.ini
povray.1 is the Unix man page. It lists the common switches with their INI forms, the exit status and the files below. It is shorter than the reference manual and a little behind it (for instance it does not list +AM3, and it still says +Q10 and +Q11 add radiosity).
povray.conf
This file limits what a scene or an INI file may do to the computer. It is read from two places: the system file (<prefix>/etc/povray/3.8/povray.conf) and the user file (~/.povray/3.8/povray.conf). The program uses the stricter of what they say: a user file can only add restrictions. Comment lines start with ;.
| Section | Setting | Meaning |
|---|---|---|
[File I/O Security] | none | no restriction beyond the file system's own |
read-only | files may be read anywhere; writing is limited to the read+write directories | |
restricted | only the listed directories may be used (the sample file sets this) | |
[Shellout Security] | allowed or forbidden | whether the shell command options may run programs (the sample file forbids it) |
[Permitted Paths] | read = dir | files in that directory may be read |
read* = dir | the same, with its sub-directories | |
read+write = dir | files there may be read and written | |
read+write* = dir | the same, with sub-directories |
A directory with spaces is quoted. Paths may be relative (. is the current directory). %INSTALLDIR% stands for the install directory of the data files and %HOME% for the home directory. A path in the system file must also be written in the user file. When the program finds no povray.conf it says "I/O restrictions are disabled". The sample file allows reading the include and scenes folders and the home directory, and reading and writing /tmp and the current directory.
povray.ini
The default INI file holds the options a user wants on every run, above all Library_Path lines that point at the include folder. The program reads exactly one default file, the first that exists in this order:
- the file named by
$POVINI; ./povray.iniin the current directory;$HOME/.povray/3.8/povray.ini;povray.iniin the system configuration directory;- the old files
$HOME/.povrayrcand the older system file.
If none is found the program prints "cannot open an INI file, adding default library path" and adds the include folder of its installation. The sample povray.ini of the distribution sets Width = 800, Height = 600, Bounding_Threshold = 3, Display=On, Verbose=On, three Library_Path lines (the data folder, its ini folder and its include folder; the installer fills in the real paths) and Output_to_File=true, Output_File_Type=N8.
The ini folder
The distribution carries 17 sample INI files in its ini folder. Read one by naming it on the command line, for instance povray res640.ini +Iscene.pov; each file sets only the options it needs. The tools they name (dta, pkzip, exists, tga2gif) are DOS-era programs that are not part of the Unix build, and some of the files use the substitution %p, which the current program does not know (it leaves it as written). They are examples to adapt.
| File | What it does |
|---|---|
povray.ini | the sample default INI file (see above) |
quickres.ini | 31 named sections of image size and anti-aliasing, from [160x120, No AA] to [1920x1080 16:9 AA 0.3], with and without anti-aliasing (AA 0.3 means Antialias_Threshold=0.3), some with mosaic preview (+SP16, +EP1) and some 16:9 or 5:4. Use quickres.ini[section]. |
res120.ini | Width=120, Height=90 |
res320.ini | 320 by 200 |
res640.ini | 640 by 480 |
res800.ini | 800 by 600 |
res1k.ini | 1024 by 768 |
low.ini | a quick test: Quality=4, 120 by 90 |
slow.ini | a careful final render: Quality=11, anti-aliasing on with threshold 0.1 and depth 3, jitter on with amount 0.5 |
pngflc.ini, pngfli.ini | render an animation to PNG frames (Output_File_Type=n) and, after the last frame, call dta to make an FLC or FLI animation file; skip the scene when that file already exists |
tgaflc.ini, tgafli.ini | the same with Targa frames (Output_File_Type=t) |
zipflc.ini, zipfli.ini | move each finished frame into a ZIP archive with pkzip (and skip frames that are already in it), then make the FLC or FLI file from the archive |
allstill.ini | batch settings for rendering many still scenes in one run: turns off pause, test abort and display, sets anti-aliasing and bounding, an output folder, and commands that skip finished scenes, log fatal errors and convert Targa to GIF |
allanim.ini | the same idea for animations: shell commands that skip a scene whose FLC file exists, test whether a frame is already in the archive, move each frame into it, and build the FLC at the end |
All of them carry the comment line "version 3.8 sample INI file". The animation files use Pre_*_Command and Post_*_Command with the return actions -q, -s and f (see the shell command section of INI options and switches).
Image formats
| Format | Written (+Fx) | Read by a scene | Notes |
|---|---|---|---|
| PNG | N (default), 1 to 16 bits, grey scale, alpha | png | stores the gamma; metadata with the program version, the date and the platform |
| Targa | T plain, C or T with Compression=1 RLE; alpha | tga | 8 bits per channel |
| JPEG | J | jpeg | lossy; Compression sets the quality; no chroma sub-sampling |
| PPM, PGM | P, with g for grey scale; Compression=0 for the text form | ppm, pgm | raw form by default; 1 to 16 bits |
| BMP | B | bmp | alpha uses an unofficial extension |
| OpenEXR | E, with alpha | exr | linear light, 16-bit floating point; needs the OpenEXR library in the build |
| Radiance HDR | H | hdr | linear light |
| GIF | not written | gif | read for image maps and height fields |
| IFF (ILBM) | not written | iff | also files with the extension .lbm |
| TIFF | not written | tiff | reading is marked experimental: the render reports it |
| POT | not written | pot | Fractint potential file, a GIF-like file with a 16-bit palette |
| system format | S where the build defines one | sys | platform dependent (BMP on Windows, PNG on macOS, Targa on Unix as the manual says) |
| DF3 | written by scenes (ARRAYS_WriteDF3 in arrays.inc) | density_file df3 | big-endian voxel grid, see File types and structure |
Writing a file with the extension of the type is the program's choice: it appends .png, .tga, .jpg and so on to the scene name. The text outputs (debug.out, stats.out and the others), the radiosity cache (.rca) and the continue-trace state file are written beside the image.
Front ends and editors
The ray tracer is the same everywhere; the programs differ in how they start it and show the result.
| Program | What it is |
|---|---|
| POV-Ray for Unix | the command-line program described above, with an optional preview window and a text-graphics preview, a benchmark mode, and shell scripts in the scripts folder: render_scene.sh (render one scene, with options taken from a comment in the scene file), render_anim.sh (render a scene as an animation), allscene.sh, allanim.sh and portfolio.sh (render all the sample scenes, all animations, the portfolio), runpov.sh and rerunpov.sh (render while saving all settings to rerun.ini, and render again from it). The Unix sources also have a kde_install.sh script that adds menu entries. |
| POV-Ray for Windows | a graphical front end that includes a text editor. The editor colours the language (keywords, comments, strings), completes keywords, and takes extra keywords from Ini/user-keywords.txt (one word per line; they affect only the editor). Scenes are rendered from the editor and shown in a preview window; the Tiles folder holds bitmaps that can tile the window background. Its Insert Menu folder holds code snippets (basic shapes, CSG, textures, patterns, cameras, lights, radiosity and so on) that the editor offers under an Insert menu; Ini/pvtools.ini defines an external tools menu. It uses .pov and .inc (and .ini, .mac, .mcr) as its file types and installs sample sounds and icons. Help is a compiled help file. Shell commands are off by default there. |
| POV-Ray for macOS | a graphical front end with the same ray tracer; the system image format S maps to PNG there. |
| Moray | a Windows modeller that exports scenes to POV-Ray. |
| KPovModeler | a modeller for KDE that edits scenes in the POV-Ray language and shows the objects as a tree. |
| Blender | has an exporter that writes POV-Ray scenes. |
| Editors in general | The scene is plain text, so any editor works. The .pov, .inc and .ini extensions are the ones editors associate with the language. |
The sample scenes
The distribution holds 403 sample scenes in its scenes folder, grouped by topic. Each group has an index page (advanced.htm, animations.htm, cameras.htm, incdemo.htm, interior.htm, language.htm, objects.htm, rad_sub.htm, textures.htm) and a previews folder with small pictures.
| Folder | .pov files | Content |
|---|---|---|
advanced | 44 | larger finished scenes (chess2.pov, landscape.pov, mtmand.pov, wineglass.pov) and sub-folders such as balcony, benchmark, teapot |
animations | 17 | one folder per animation that uses clock, with an INI file for each |
bsp | 1 | Tango.pov, a scene that benefits from the BSP bounding method |
camera | 27 | one scene per camera type, plus the mesh camera demos in mesh_camera |
incdemo | 66 | demos of the include files (colors.pov, shapes.pov, chars.pov, math.pov, strings.pov, screen.pov) and texture folders |
interior | 26 | media, fog, rainbows, sky spheres, attenuation, refraction |
language | 17 | language features such as macros, arrays, loops and functions |
lights | 14 | area, spot, cylindrical, parallel and shadowless lights, photons |
objectmods | 3 | object modifiers |
objects | 53 | one or more scenes for each object type |
output | 2 | dither_showcase.pov, gamma_showcase.pov |
portfolio | 22 | the pictures of the portfolio, rendered by portfolio.sh |
qtvr | 1 | a panorama |
radiosity | 9 | radiosity scenes |
subsurface | 1 | subsurface light transport |
templates | 22 | starting points for new scenes |
textures | 78 | textures, patterns, finishes, normals, pigments, maps |
A scene may carry a comment line of options within its first 50 lines (a // comment, a space, then options that start with + or -, for instance // +W800 +H600); render_scene.sh passes it to the program.
Building from source on Unix
The source tree is built with the usual GNU steps. The build needs a C++11 compiler, a make tool, a Bourne shell and the libraries Boost (1.38 or later), zlib, libpng, libjpeg and libtiff; OpenEXR and SDL are optional (for EXR files and the preview window). A source package that does not carry a ready configure script must first run cd unix/ ; ./prebuild.sh ; cd ../.
./configure COMPILED_BY="your name and contact" [--prefix=dir]
make
make check
sudo make install| Item | Meaning |
|---|---|
COMPILED_BY | who built the program. It is shown in the banner as the maker of an "unofficial version". An unofficial build accepts the word unofficial after #version (Versions 3.0 to 3.8). |
--prefix=dir | install tree (default /usr/local); the program goes to bin, the data files (include, scenes, INI files) to share/povray-3.8, the documentation to share/doc/povray-3.8, the configuration to etc/povray/3.8. Installing also copies the configuration files to ~/.povray/3.8 of the installing user. |
--with-x, --without-x | use the X Window System for the display or not |
--with-boost=dir, --with-zlib, --with-libpng, --with-libjpeg, --with-libtiff, --with-openexr, --with-libsdl | where to find the libraries, or leave one out (--without-...) |
CXX, CXXFLAGS, LDFLAGS, LIBS | compiler and flags |
make check | builds and runs a short test render |
make uninstall, make clean, make dist | remove an installation, clean the build, make source archives |
The program can be built and run from the build tree without installing, but it then looks for its configuration files under /usr/local, which complicates finding the standard include files; install it, or give +L paths.
Not described
Known, not yet covered
- Reference: the Windows and macOS front ends were not run here, so their features are described from the files in the distribution (the Windows editor sources, Insert menu, INI and help files) and not from the program; the full configure option list (only the main options are given); the options of the helper scripts.
Unknown
- Reference: the exact feature set of Moray, KPovModeler and the Blender exporter in current versions was not checked against their own documentation; only what they are is stated.