--- name: "povray" section: "1" platform: "linux" package: "povray" version: "2:3.7.0.10-24" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/povray" --- # povray(1) POV-Ray: The Persistence of Vision Ray Tracer ## NAME povray - POV-Ray: The Persistence of Vision Ray Tracer ## SYNOPSIS **povray** \[**+O***output\_file*\] \[**+/-option** ...\] \[*input\_file*\] **povray** \[**+I***input\_file*\] \[**+O***output\_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*. 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.7, 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. - 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)](/kill/1.md)* 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.** ### 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.** - **MV***n.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.** - **BM1 or Bounding\_Method=1** **Enable BVH (Bounding Volume Hierarchy) bounding (the default).** - **BM2 or Bounding\_Method=2** **Enable BSP (Binary Space Partitioning) tree bounding.** ### Output options: - **H***n* **or Height=***integer* **The image should be** *n* **pixels high.** - **W***n* **or Width=***integer* **The image should be** *n* **pixels wide.** - **SR***n* **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.** - **ER***n* **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.** - **SC***n* **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.** - **EC***n* **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.** - **WL***n* **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.** - **X***n* **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. 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.** - **SP***n* **or Preview\_Start\_Size=***integer* **Start mosaic preview with blocks** *n* **pixels square.** - **EP***n* **or Preview\_End\_Size=***integer* **End mosaic preview with blocks** *n* **pixels square.** - **UD or Draw\_Vistas=***bool* **Draw vista rectangles before rendering has been deprecated.** ### Output options - file related: - **F\[***CEHJNPST***\]\[***n***\] or Output\_to\_File=***bool* **Output\_File\_Type=***char* **Store the rendered image using one of the available formats, namely** *C***ompressed TGA, Open***E***XR, Radiance** *H***igh Dynamic-Range,** *J***PEG, P***N***G,** *P***PM,** *S***ystem specific (PNG) and** *T***GA.** - **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.** - **MI***n* **or Max\_Image\_Buffer\_Memory=***n* **Sets the allowable size of the output image cache in megabytes.** ### Tracing options: - **MB***n* **or Bounding=***bool* **Bounding\_Threshold=***integer* **Use automatic bounding slabs if more than** *n* **objects are in the scene.** - **Q***n* **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.** - **AM***n* **or Sampling\_Method=***integer* **Specify the method of antialiasing used, non-adaptive (***n* **= 1), or** **adaptive antialiasing (***n* **= 2).** - **J***n.n* **or Jitter=***bool* **Jitter\_Amount=***float* **Specify maximum radius, in pixels, that antialiased samples should be** **jittered from their true centers.** - **R***n* **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 has been deprecated.** - **UV or Vista\_Buffer=***bool* **Use vista buffer to speed up rendering has been deprecated.** ### Animation options: - **K***n.n* **or Clock=***float* **Render a single frame of an animation with the clock value** *n.n***.** - **KFI***n* **or Initial\_Frame=***integer* **Specify the initial frame number for an animation.** - **KFF***n* **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.** - **KI***n.n* **or Initial\_Clock=***float* **Specify the clock value for the initial frame of an animation.** - **KF***n.n* **or Final\_Clock=***float* **Specify the clock value for the frame final of an animation.** - **SF***n* **or Subset\_Start\_Frame=***integer* **Render a subset of frames from an animation, starting at frame** *n***.** - **SF***0.n* **or Subset\_Start\_Frame=***float* **Render a subset of frames from an animation, starting** *n* **percent** **into the animation.** - **EF***n* **or Subset\_End\_Frame=***integer* **Render a subset of frames from an animation, stopping at frame** *n***.** - **EF***0.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\ 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 \\_File=***bool* **or \\_File=***file* **Write the stream to the console and/or the specified file. The streams are** *A***ll\_File (except status),** *D***ebug\_File,** *F***atal\_File,** *R***ender\_File,** *S***tatistics\_File, and the** *W***arning\_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 \[***WIDTH***x***HEIGHT***\]\[+***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 W***n* **and H***n* **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.7/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.7/povray.ini***, then in** *PREFIX/etc/povray/3.7/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.7/povray.conf* **file and an user-level** *$HOME/.povray/3.7/povray.conf* **file with more restrictive settings.** **As of 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.7, and** **documentation in PREFIX/share/doc/povray-3.7, 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** *povray.org***, as well as many other locations.** ## SEE ALSO **X(1), [kill(1)](/kill/1.md),** *The POV-Ray Manual* ## COPYRIGHT **Persistence of Vision Ray Tracer (POV-Ray)**\ **Copyright 1991-2013 Persistence of Vision Raytracer Pty. Ltd.** **For further information see the file** *povlegal.doc* **that comes** **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 **Before reporting a bug to our bug-tracking system** *bugs.povray.org* **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* **and a list of available groups** **can be found on** *povray.org/resources/newsgroups***. You should try to find** **help and assistance in there before lodging a bug report.** ## AUTHORS **Primary POV-Ray 3.7 Architects/Developers: (Alphabetically)** **Chris Cason Thorsten Froehlich Christoph Lipka** **With Assistance From: (Alphabetically)** **Ton van den Broek Nicolas Calimet Jerome Grimbert James Holsenback** \ **Christoph Hormann Nathan Kopp Juha Nieminen** **Past Contributors: (Alphabetically)** **Steve Anger Eric Barish Dieter Bayer David K. Buck** \ **Nicolas Calimet Chris Cason Aaron A. Collins Chris Dailey** \ **Steve Demlow Andreas Dilger Alexander Enzmann Dan Farmer** \ **Thorsten Froehlich Mark Gordon James Holsenback Christoph Hormann** \ **Mike Hough Chris Huff Kari Kivisalo Nathan Kopp** \ **Lutz Kretzschmar Christoph Lipka Jochen Lippert Pascal Massimino** \ **Jim McElhiney Douglas Muir Juha Nieminen Ron Parker** \ **Bill Pulver 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.**