Documentation Talk:Reference Section 1.2

Grid Size

`Histogram_Grid_Size=` nn.mm	Set histogram grid to nn by mm
`+HS`nn.mm	Same as `Histogram_Grid_Size=`nn.mm

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.

Scene Parsing Options

POV-Ray reads in your scene file and processes it to create an internal model of your scene. The process is called parsing. As your file is parsed other files may be read along the way. This section covers options concerning what to parse, where to find it and what version specific assumptions it should make while parsing it.

Constant

Declare=IDENTIFIER=FLOAT Declares an identifier with a float value

You can now declare a constant in an INI file, and that constant will be available to the scene. Since INI file statements may also be laced on the command-line, you can therefore also declare on the command-line (though there is no switch for it).

  Declare=MyValue=24

This would be the same as a #declare MyValue=24; in a scene file. The value on the right-hand side must be a constant float value.

A possible use could be switching off radiosity or photons from commandline:

--in INI-file / on command-line

Declare=RAD=0

--in scenefile

global_settings {
  #if (RAD)
    radiosity {
    ...
    }
#end
}

Input File Name

`Input_File_Name=`file	Sets input file name to file
`+I`file	Same as `Input_File_Name=`file

Note: there may be no space between +I and file.

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.

Note: as per version 3.5 you can now specify a POV file on the command-line without the use of the +i switch (i.e. it works the same way as specifying an INI file without a switch), the POV file then should be the last on the commandline.

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.

type ANYSCENE.POV | povray +I-

Include File Name

`Include_Header=`file	Sets primary include file name to file
`+HI`file	Same as `Include_Header=`file

This option allows you to include a file as the first include file of a scene file. You can for example use this option to always include a specific set of default include files used by all your scenes.

Library Paths

`Library_Path=`path	Add path to list of library paths
`+L`path	Same as `Library_Path=`path

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

Library_Path=c:\povray3\include

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 twenty unique paths may be specified. If you specify the exact same path twice it is only counted once. The current directory will be searched first followed by the indicated library directories in the order in which you specified them.

Language Version

`Version=`n.n	Set initial language compatibility to version n.n
`+MV`n.n	Same as `Version=`n.n

As POV-Ray has evolved from version 1.0 through to today we have made every effort to maintain some amount of backwards compatibility with earlier versions. Some old or obsolete features can be handled directly without any special consideration by the user. Some old or obsolete features can no longer be handled at all. However some old features can still be used if you warn POV-Ray that this is an older scene. In the POV-Ray scene language you can use the #version directive to switch version compatibility to different settings. See section "The #version Directive" for more details about the language version directive. Additionally you may use the Version=n.n option or the +MVn.n switch to establish the initial setting. For example one feature introduced in 2.0 that was incompatible with any 1.0 scene files is the parsing of float expressions. Setting Version=1.0 or using +MV1.0 turns off expression parsing as well as many warning messages so that nearly all 1.0 files will still work. Naturally the default setting for this option is the current version number.

Note: some obsolete or re-designed features are totally unavailable in the current version of POV-Ray REGARDLES OF THE VERSION SETTING. Details on these features are noted throughout this documentation.

Shell-out to Operating System

`Pre_Scene_Command=`s	Set command before entire scene
`Pre_Frame_Command=`s	Set command before each frame
`Post_Scene_Command=`s	Set command after entire scene
`Post_Frame_Command=`s	Set command after each frame
`User_Abort_Command=`s	Set command when user aborts POV-Ray
`Fatal_Error_Command=`s	Set command when POV-Ray has fatal error

Note: no + or - switches are available for these options. They cannot be used from the command line. They may only be used from INI files.

POV-Ray offers you the opportunity to shell-out to the operating system at several key points to execute another program or batch file. Usually this is used to manage files created by the internal animation loop however the shell commands are available for any scene. The string s is a single line of text which is passed to the operating system to execute a program. For example

Post_Scene_Command=tga2gif -d -m myfile

would use the utility tga2gif with the -D and -M parameters to convert myfile.tga to myfile.gif after the scene had finished rendering.

Note: individual platforms may provide means of preventing shell-outs from occurring. For example, the Windows version provides a menu command to turn shell-outs off (which is the default setting for that platform). The reason for this (along with file I/O restrictions) is to attempt to prevent untrusted INI files from doing harm to your system.

String Substitution in Shell Commands

It could get cumbersome to change the Post_Scene_Command every time you changed scene names. POV-Ray can substitute various values into a command string for you. For example:

Post_Scene_Command=tga2gif -d -m %s

POV-Ray will substitute the %s with the scene name in the command. The scene name is the Input_File_Name or +I setting with any drive, directory and extension removed. For example:

Input_File_Name=c:\povray3\scenes\waycool.pov

is stripped down to the scene name waycool which results in...

Post_Scene_Command=tga2gif -d -m waycool

In an animation it may be necessary to have the exact output file name with the frame number included. The string %o will substitute the output file name. Suppose you want to save your output files in a zip archive using the utility program pkzip. You could do...

Post_Frame_Command=pkzip -m %s %o

After rendering frame 12 of myscene.pov POV-Ray would shell to the operating system with

pkzip -m myscene mysce012.tga

The -M switch in pkzip moves mysce012.tga to myscene.zip and removes it from the directory. Note that %o includes frame numbers only when in an animation loop. During the Pre_Scene_Command and Post_Scene_Command there is no frame number so the original, unnumbered Output_File_Name is used. Any User_Abort_Command or Fatal_Error_Command not inside the loop will similarly give an unnumbered %o substitution.

Here is the complete list of substitutions available for a command string.

`%o`	Output file name with extension and embedded frame number if any
`%s`	Scene name derived by stripping path and ext from input name
`%n`	Frame number of this frame
`%k`	Clock value of this frame
`%h`	Height of image in pixels
`%w`	Width of image in pixels
`%%`	A single % sign.

Shell Command Sequencing

Here is the sequence of events in an animation loop. Non-animated scenes work the exact same way except there is no loop.

Process all INI file keywords and command line switches just once.
Open any text output streams and do Create_INI if any.
Execute Pre_Scene_Command if any.
Loop through frames (or just do once on non-animation).
1. Execute Pre_Frame_Command if any.
2. Parse entire scene file, open output file and read settings, turn on display, render the frame, destroy all objects, textures etc., close output file, close display.
3. Execute Post_Frame_Command if any.
4. Repeat above steps until all frames are done.
Execute Post_Scene_Command if any.
Finish

If the user interrupts processing the User_Abort_Command, if any, is executed. User aborts can only occur during the parsing and rendering parts of step (4b) above. If a fatal error occurs that POV-Ray notices the Fatal_Error_Command, if any, is executed. Sometimes an unforeseen bug or memory error could cause a total crash of the program in which case there is no chance to shell out. Fatal errors can occur just about anywhere including during the processing of switches or INI files. If a fatal error occurs before POV-Ray has read the Fatal_Error_Command string then obviously no shell can occur.

Note: the entire scene is re-parsed for every frame. Future versions of POV-Ray may allow you to hold over parts of a scene from one frame to the next but for now it starts from scratch every time.

Note: that the Pre_Frame_Command occurs before the scene is parsed. You might use this to call some custom scene generation utility before each frame. This utility could rewrite your .pov or .inc files if needed. Perhaps you will want to generate new .gif or .tga files for image maps or height fields on each frame.

Shell Command Return Actions

`Pre_Scene_Return=`s	Set pre scene return actions
`Pre_Frame_Return=`s	Set pre frame return actions
`Post_Scene_Return=`s	Set post scene return actions
`Post_Frame_Return=`s	Set post frame return actions
`User_Abort_Return=`s	Set user abort return actions
`Fatal_Error_Return=`s	Set fatal return actions

Note: that no + or - switches are available for these options. They cannot be used from the command line. They may only be used from INI files.

Most operating systems allow application programs to return an error code if something goes wrong. When POV-Ray executes a shell command it can make use of this error code returned from the shell process and take some appropriate action if the code is zero or non-zero. POV-Ray itself returns such codes. It returns 0 for success, 1 for fatal error and 2 for user abort.

The actions are designated by a single letter in the different ..._Return=s options. The possible actions are:

`I`	ignore the code
`S`	skip one step
`A`	all steps skipped
`Q`	quit POV-Ray immediately
`U`	generate a user abort in POV-Ray
`F`	generate a fatal error in POV-Ray

For example if your Pre_Frame_Command calls a program which generates your height field data and that utility fails then it will return a non-zero code. We would probably want POV-Ray to abort as well. The option Pre_Frame_Return=F will cause POV-Ray to do a fatal abort if the Pre_Frame_Command returns a non-zero code.

Sometimes a non-zero code from the external process is a good thing. Suppose you want to test if a frame has already been rendered. You could use the S action to skip this frame if the file is already rendered. Most utilities report an error if the file is not found. For example the command...

pkzip -V myscene mysce012.tga

tells pkzip you want to view the catalog of myscene.zip for the file mysce012.tga. If the file is not in the archive pkzip returns a non-zero code.

However we want to skip if the file is found. Therefore we need to reverse the action so it skips on zero and does not skip on non-zero. To reverse the zero vs. non-zero triggering of an action precede it with a "-" sign (note a "!" will also work since it is used in many programming languages as a negate operator).

Pre_Frame_Return=S will skip if the code shows error (non-zero) and will proceed normally on no error (zero). Pre_Frame_Return=-S will skip if there is no error (zero) and will proceed normally if there is an error (non-zero).

The default for all shells is I which means that the return action is ignored no matter what. POV-Ray simply proceeds with whatever it was doing before the shell command. The other actions depend upon the context. You may want to refer back to the animation loop sequence chart in the previous section "Shell Command Sequencing". The action for each shell is as follows.

On return from any User_Abort_Command if there is an action triggered...

...and you have specified...	...then POV-Ray will..
`F`	Then turn this user abort into a fatal error. Do the `Fatal_Error_Command`, if any. Exit POV-Ray with error code 1.
`S`, `A`, `Q`, or `U`	Then proceed with the user abort. Exit POV-Ray with error code 2.

On return from any Fatal_Error_Command then POV-Ray will proceed with the fatal error no matter what. It will exit POV-Ray with error code 1.

On return from any Pre_Scene_Command, Pre_Frame_Command, Post_Frame_Command or Post_Scene_Commands if there is an action triggered...

...and you have specified...	...then POV-Ray will...
`F`	...turn this user abort into a fatal error. Do the `Fatal_Error_Command`, if any. Exit POV-Ray with error code 1.
`U`	...generate a user abort. Do the `User_Abort_Command`, if any. Exit POV-Ray with an error code 2.
`Q`	..quit POV-Ray immediately. Acts as though POV-Ray never really ran. Do no further shells, (not even a `Post_Scene_Command`) and exit POV-Ray with an error code 0.

On return from a Pre_Scene_Command if there is an action triggered...

...and you have specified...	...then POV-Ray will...
`S`	...skip rendering all frames. Acts as though the scene completed all frames normally. Do not do any `Pre_Frame_Command` or `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip step #4.
`A`	...skip all scene activity. Works exactly like `Q` quit. On the earlier chart this means skip to step #6. Acts as though POV-Ray never really ran. Do no further shells, (not even a `Post_Scene_Command`) and exit POV-Ray with an error code 0.

On return from a Pre_Frame_Command if there is an action triggered...

...and you have specified...	...then POV-Ray will...
`S`	...skip only this frame. Acts as though this frame never existed. Do not do the `Post_Frame_Command`. Proceed with the next frame. On the earlier chart this means skip steps (4b) and (4c) but loop back as needed in (4d).
`A`	...skip rendering this frame and all remaining frames. Acts as though the scene completed all frames normally. Do not do any further `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step (4) and proceed at step (5).

On return from a Post_Frame_Command if there is an action triggered...

...and you have specified...	...then POV-Ray will...
`S` or `A`	...skip all remaining frames. Acts as though the scene completed all frames normally. Do not do any further `Post_Frame_Commands`. Do the `Post_Scene_Command`, if any. Exit POV-Ray with error code 0. On the earlier chart this means skip the rest of step (4) and proceed at step (5).

On return from any Post_Scene_Command if there is an action triggered and you have specified S or A then no special action occurs. This is the same as I for this shell command.

Text Output

Text output is an important way that POV-Ray keeps you informed about what it is going to do, what it is doing and what it did. The program splits its text messages into 7 separate streams. Some versions of POV-Ray color-codes the various types of text. Some versions allow you to scroll back several pages of messages. All versions allow you to turn some of these text streams off/on or to direct a copy of the text output to one or several files. This section details the options which give you control over text output.