POV file format: INI options and switches

The options of a render (image size, quality, anti-aliasing, animation, output file, text messages and so on) are not part of the scene file. They are set with INI files and on the command line, before the scene is parsed. Almost every option has two spellings: a name for an INI file (Width=640) and a switch for the command line (+W640). This page lists all of them, then the syntax of an INI file, the string substitutions of shell commands, and the order in which the sources are read. The language itself reads only a few of them (Declare and Clock show up in the scene, Version sets the language version).

How an option is written

Notation	Meaning
bool	For an INI option and for a switch with a parameter: `true`, `yes`, `on` or `1` turn it on; any other text turns it off. For a switch without a parameter: `+` turns it on and `-` turns it off.
int, float	A whole number or a number with a fraction. A switch takes it directly after the letters (`+W320`, `+A0.1`).
string, file	Text; a file name may be quoted when it holds spaces (`+I"my scene.pov"`).
file or bool	For the text stream options: `true` (or `yes`, `on`, `1`) sends the stream to a file with a default name, `false` (or `no`, `off`, `0`) stops it, and any other text is the file name.
`+` or `-`	The sign before a switch normally gives the same result. It matters for switches that are on/off switches (`+P` on, `-P` off), and a switch with an optional parameter keeps the parameter for later (`-A0.2` turns anti-aliasing off but sets the threshold).
case	Option names and switch letters are case-insensitive. File names are not.

Input, files and parsing

Option	Switch	Value	Default	Meaning
`Input_File_Name`	`+Ifile`	file	none	The scene file (`.pov`). A plain argument that ends in `.pov` has the same effect.
`Include_Header`	`+HIfile`	file	none	An include file that is read before the first line of every scene, as if the scene began with `#include` of it. Useful for a set of defaults.
`Include_Ini`	(a bare file name)	file	none	Reads another INI file at this point. An argument or line that is not an option and does not end in `.pov` or a path separator is taken as an INI file. `name[Section]` reads only that section (see below). On the command line, a section name that holds spaces must be quoted a second time inside the shell quotes (`'"quickres.ini[320x240, AA 0.3]"'`).
`Library_Path`	`+Ldir`	directory	none	Adds a directory where include files, images and other files are looked for. Repeated uses add to the list; the same directory twice counts once. An argument that ends in a path separator is also a library path. The current directory is always searched first (File types and structure).
`Declare`	none	`Id`=`value`	none	Declares an identifier before the scene is read, like `#declare Id = value;`. A number is declared as a float. A value in double quotes is declared as a string (the source accepts it; the manual names only floats). Test it in the scene with `#ifdef`.
`Version`	`+MVn.n`	float	none	The language version a scene is read as when it has no `#version` line. Without it, such a scene is read as 3.62. See Versions 3.0 to 3.8.
`Create_Ini`	`+GIfile`	file or bool	off	Writes an INI file that holds every option that was set, after all INI files and switches have been read. `true` uses the scene name with `.ini`; `false` turns an earlier setting off. Rerunning with that file repeats the render (also useful with `+C`).

#version 3.8;
#ifndef (RAD) #declare RAD = 1; #end
global_settings {
  assumed_gamma 1.0
  #if (RAD)
    radiosity { }
  #end
}
camera { location <0, 1, -4> look_at 0 }
light_source { <5, 8, -6> rgb 1 }
sphere { 0, 1 pigment { rgb 1 } }

A scene that reads an option from outside. povray +Ishow.pov Declare=RAD=0 (or the line Declare=RAD=0 in an INI file) turns radiosity off; without it RAD is 1.

Image size and region

Option	Switch	Value	Default	Meaning
`Width`	`+Wn`	int	160	Image width in pixels.
`Height`	`+Hn`	int	120	Image height in pixels. As the only switch on the command line, `+H` shows the help screen.
`Start_Column`	`+SCn`	float	1	First column rendered. A value of 1 or more is a pixel number; a value below 1 is a fraction of the width (`0.75` starts three quarters across).
`End_Column`	`+ECn`	float	image width	Last column rendered; same rule.
`Start_Row`	`+SRn`	float	1	First row rendered (counted from the top); same rule.
`End_Row`	`+ERn`	float	image height	Last row rendered; same rule. The output is always a full-size image; the rows and columns that were not rendered are black.
`Max_Image_Buffer_Memory`	`+MIn`	int (MB)	128	RAM for the image buffer. A larger image uses a file-backed buffer.

Output file

Option	Switch	Value	Default	Meaning
`Output_To_File`	`+F`, `-F`	bool	on	Write an image file. `+Fx` sets the type and turns writing on; `-Fx` sets the type but turns writing off.
`Output_File_Type`	`+Fxn`	letter	N (PNG)	One letter: `N` PNG, `T` Targa, `C` compressed (RLE) Targa, `J` JPEG, `P` PPM, `B` BMP, `E` OpenEXR, `H` Radiance HDR, `S` system format (only where the build has one). A trailing `g` asks for grey-scale output, a number is the bits per colour: `+FN16`, `+FPg8`.
`Output_File_Name`	`+Ofile`	file	scene name plus the type extension	Output file. A directory (ending in a separator) keeps the default name and writes in it. `-` or `stdout` writes the image to standard output. In an animation the frame number is added to the name.
`Bits_Per_Color`	`+Fxn`	int 1 to 16	8	Bits per colour channel. PNG and PPM store the depth chosen.
`Bits_Per_Colour`	none	int 1 to 16	8	The British spelling of `Bits_Per_Color`; the program accepts both and writes the second form.
`Output_Alpha`	`+UA`	bool	off	Write an alpha channel (TGA, PNG, OpenEXR; BMP uses an unofficial extension). Areas where the background shows are transparent. The background needs a `filter` or `transmit` value for this to work.
`Grayscale_Output`	`+Fxg`	bool	off	Write grey scale (PNG and PPM only): 0.3 red + 0.59 green + 0.11 blue. Useful for height fields.
`Greyscale_Output`	none	bool	off	The same option, British spelling.
`Compression`	none	int 0 to 255	not set	Format dependent. JPEG: quality 2 to 100 (0 or 1 gives the default 85). PPM: `0` writes the plain (text) form. Targa: `Output_File_Type=T` with `Compression=1` writes the RLE form.
`Dither`	`+TH`	bool	off	Dither the output file. Ignored for JPEG and OpenEXR.
`Dither_Method`	`+THxx`	code	BN	Ordered: `B2`, `B3`, `B4` (Bayer 2x2, 3x3, 4x4), `BN` (blue noise), `BNX` (blue noise, inverted for red and blue). Error diffusion: `AT` Atkinson, `BK` Burkes, `D1` one-dimensional, `D2` Sierra Lite, `FS` Floyd-Steinberg, `JN` Jarvis-Judice-Ninke, `S2` two-row Sierra, `S3` Sierra, `ST` Stucki.
`File_Gamma`	none	float or `sRGB`, `BT709`, `BT2020`	sRGB	The transfer function of the output file. For file types without a gamma rule it is the display gamma to pre-correct for; for PNG it is the stored decoding gamma; OpenEXR and HDR are always linear. PPM output uses BT709 unless set. A value of 1 means neutral.
`Buffer_Output`	none	any	none	Removed. Still accepted, with a warning that it is no longer used.
`Buffer_Size`	none	any	none	Removed. Still accepted, with the same warning.
`Create_Histogram`	none	any	none	Removed (the CPU histogram no longer exists). Accepted with a warning.
`Histogram_Name`	none	any	none	Removed; accepted with a warning.
`Histogram_Grid_Size`	none	any	none	Removed; accepted with a warning.
`Histogram_Type`	none	any	none	Removed; accepted with a warning.

Display

Option	Switch	Value	Default	Meaning
`Display`	`+D`, `-D`	bool	off (on in the Windows build)	Show the image while it renders (a window, or ASCII art on a text console).
`Display_Gamma`	none	float or `sRGB`, `BT709`, `BT2020`	sRGB (about 2.2)	The gamma of the display. Set it once per computer.
`Video_Mode`	`+Dx`	one character	none	Deprecated; kept for old INI files. A character that the display driver interpreted.
`Palette`	`+Dxy`	one character	none	Deprecated, like `Video_Mode`.
`Pause_When_Done`	`+P`, `-P`	bool	off	Keep the display open until a key is pressed.
`Verbose`	`+V`, `-V`	bool	on in the source (the manual says off)	Report the line and time of the render in the status stream.
`Draw_Vistas`	`+UD`	bool	off	Deprecated. Accepted and shown in the render summary; it has no effect.
`Preview_Start_Size`	`+SPn`	int, power of two	1	Mosaic preview: the block size of the first pass (a value that is not a power of two is lowered to the nearest one, at most 64).
`Preview_End_Size`	`+EPn`	int, power of two	1	The block size of the last pass before the final 1 by 1 pass. At most `Preview_Start_Size`. Below 8 is not recommended. The final pass always runs at 1 by 1 and nothing is written to the file earlier.
`Test_Abort`	`+X`, `-X`	bool	off	Deprecated. Poll the keyboard for an abort key; an abort exits with code 2.
`Test_Abort_Count`	`+Xn`	int	none	Deprecated. Poll every `n` pixels or lines.

Animation

A render becomes an animation when Final_Frame is more than 0. The scene is parsed again for every frame and the built-in clock runs from Initial_Clock to Final_Clock.

Option	Switch	Value	Default	Meaning
`Clock`	`+Kn.n`	float	0	Sets `clock` to a fixed value for a single render (the external animation loop: you start the program once per frame).
`Initial_Frame`	`+KFIn`	int	1	First frame number.
`Final_Frame`	`+KFFn`	int	none	Last frame number. Any value above 0 starts the internal animation loop. The frame number in the file names is padded with zeros to the width of this number.
`Initial_Clock`	`+KIn.n`	float	0.0	Clock value of the first frame.
`Final_Clock`	`+KFn.n`	float	1.0	Clock value of the last frame. Frames between are interpolated.
`Subset_Start_Frame`	`+SFn`, `+SF0.n`	float	first frame	First frame actually rendered. A value between 0 and 1 is a fraction of the animation. The clock values are unchanged.
`Subset_End_Frame`	`+EFn`, `+EF0.n`	float	last frame	Last frame actually rendered; same rule.
`Frame_Step`	`+STPn`	int	1	Render every `n`-th frame (positive only). Not available in the scene.
`Cyclic_Animation`	`+KC`, `-KC`	bool	off	Adjusts the final clock so that the last frame does not repeat the first one.
`Clockless_Animation`	`+KLA`	bool	off	Experimental. Renders the cameras of the scene one after the other as the frames (needs at least two cameras).
`Field_Render`	`+UF`	bool	off	Deprecated. Renders alternate frames as even or odd fields.
`Odd_Field`	`+UO`	bool	off	Deprecated. Start with the odd field.

During an animation the program declares these floats for the scene, so a scene can read them: initial_frame, final_frame, frame_number, initial_clock, final_clock and clock_delta (the clock step between two frames). The frame step is not declared.

Resuming

Option	Switch	Value	Default	Meaning
`Continue_Trace`	`+C`, `-C`	bool	off	Continue an interrupted render from its output file. The file holds the image size, so that overrides the size options. The other options must match the first run.
`Create_Continue_Trace_Log`	`+CC`, `-CC`	bool	on	Keep the state file that `+C` needs.

Tracing, quality and threads

Option	Switch	Value	Default	Meaning
`Quality`	`+Qn`	int 0 to 9 (a higher value is lowered to 9)	9	The level turns features on (the flags of the program): 0 and 1 ambient light only; up to 5 quick colours (no real textures); 4 and up shadows; 5 and up area lights; 6 and up refraction; 8 and up reflection and normals (bump patterns); 9 media, radiosity, photons and subsurface scattering. The manual says photons start at 6; the program turns them on at 9.
`Work_Threads`	`+WTn`	int	number of cores detected, 4 if unknown; at most 512	Number of render threads.
`Render_Block_Size`	`+BSn`	int, at least 4	32	Edge of the square block handed to a thread. A smaller value than 4 is refused; a value above the image size is clipped.
`Render_Pattern`	`+RPn`	int 0 to 5	0	Order of the blocks: 0 left to right and down; 1 top to bottom and across; 2 a row from both corners towards the centre; 3 from the centre outwards, first sideways; 4 and 5 are 2 and 3 with rows and columns swapped. It changes only the look of the preview.
`Render_Block_Step`	`+RSn`	int, 1 or more	1	Jump over blocks between two rendered ones; the program lowers a step that would leave blocks unrendered.
`Stochastic_Seed`	`+SSn`	int	0 (derived from the time)	Seed for the random numbers of stochastic features (at present anti-aliasing method 3). A fixed value gives repeatable noise.
`Real_Time_Raytracing`	`+RTR`	bool	off	Beta. A real-time render loop (turns file output off).
`High_Reproducibility`	`+HR`	bool	off	Makes radiosity renders repeatable with several threads, at some cost. Experimental.

Bounding

Option	Switch	Value	Default	Meaning
`Bounding`	`+MB`, `-MB`	bool	on	Use the bounding hierarchy to skip objects a ray cannot hit.
`Bounding_Threshold`	`+MBn`	int 1 to 32767	3	Minimum number of objects for which bounding is used.
`Bounding_Method`	`+BMn`	int 1 or 2	1	1 is the bounding volume hierarchy; 2 is the binary space partition (beta; it can be faster for a scene with very many objects, slower otherwise).
`BSP_MaxDepth`	none	int	0 (the program uses 128)	Tuning of the BSP tree. A value of 0 means the internal default.
`BSP_BaseAccessCost`	none	float	0 (1.0)	BSP tuning.
`BSP_ChildAccessCost`	none	float	0 (1.5)	BSP tuning.
`BSP_ISectCost`	none	float	0 (150.0)	BSP tuning (the option name is read without regard to case, so `BSP_IsectCost` works too).
`BSP_MissChance`	none	float 0 to below 1	0 (0.2)	BSP tuning. Using any of these options makes the render print a warning that they may change in future versions.
`Remove_Bounds`	`+UR`	bool	on	Remove hand-made `bounded_by` objects when the automatic bounding is better. Turn it off for old scenes that used bounding where clipping was meant.
`Split_Unions`	`+SU`	bool	off	Also split unions that have a manual bound.
`Light_Buffer`	`+UL`	bool	on	Deprecated; no effect.
`Vista_Buffer`	`+UV`	bool	on	Deprecated; no effect.

Anti-aliasing

Anti-aliasing shoots more than one ray into a pixel. Selecting a method does not turn it on; Antialias does.

Option	Switch	Value	Default	Meaning
`Antialias`	`+A`, `-A`	bool	off	`+An.n` turns it on and sets the threshold.
`Sampling_Method`	`+AMn`	int 1 to 3	1	1: adaptive, non-recursive (a pixel whose difference to its left or upper neighbour is above the threshold gets a grid of extra samples). 2: adaptive and recursive (starts with the four corners, subdivides). 3: stochastic oversampling that stops where the statistics are good enough; the method shoots at most 4 times the depth rays.
`Antialias_Threshold`	`+An.n`	float 0 to 1	0.3	For methods 1 and 2: the difference (sum of the absolute rgb differences) that triggers extra samples. 0 samples every pixel. For method 3: the acceptable sampling error.
`Antialias_Depth`	`+Rn`	int 1 to 9	3	Method 1: a grid of `n` by `n` samples. Method 2: the number of subdivisions. Method 3: limits the rays per pixel.
`Antialias_Confidence`	`+ACn.n`	float 0 to 1	0.9	Method 3 only: how sure the program must be that a pixel is good.
`Antialias_Gamma`	`+AGn.n`	float, or a name as for `File_Gamma`	2.5	The gamma applied before pixels are compared, so that dark areas are sampled enough. Only the comparison is affected. 1.0 compares linear values.
`Jitter`	`+J`, `-J`	bool	on	Move the sub-samples randomly a little. Method 3 always jitters.
`Jitter_Amount`	`+Jn.n`	float 0 to 1	1.0	Size of the jitter. 0 or less turns it off. Jitter changes from frame to frame, so avoid it in animations.

Radiosity files

The settings of the radiosity calculation itself are in the scene (Global settings, radiosity and photons). These options deal with the cache file.

Option	Switch	Value	Default	Meaning
`Radiosity_File_Name`	`+RFfile`	file	scene name with `.rca`	The radiosity cache file.
`Radiosity_From_File`	`+RFI`	bool	off	Read the cache at the start.
`Radiosity_To_File`	`+RFO`	bool	off	Write new samples to the cache. With both, new samples are appended; with only this one an existing file is overwritten.
`Radiosity_Vain_Pretrace`	`+RVP`, `-RVP`	bool	on	When on, the pretrace does every computation, so it also works as a coarse preview. Off skips the diffuse, highlight and iridescence work that does not contribute samples; the preview then looks odd.

Shell commands

The program can run another program at fixed points of a render. These options can only be given in an INI file, never as switches. A file named povray.conf can forbid shell commands (see Tooling).

Option	Value	Default	When it runs, and what its return does
`Pre_Scene_Command`	string	none	Once before everything.
`Pre_Frame_Command`	string	none	Before each frame, before the scene is parsed.
`Post_Frame_Command`	string	none	After each frame.
`Post_Scene_Command`	string	none	Once after the last frame.
`User_Abort_Command`	string	none	When the user interrupts the render.
`Fatal_Error_Command`	string	none	When a fatal error stops the render.
`Pre_Scene_Return`, `Pre_Frame_Return`, `Post_Frame_Return`, `Post_Scene_Return`, `User_Abort_Return`, `Fatal_Error_Return`	one letter	`I`	What to do with the exit code of the command of the same name. A minus sign or `!` before the letter reverses the test (act when the code is zero).

Letter	Action
`I`	ignore the code (default)
`S`	skip one step: after `Pre_Frame_Command` skip that frame; after `Pre_Scene_Command` skip all frames but still run `Post_Scene_Command`; after `Post_Frame_Command` skip the remaining frames
`A`	skip all steps: as `S` after a frame command; after `Pre_Scene_Command` behave as `Q`
`Q`	quit at once, as if the program had not run (exit code 0, no further commands)
`U`	make it a user abort (exit code 2)
`F`	make it a fatal error (exit code 1)

A user abort command with F turns the abort into a fatal error; a Fatal_Error_Command never changes the outcome. The program itself exits with 0 on success, 1 on a fatal error and 2 on a user abort.

String substitution

The command string may hold these codes. They are replaced before the command runs.

Code	Replaced by
`%o`	the output file name with extension and frame number (without a number in the scene-level commands)
`%s`	the scene name: the input name without directory and extension
`%n`	the frame number
`%k`	the clock value (six decimals)
`%h`	the image height in pixels
`%w`	the image width in pixels
`%%`	one percent sign (any other `%` pair is left as written)

Post_Frame_Command=zip -m %s %o
Post_Frame_Return=S
Post_Scene_Command="convert -delay 4 %s*.png %s.gif"

Three lines of an INI file. The command values are read raw (quotes, and a ; or # inside quotes, are kept).

Order of a render with shell commands

All INI files and switches are read once. The text streams are opened and Create_Ini is written. Pre_Scene_Command runs. For each frame: Pre_Frame_Command, then parse, render and close the output, then Post_Frame_Command. After the last frame comes Post_Scene_Command. A non-animated scene is the same without the loop.

Text output

The program writes its messages to seven streams: banner, debug, fatal, render, statistics, status and warning. The banner and the status stream cannot be turned off or sent to a file. The five others have a switch for the console and a switch for a file.

Option	Switch	Value	Default	Meaning
`Debug_Console`	`+GD`, `-GD`	bool	on	Show the debug stream (`#debug` text and developer messages) on the console.
`Fatal_Console`	`+GF`, `-GF`	bool	on	Show fatal error text.
`Render_Console`	`+GR`, `-GR`	bool	on	Show the summary of the options used.
`Statistic_Console`	`+GS`, `-GS`	bool	on	Show the render statistics.
`Warning_Console`	`+GW`, `-GW`	bool	on	Show warnings.
`All_Console`	`+GA`, `-GA`	bool	sets the five above	Turn all five console streams on or off at once.
`Debug_File`	`+GDfile`	file or bool	off	Copy the debug stream to a file (default name `debug.out`).
`Fatal_File`	`+GFfile`	file or bool	off	Default name `fatal.out`.
`Render_File`	`+GRfile`	file or bool	off	Default name `render.out`.
`Statistic_File`	`+GSfile`	file or bool	off	Default name `stats.out`.
`Warning_File`	`+GWfile`	file or bool	off	Default name `warning.out`.
`All_File`	`+GAfile`	file or bool	off	One file for all five (default `alltext.out`). Do not give two streams the same file.
`Append_File`	`+GP`, `-GP`	bool	off	Append to the stream files instead of overwriting them. The second and later frames of an animation append in any case. A separator line marks the start of each render.
`Warning_Level`	`+WLn`	int 0 to 9	9 (the manual says 10; the program lowers values above 9)	0 turns off all warnings; 5 turns off the warnings about language versions; 9 shows all.

A switch with a file name sets both: +GWwarn.txt turns Warning_Console on and Warning_File to that file; -GWwarn.txt sends the stream to the file only. These options take effect after the INI files have been read, and an error in an INI file stops its reading at that point.

Help and version (Unix)

Switch	Meaning
`-h`, `-help`, `--help`, `-?`	Show the usage text and exit. (`+H` with nothing else on the line does the same.)
`-version`, `--version`, `--V`	Show the program version.
`--generation`	Show the short version number.
`-benchmark`, `--benchmark`	Run the built-in benchmark (it accepts `+WTn` and `+Ldir`).

INI file syntax

An INI file is a text file, read line by line. The unit is a line; the rules are the same for a file, for the arguments of the command line (an argument that looks like Name=value is an INI option) and for povray.ini.

Form	Meaning
`Name=value`	One option on a line, with optional spaces round the equals sign. A value ends at white space, a comma, `;` or `#`; use single or double quotes for a value that holds those characters. For a file name with spaces and no quotes the program looks ahead and keeps the whole text up to a comment or the end of the line.
`; text`, `# text`	A comment from that mark to the end of the line. It can follow an option.
`+W640`, `-D`	A command-line switch written on a line of its own. INI files and the command line share one table, so the two styles can be mixed.
`[Section]`	Starts a named section. Its options are ignored unless the file is read as `name.ini[Section]` (in an `Include_Ini`, a bare argument or a switch). The options above the first section line always apply.
`file.ini`	A line that is neither an option nor a switch is a file name: an INI file to read (`Include_Ini`), a scene file if it ends in `.pov`, or a library path if it ends in a path separator.
unknown name	An unknown option is an error that stops the reading of that file. The text “Cannot continue to process INI file ... due to a parse error in line `n`” gives the line.

; settings for quick previews
Width=8
Height=8
Quality=0
Antialias=off
Output_To_File=off
Declare=RAD=0
Library_Path="include"

[Final]
Width=16
Height=16
Antialias=on
Antialias_Threshold=0.2

An INI file with a named section. povray io1.ini +Iscene.pov renders the preview (8 by 8, no anti-aliasing); povray "io1.ini[Final]" +Iscene.pov reads the top lines and then the lines of [Final] (16 by 16, threshold 0.2). Checked with the program of the 3.8 source tree.

Where the settings come from, and the order

On Unix the program first reads povray.conf (the I/O restrictions, not options).
Then exactly one default INI file is read: the file named by the environment variable POVINI; else ./povray.ini in the current directory; else the user file $HOME/.povray/3.8/povray.ini; else the system file povray.ini in the configuration directory chosen at build time; else the older $HOME/.povrayrc and the older system file. If none exists, the program says so and uses <installation>/include as the only library path.
The environment variable POVINC adds one more library path.
The command-line arguments are processed from left to right, so a later setting replaces an earlier one, and a switch on the command line replaces the value from the INI file. Lists (Library_Path, Declare, Include_Ini) add up instead.

The Windows build reads its INI files from the program's folder in a similar way; see the Windows documentation of the distribution.

Not described

Known, not yet covered

Reference: Display and Verbose defaults differ between the manual and the front end code as noted in the tables; the Windows and macOS only switches (for example the ones of the Windows front end) are not listed.

.POV File Format – INI options and switches