pov-ray(1)

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 pre view renderings.

This manual page only lists the basic POV-Ray and Unix specific features and command-line options for this ver
sion of POV-Ray. For a complete description of the fea tures 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 docu
mentation that should accompany all versions of POV-Ray. On some sites this will be installed in
/usr/local/share/doc/povray-3.5. Some of the Unix-spe
cific features are:: Support for X Windows 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 dither
ing is used, along with a dynamically allocated and
optimized palette to produce the best display pos
sible with the current visual, depth, and available
colormap.; ICCCM compliance for the X Windows version means
that the preview window will behave like standard X
Windows programs, communicate properly with the
window manager, and will accept the standard com
mand-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 inter
rupted in a safe way, so that any data not cur
rently written to disk will be saved before exit
ing. 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. 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 corre
sponding INI file options. If the same option is speci
fied multiple times, whether in INI files or on the com
mand-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. 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 speci
fied 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 over
ridden 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:: ?[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.; 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 Start_Column=integer
End the rendering at column nn from the left of the
screen.; EC0.nn or Start_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 closing 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 render
ing 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 spec
ifying the palette. The only valid X Windows
palette option is G, which forces grayscale pre
view. 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 dis
play, 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.; 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. 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, uncom
pressed 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:: 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.; 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-adap
tive (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.; 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.; KFInn or Initial_Frame=integer
Specify the initial frame number for an animation.; 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.; 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, start
ing at frame nn.; SF0.nn or Subset_Start_Frame=float
Render a subset of frames from an animation, start
ing nn percent into the animation.; EFnn or Subset_End_Frame=integer
Render a subset of frames from an animation, stop
ping at frame nn.; EF0.nn or Subset_End_Frame=float
Render a subset of frames from an animation, stop
ping 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.
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 speci
fied file. The streams are All_File (except sta
tus), Debug_File, Fatal_File, Render_File, Statis
tics_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 respec
tively). The WIDTH and HEIGHT, if given, override any previous Wnn and Hnn settings.; -help Display the X Window System-specific options. Use
-H by itself on the command-line to output the gen
eral POV-Ray options.; -icon Start the preview window as an icon.; -title <window_title>
Override the default preview window title with win_
dow_title.; -visual <visual_type>
Use the deepest visual of visual_type, if avail able, instead of the automatically selected visual.
Valid visuals are StaticGray, GrayScale, Static
Color, PseudoColor, TrueColor, or DirectColor.

RESOURCES

Currently no X resource or app-default files are supported
for the X Windows options.

FILES

POV-Ray for Unix allows a povray.ini file in the current directory to override the individual setting in .povrayrc. 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 vari
able $POVINI, then in /usr/local/lib/povray35/povray.ini. The directory can be changed at compile-time using the
--prefix option of the configure script.

povlegal.doc should be 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 /usr/local/lib/povray35, with docu
mentation in /usr/local/share/doc/povray-3.5, 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 http://www.povray.org/, as
well as many other locations.

COPYRIGHT

POV-Ray is Copyright (C) 1991, 2002 the POV-Ray Develop ment Team. Although it is distributed as freeware, it is
NOT PUBLIC DOMAIN software. POV-Ray is subject to the restrictions as defined in povlegal.doc.

TRADEMARKS

Persistence of Vision, POV-Ray, and POV-Help are: 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 newsgroup comp.graph ics.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 possi
ble. The POV-Ray Team Co-ordinator 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.

docs.sk

comprehensive documentation repository

See also