Early versions of POV-Ray had no system of automatic bounding or spatial sub-division to speed up ray-object intersection tests. Users had to manually create bounding boxes to speed up the rendering. POV-Ray 3.0 has more sophisticated automatic bounding than any previous version. In many cases the manual bounding on older scenes is slower than the new automatic systems. Therefore POV-Ray removes manual bounding when it knows it will help. In rare instances you may want to keep manual bounding. Some older scenes incorrectly used bounding when they should have used clipping. If POV-Ray removes the bounds in these scenes the image will not look right. To turn off the automatic removal of manual bounds you should specify Remove_Bounds =off or use -UR . The default is Remove_Bounds =on.

One area where the jury is still out is the splitting of manually bounded unions. Unbounded unions are always split into their component parts so that automatic bounding works better. Most users do not bound unions because they know that doing so is usually slower. If you do manually bound a union we presume you really want it bound. For safety sake we do not presume to remove such bounds. If you want to remove manual bounds from unions you should specify Split_Unions =on or use +SU . The default is Split_Unions =off.

Note that no + / - 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 CMD is a single line of text which is passed to the operating system to execute a program. For example

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

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 or extension removed. For example:

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

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 pkzip . You could do...

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

  1)  Process all INI file keywords and command line switches just once. 
  2)  Open any text output streams and do Create_INI if any.
  3)  Execute Pre_Scene_Command if any.
  4)  Loop through frames (or just do once on non-animation).
      a)  Execute Pre_Frame_Command if any.
      b)  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. 
      c)  Execute Post_Frame_Command if any.
      d)  Go back to 4 a until all frames are done.
  5)  Execute Post_Scene_Command if any.
  6)  Exit POV-Ray. 

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 4 a 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 that 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 also 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.

Note that no + / - 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:

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 isn't 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 doesn't 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. 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...

On return from any Fatal_Error_Command proceed with the fatal error no matter what. 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...

On return from a Pre_Scene_Command if there is an action triggered and you have specified...

On return from a Pre_Frame_Command if there is an action triggered and you have specified...

On return from a Post_Frame_Command if there is an action triggered and you have specified...

On return from any Post_Scene_Command if there is an action triggered and you have specified...