POV-Ray(1) Version 3.1g POV-Ray(1)NAME
povray, x-povray, s-povray - POV-Ray: The Persistence of Vision Ray
Tracer
SYNOPSISpovray [+iinput_file] [+ooutput_file] [+/-option...] [INI_file ...]
x-povray [+iinput_file] [+ooutput_file] [+/-option...] [INI_file ...]
s-povray [+iinput_file] [+ooutput_file] [+/-option...] [INI_file ...]
DESCRIPTION
POV-Ray is a free, full-featured ray tracer, written and maintained by
a team of volunteers on the Internet. On the Unix platform POV-Ray can
be either a text-mode only program (povray), or can optionally have
preview capabilities using the X Window System (x-povray). Under
Linux, POV-Ray can optionally use the SVGA library (s-povray) to pre‐
view renderings.
This manual page only lists the basic POV-Ray and Unix specific fea‐
tures and command-line options for this version of POV-Ray. For a com‐
plete description of the features of POV-Ray and its scene description
language, or for a better explanation of the meaning of the com‐
mand-line and INI file options, please consult the documentation that
should accompany all versions of POV-Ray. On some sites this will be
installed in /usr/local/lib/povray31. Some of the Unix specific fea‐
tures are:
Support for X Windows display automatically uses the best visual
class and deepest depth available. For visuals that do not sup‐
port 24 bits of color per pixel, Floyd-Steinberg error diffusion
dithering is used, along with a dynamically allocated and opti‐
mized palette to produce the best display possible with the cur‐
rent visual, depth, and available colormap.
ICCCM compliance for the X Windows version means that the pre‐
view window will behave like standard X Windows programs, commu‐
nicate properly with the window manager, and will accept the
standard command-line options. See X(1) for more information.
Support for SVGAlib display automatically detects the available
SVGA display modes to choose the size which best fits the ren‐
dered image. When rendering an image that is too large for the
current display, the displayed image is scaled to fit on the
screen. For displays that do not support true-color modes,
Floyd-Steinberg dithering is used.
ASCII graphics in the text-mode version allow a basic view of
the current rendering on text-only terminals.
An interrupt handler allows rendering to be interrupted in a
safe way, so that any data not currently written to disk will be
saved before exiting. Control-C or SIGINT will cause a user
abort, and save the current rendering, before exiting. See
kill(1) for more information.
Platform and architecture independent rendering means the same
scene will render in the same way on all computers and operating
systems (with the exception of the rendering speed, of course).
OPTIONS
Options can be specified with either a leading '+' or a leading '-'.
Many options are switches, meaning a '+' turns the option on, and a '-'
turns the option off. Generally, the INI file option for such switches
is bool. For other options, it doesn't matter if a '+' or a '-' is
used. Most options cannot have spaces in them so you should specify
+FN rather than +F N, and combining options is not allowed, so +SC is
very different from +S +C. Options are not case sensitive.
The command-line options are shown below with their corresponding INI
file options. If the same option is specified multiple times, whether
in INI files or on the command-line, the last such option overrides any
previous ones, with the exception of the +L or Library_Path option,
which is cumulative.
Parsing options:
I<input_file_name> or Input_File_Name=file
Specifies the input file to use. If the input file name is '-',
the scene description will be read from the standard input.
L<library_path> or Library_Path=path
Specifies a directory for to search for input files, include
files, fonts, and image maps, if the specified file is not in
the current directory.
MVn.n or Version=float
Treat scene files as if they were version n.n instead of the
current version. This may be overridden from within the scene
file.
SU or Split_Unions=bool
Split bounded CSG unions if children are finite. This allows
automatic bounding of CSG objects to take place.
UR or Remove_Bounds=bool
Remove unnecessary bounding objects. This allows automatic
bounding of older scene files to take place.
Output options:
H[01234567]
Display help on command-line options for section 0 through 7.
Hnn or Height=integer
The image should be nn pixels high.
Wnn or Width=integer
The image should be nn pixels wide.
SRnn or Start_Row=integer
Start the rendering at row nn from the top of the screen.
SR0.nn or Start_Row=float
Start the rendering nn percent from the top of the screen.
ERnn or End_Row=integer
End the rendering at row nn from the top of the screen.
ER0.nn or End_Row=float
End the rendering at nn percent from the top of the screen.
SCnn or Start_Column=integer
Start the rendering at column nn from the left of the screen.
SC0.nn or Start_Column=float
Start the rendering at nn percent from the left of the screen.
ECnn or End_Column=integer
End the rendering at column nn from the left of the screen.
EC0.nn or End_Column=float
End the rendering at nn percent from the left of the screen.
C or Continue_Trace=bool
Continue a previously interrupted trace.
P or Pause_When_Done=bool
If previewing, pause when the rendering is complete before clos‐
ing the window.
V or Verbose=bool
Output verbose status messages on the progress of the rendering.
X or Test_Abort=bool
Enable the 'q' and 'Q' keys to interrupt a rendering in
progress.
Xnn or Test_Abort_Count=integer
Only check every nn pixels for a user abort.
Output options - display related:
D[0][GHT] or Display=bool Palette=char
Display the rendering in progress, optionally specifying the
palette. The only valid X Windows palette option is G, which
forces grayscale preview. The X Windows palette is based on the
visual used, whether selected automatically by POV-Ray or via
the -visual option. SVGA options are T for 24-bit true-color,
and H for 15-bit high-color display, in addition to the default
256-color palette. To specify the palette, you must first spec‐
ify the display type (the second character, shown here as '0')
for compatibility reasons, even though it is ignored in Unix
versions.
Display_Gamma=float
Set the display gamma to the specified value.
SPnn or Preview_Start_Size=integer
Start mosaic preview with blocks nn pixels square.
EPnn or Preview_End_Size=integer
End mosaic preview with blocks nn pixels square.
UD or Draw_Vistas=bool
Draw vista rectangles before rendering.
Output options - file related:
Bnn or Buffer_Output=bool Buffer_Size=integer
Use an output buffer nn kilobytes in size.
F[CNPT][n] or Output_to_File=bool Output_File_Type=char
Store the rendered image using one of the available formats,
namely Compressed TGA, PNG, PPM, and TGA. PNG format supports
the n option to specify the number of bits per color, where 5 <=
n <= 16.
O<output_file> or Output_File_Name=file
Write the output to the file named output_file, or the standard
output if '-' is given as the output file name.
HT[CNPTX] or Histogram_Type=char
Create a CPU utilization histogram image in format x. Available
formats are Comma-separated values (CSV), PNG grayscale, PPM POV
heightfield, uncompressed TGA POV heightfield, or X for no his‐
togram generation.
HN<histogram_file_name> or Histogram_Name=file
Output the histogram to the specified file.
HSx.y or Histogram_Grid_Size=float
Divide the histogram into x columns and y rows of buckets.
Tracing options:
MBnn or Bounding=bool Bounding_Threshold=integer
Use automatic bounding slabs if more than nn objects are in the
scene.
Qn or Quality=integer
Render at quality n. Qualities range from 0 for rough images
and 9 for complete ray-tracing and textures, and 10 and 11 add
radiosity.
QR or Radiosity=bool
Turn on radiosity.
A0.n or Antialias=bool Antialias_Threshold=integer
Do antialiasing on the pixels until the difference between adja‐
cent pixels is less that 0.n, or the maximum recursion depth is
reached.
AMn or Sampling_Method=integer
Specify the method of antialiasing used, non-adaptive (n = 1),
or adaptive antialiasing (n = 2).
Jn.n or Jitter=bool Jitter_Amount=float
Specify maximum radius, in pixels, that antialiased samples
should be jittered from their true centers.
Rn or Antialias_Depth=integer
Set the maximum recursion depth for antialiased pixel sub-sam‐
pling.
UL or Light_Buffer=bool
Use light buffer to speed up rendering.
UV or Vista_Buffer=bool
Use vista buffer to speed up rendering.
Animation options:
Kn.n or Clock=float
Render a single frame of an animation with the clock value n.n,
typically used in external animation loops.
KFInn or Initial_Frame=integer
Specify the initial frame number for an animation, using an
internal animation loop. The default is 1.
KFFnn or Final_Frame=integer
Specify the final frame number for an animation. This must be
set at a value other that 1 in order to render multiple frames
at once (i.e. an internal animation loop).
KIn.n or Initial_Clock=float
Specify the clock value for the initial frame of an animation.
KFn.n or Final_Clock=float
Specify the clock value for the frame final of an animation.
SFnn or Subset_Start_Frame=integer
Render a subset of frames from an animation, starting at frame
nn.
SFnn or Subset_Start_Frame=float
Render a subset of frames from an animation, starting nn percent
into the animation.
EFnn or Subset_End_Frame=integer
Render a subset of frames from an animation, stopping at frame
nn.
EFnn or Subset_End_Frame=float
Render a subset of frames from an animation, stopping nn percent
into the animation.
KC or Cyclic_Animation=bool
Generate clock values for a cyclic animation.
UF or Field_Render=bool
Render alternate frames using odd/even fields, suitable for
interlaced output.
UO or Odd_Field=bool
Start a field rendered animation on the odd field, rather than
the even field.
Shell Out:
Pre_Scene_Command=command line
Execute the specified command line before the scene is rendered.
This option may only be used from INI files.
Pre_Frame_Command=command line
Execute the specified command line before the frame is rendered.
This option may only be used from INI files.
Post_Scene_Command=command line
Execute the specified command line after the scene is rendered.
This option may only be used from INI files.
Post_Frame_Command=command line
Execute the specified command line after the frame is rendered.
This option may only be used from INI files.
User_Abort_Command=command line
Execute the specified command line when the user aborts POV-Ray.
This option may only be used from INI files.
Fatal_Error_Command=command line
Execute the specified command line when POV-Ray has a fatal
error. This option may only be used from INI files.
Command-line Substitutions
The following substitutions are available for use within command lines:
%h Height of image in pixels
%k Clock value of this frame
%n Frame number of this frame
%o Output file name with extension and embedded frame number if any
%s Scene name derived by stripping path and extension from input
name
%w Width of image in pixels
%% A single % sign.
Shell Command Return Actions
These options can be used within INI files to specify actions to take
based on return codes from shell commands.
Pre_Scene_Return=return action
Set pre-scene return actions
Pre_Frame_Return=return action
Set pre-frame return actions
Post_Scene_Return=return action
Set post-scene return actions
Post_Frame_Return=return action
Set post-frame return actions
User_Abort_Return=return action
Set user abort return actions
Fatal_Error_Return=return action
Set fatal error return actions
Return Actions:
Return actions are specified by a single letter. 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
Redirecting options:
GI<name> or Create_Ini=bool or Create_Ini=file
Write all INI parameters to a file named after the input scene
file, or one with the specified name.
G[ADFRSW] or <Stream>_Console=bool
Write the specified stream to the console. The streams are All
(except status), Debug, Fatal, Render, Statistics, and Warning.
G[ADFRSW]<name> or <Stream>_File=bool or <Stream>_File=file
Write the specified stream to the console and/or the specified
file. The streams are All (except status), Debug, Fatal, Ren‐
der, Statistics, and Warning.
X Windows options
In addition to the standard command-line options, the X Windows version
recognizes additional command-line switches. See X(1) for a complete
description of these options.
-display <display_name>
Display preview on display_name rather than the default display.
This is meant to be used to change the display to a remote host.
The normal dispay option +d is still valid.
-geometry [WIDTHxHEIGHT][+XOFF+YOFF]
Render the image with WIDTH and HEIGHT as the dimensions, and
locate the window XOFF from the left edge, and YOFF from the top
edge of the screen (or if negative the right and bottom edges
respectively). The WIDTH and HEIGHT, if given, override any
previous Wnn and Hnn settings.
-help Display the X Windows specific options. Use -H by itself on the
command-line to output the general POV-Ray options.
-icon Start the preview window as an icon.
-title <window_title>
Override the default preview window title with window_title.
-visual <visual_type>
Use the deepest visual of visual_type, if available, instead of
the visual automatically selected visual. Valid visuals are
StaticGray, GrayScale, StaticColor, PseudoColor, TrueColor, or
DirectColor.
RESOURCES
Currently no X resource or app-default files are supported for the X
Windows options.
FILES
POV-Ray version 3.1 includes a modification which causes the povray.ini
in the current directory to override the individual setting in
.povrayrc, POV-Ray now looks for initial configuration information,
like the Library_Path settings, which gives the location for the stan‐
dard include files, first in the environment variable $POVINI, then in
./povray.ini, then in $HOME/.povrayrc, then in
/usr/local/lib/povray31/povray.ini, which directory can be changed at
compile-time by modifying POVLIBDIR in the makefile.
POVLEGAL.DOC should be accompany all installations of POV-Ray, and out‐
lines specific conditions and restrictions on the POV-Ray software. A
condition of POVLEGAL.DOC requires that documentation, INI, and scene
files be available to all users of POV-Ray They are often installed in
/usr/local/lib/povray31, but may be in other locations on some systems.
The most recent version of POV-Ray and its documentation can always be
retrieved via anonymous FTP at ftp.povray.org, or via HTTP at
http://www.povray.org/, as well as many other locations.
SEE ALSOX(1), kill(1)COPYRIGHT
POV-Ray is Copyright (C) 1991, 1999 the POV-Ray Development Team.
Although it is distributed as freeware, it is NOT PUBLIC DOMAIN soft‐
ware. POV-Ray is subject to the restrictions as defined in POVLE‐
GAL.DOC.
X Windows is Copyright (C) 1984 - 1991 the Massachusetts Institute of
Technology, and also Copyright (C) 1992 - 1996 the X Consortium, Inc.
TRADEMARKS
Persistence of Vision, POV-Ray, and POV-Help are registered trademarks
of the POV-Ray Development Team.
BUGS
The SVGA version does not currently generate an optimized grayscale
palette for grayscale preview, so displays using the G palette option
will use very few gray levels, and a few non-gray colors.
Before reporting a bug to the authors, you should make sure you have
the latest version of the software, in case the bug has already been
fixed. There are a large number of POV-Ray users on the USENET news‐
group comp.graphics.rendering.raytracing that may be able to help you
with your problem. If you are having problems compiling, installing,
or running the software, you should seek help locally or on USENET,
rather than from the authors.
If you have a repeatable bug in the most recent version, try to isolate
the bug in the smallest scene file possible. The POV-Ray Team Co-ordi‐
nator is Chris Young and can be reached at team-coord@povray.org. Do
not send large binary or uuencoded files to Chris without first asking
permission to do so.
AUTHORS
The primary developers, in alphabetical order are:
Steve Anger Dieter Bayer Chris Cason
Chris Dailey Andreas Dilger Steve Demlow
Alexander Enzmann Dan Farmer Timothy Wegner
Chris Young
Major contributing authors, in alphabetical order are:
Steve A. Bennett David K. Buck Aaron A. Collins
Pascal Massimino Jim McElhiney Douglas Muir
Bill Pulver Robert Skinner Zsolt Szalavari
Scott Taylor Drew Wells
Other authors are listed in the documentation.
ACKNOWLEDGEMENT
POV-Ray is based on DKBTrace 2.12 by David K. Buck and Aaron A.
Collins.
POV-Team 21 November 1999 POV-Ray(1)