NAME
povray - POV-Ray: The Persistence of Vision Ray Tracer
SYNOPSIS
povray [+Ooutput_file] [+/-option ...] [input_file]
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 compiled with support for preview capabilities using the X Window
System. Under Linux, POV-Ray can optionally use the SVGA library to
preview renderings.
This manual page only lists the basic POV-Ray and UNIX specific
features and command-line options for this version of POV-Ray. For a
complete description of the features of POV-Ray and its scene
description language (a.k.a. POV-Ray SDL), or for a better explanation
of the meaning of the command-line and INI file options, please consult
the documentation that should accompany all versions of POV-Ray. The
documentation is installed in PREFIX/share/doc/povray-3.6, where PREFIX
is /usr/local by default, or a path specified when configuring the
source package for compilation and installation.
Some of the UNIX-specific features are:
Support for X Window display automatically uses the best visual
class and deepest depth available. For visuals that do not
support 24 bits of color per pixel, Floyd-Steinberg error
diffusion dithering is used, along with a dynamically allocated
and optimized palette to produce the best display possible with
the current visual, depth, and available colormap.
ICCCM compliance for the X Window version means that the preview
window will behave like standard X Window programs, communicate
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
rendered 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 that 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. 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.
Help options:
The help screen is divided into several parts. To access one part just
enter the number of the screen after the -? option or the -help option.
For instance, use -?5 or -help5 to see the help screen about the
tracing options.
?[01234567] or help[01234567]
Display help on command-line options for section 0 through 7.
Note that most shells will treat the ? as a shell globbing
character unless it is escaped. The available sections are:
Number Part
1 Parsing Options
2 Output Options
3 Output Options - display related
4 Output Options - file related
5 Tracing Options
6 Animation Options
7 Redirecting Options
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. The
HI<header_include_file_name> or Include_Header=file
Specifies a file as the first include file of a scene file.
This can be used to always include a specific set of default
include files used by all your scenes.
L<library_path> or Library_Path=path
Specifies a directory to search for input files, include files,
fonts, and image maps, if the specified file is not in the
current directory. This may be specified multiple times to
increase the number of directories to search.
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:
Hn or Height=integer
The image should be n pixels high.
Wn or Width=integer
The image should be n pixels wide.
SRn or Start_Row=integer
Start the rendering at row n from the top of the screen.
SR0.n or Start_Row=float
Start the rendering n percent from the top of the screen.
ERn or End_Row=integer
End the rendering at row n from the top of the screen.
ER0.n or End_Row=float
End the rendering at n percent from the top of the screen.
SCn or Start_Column=integer
Start the rendering at column n from the left of the screen.
SC0.n or Start_Column=float
Start the rendering at n percent from the left of the screen.
ECn or Start_Column=integer
End the rendering at column n from the left of the screen.
EC0.n or Start_Column=float
End the rendering at n 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
closing the window.
V or Verbose=bool
Output verbose status messages on the progress of the rendering.
WLn or Warning_Level=integer
Set warning level to n.
X or Test_Abort=bool
Enable the ’q’ and ’Q’ keys to interrupt a rendering in
progress.
Xn or Test_Abort_Count=integer
Only check every n 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 Window palette option is G, which
forces grayscale preview. The X Window 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
specify the display type (the second character, shown here as
’0’) for compatibility reasons, even though it is ignored in
UNIX versions.
SPn or Preview_Start_Size=integer
Start mosaic preview with blocks n pixels square.
EPn or Preview_End_Size=integer
End mosaic preview with blocks n pixels square.
UD or Draw_Vistas=bool
Draw vista rectangles before rendering.
Output options - file related:
Bn or Buffer_Output=bool Buffer_Size=integer
Use an output buffer n 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. The default is 8.
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
histogram 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:
MBn or Bounding=bool Bounding_Threshold=integer
Use automatic bounding slabs if more than n 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.
A0.n or Antialias=bool Antialias_Threshold=integer
Do antialiasing on the pixels until the difference between
adjacent 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-sampling.
UA or Output_Alpha=bool
Use alpha channel for transparency mask.
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.
KFIn or Initial_Frame=integer
Specify the initial frame number for an animation.
KFFn 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.
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.
SFn or Subset_Start_Frame=integer
Render a subset of frames from an animation, starting at frame
n.
SF0.n or Subset_Start_Frame=float
Render a subset of frames from an animation, starting n percent
into the animation.
EFn or Subset_End_Frame=integer
Render a subset of frames from an animation, stopping at frame
n.
EF0.n or Subset_End_Frame=float
Render a subset of frames from an animation, stopping n 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.
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]<name> or <Stream>_File=bool or <Stream>_File=file
Write the stream to the console and/or the specified file. The
streams are All_File (except status), Debug_File, Fatal_File,
Render_File, Statistics_File, and the Warning_File.
X Window System options:
In addition to the standard command-line options, POV-Ray recognizes
additional command-line switches related to the X Window System. 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 Wn and Hn settings.
-help Display the X Window System-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 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
Window options.
FILES
POV-Ray for UNIX allows a povray.ini file in the current directory to
override the individual setting in $HOME/.povray/3.6/povray.ini.
POV-Ray looks for initial configuration information, like the
Library_Path settings, which gives the location for the standard
include files, first in the environment variable $POVINI, then in
./povray.ini, then in $HOME/.povray/3.6/povray.ini, then in
PREFIX/etc/povray/3.6/povray.ini. The PREFIX directory can be changed
at compile-time using the --prefix option of the configure script. For
backward compatibility with POV-Ray version 3.5 and earlier, the
$HOME/.povrayrc and $PREFIX/etc/povray.ini files are also searched for
when none of the above files were found.
Since version 3.5 POV-Ray features an I/O Restriction mechanism. I/O
Restrictions attempt to at least partially protect a machine running
POV-Ray from having files read or written outside of a given set of
directories. The settings are defined in two configuration files, a
system-level PREFIX/etc/povray/3.6/povray.conf file and an user-level
$HOME/.povray/3.6/povray.conf file with more restrictive settings. In
POV-Ray 3.6 the format of these configuration files has changed, and no
backward compatibility is retained with the configuration files in POV-
Ray 3.5. See the documentation for further details and examples of I/O
Restriction settings.
povlegal.doc should accompany all installations of POV-Ray, and
outlines 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. Scene and INI files are
typically installed in PREFIX/share/povray-3.6, and documentation in
PREFIX/share/doc/povray-3.6, but these 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
www.povray.org, as well as many other locations.
SEE ALSO
X(1), kill(1), The POV-Ray Manual
COPYRIGHT
Persistence of Vision Ray Tracer (POV-Ray)
Copyright 1991 - 2003 Persistence of Vision Team
Copyright 2003 - 2004 Persistence of Vision Raytracer Pty. Ltd.
For further information see the file povlegal.doc coming with this
program.
The X Window System is
Copyright 1984 - 1991 the Massachusetts Institute of Technology
Copyright 1992 - 1996 the X Consortium, Inc.
Copyright 1998 the Open Group, L.L.C.
Copyright 1999 - 2004 the X.Org Foundation, L.L.C.
TRADEMARKS
The terms Persistence of Vision Raytracer and POV-Ray are trademarks of
Persistence of Vision Raytracer Pty. Ltd.
UNIX is a registered trademark of The Open Group in the US and other
countries.
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 POV-Ray
newsserver news.povray.org (a list of available groups can be found on
www.povray.org/resources/newsgroups). Try to find help and assistance
in there before contacting 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-ordinator is Chris Cason, and can be reached at team-
coord-36@povray.org. Do not send large binary or uuencoded files to
Chris without first asking permission to do so.
AUTHORS
Primary POV-Ray 3.5/3.6 Developers: (Alphabetically)
Chris Cason
Thorsten Froehlich
Nathan Kopp
Ron Parker
Contributing Authors: (Alphabetically)
Steve Anger Eric Barish Dieter Bayer
Steve A. Bennett David K. Buck Nicolas Calimet
Aaron A. Collins Chris Dailey Steve Demlow
Andreas Dilger Alexander Enzmann Dan Farmer
Mark Gordon Christoph Hormann Mike Hough
Chris Huff Kari Kivisalo Lutz Kretzschmar
Jochen Lippert Pascal Massimino Jim McElhiney
Douglas Muir Juha Nieminen Bill Pulver
Tim Rowley Eduard Schwan Wlodzimierz Skiba
Robert Skinner Yvo Smellenbergh Zsolt Szalavari
Scott Taylor Massimo Valentini Timothy Wegner
Drew Wells Chris Young
Other contributors are listed in the documentation.
ACKNOWLEDGEMENT
POV-Ray is based on DKBTrace 2.12 by David K. Buck and Aaron A.
Collins.