POV-Ray(1)

📦
version 3.7.0.10 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 POV-Ray(1) 💖

okay bestie, gather round — this is the manual page for povray, a.k.a. POV-Ray: The Persistence of Vision Ray Tracer, Version 3.7. Yes, the whole manual. Yes it's long. No we're not skimming it. periodt ✨

🌈 NAME 🌈

povray — POV-Ray: The Persistence of Vision Ray Tracer 🎀

Like. That's the name. That's the whole vibe. It traces rays. It persists vision. iconic behavior honestly 👑

✨ SYNOPSIS ✨

povray [+Ooutput_file] [+/-option ...]  [input_file]

povray [+Iinput_file] [+Ooutput_file] [+/-option ...] [INI_file]

two ways in, bestie, pick your fighter 💅

🦋 DESCRIPTION 🦋

okay so. POV-Ray is a free, full-featured ray tracer, and it's 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.

heads up! This manual page only lists the basic POV-Ray and UNIX specific features and command-line options for this version of POV-Ray. For the 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.

And where does that documentation live, you ask? she's installed at 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. she's doing the MOST to make it look good and honestly? we love her for it 💅✨
  • 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. no pixels? no problem, we do letters 🔤
  • 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). 🌍 same scene, same glow-up, every machine 💖

✨ OPTIONS ✨

okay bestie, this is the part where POV-Ray hands you the entire control panel 🎛️ and honestly? it's a lot but we're gonna eat it slice by slice.

Here's the tea on how options work: you can write them with a leading + or a leading -, either one, no drama. Many options are switches, meaning + turns the option on and - turns it off. For other options, it genuinely does not matter which sign you use 🫶.

Most options cannot have spaces in them, so you should write +FN and not +F N. And combining options is not allowed — so +SC is very different from +S +C 💀 do not merge them, that's not a thing.

Options are not case sensitive. lowercase, uppercase, whatever, she doesn't care.

The command-line options are shown below next to their corresponding INI file options 📝. And if the same option gets specified multiple times — whether in INI files or on the command-line — the last such option overrides any previous ones, with one exception: the +L or Library_Path option, which is cumulative (she stacks, she doesn't replace) 💅.

🧚 Parsing options

  • I<input_file_name> or Input_File_Name=file — specifies the input file to use. Only real files are supported. Using - as the input file name, to read from the standard input, is deprecated.
  • 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.
  • 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

  • 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.
  • 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 🙈.
  • 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 has been deprecated.
Heads up bestie: UD / Draw_Vistas is deprecated. It's giving legacy energy 💀.
  • F[CEHJNPST][n] or Output_to_File=bool Output_File_Type=char — store the rendered image using one of the available formats, namely Compressed TGA, OpenEXR, Radiance High Dynamic-Range, JPEG, PNG, PPM, System specific (PNG) and TGA 🖼️.
  • 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.
  • MIn or Max_Image_Buffer_Memory=n — sets the allowable size of the output image cache in megabytes.

🔥 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 has been deprecated.
  • UV or Vista_Buffer=bool — use vista buffer to speed up rendering has been deprecated.
More legacy tea: UL / Light_Buffer and UV / Vista_Buffer are both deprecated, no cap 💀.

🦋 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 (where all the little files live, bestie) 🗂️

Okay so POV-Ray for UNIX is very into letting a povray.ini file in the current directory override the individual setting in $HOME/.povray/3.7/povray.ini. Yes she has layers. Main character behavior honestly.

Here's the ✨hunt order✨ for initial configuration information, like the Library_Path settings, which tells her where the standard include files are:

  1. first in the environment variable $POVINI
  2. then in ./povray.ini
  3. then in $HOME/.povray/3.7/povray.ini
  4. 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. iykyk 💅

And 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. She's nostalgic, she keeps the old receipts. 🫶

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. lowkey a whole security vibe. The settings are defined in two configuration files:

  • a system-level PREFIX/etc/povray/3.7/povray.conf file
  • 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. 🚨 So don't come in with your 3.5 conf expecting a warm welcome, she's changed. 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. (Not everywhere keeps the same layout, she's flexible like that. 🦋)

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. Go get your girl. 🌈

👀 SEE ALSO 👀

like, go read the manual bestie, it's giving ✨required reading✨

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.

so like. don't be out here using these names all willy-nilly, that's ✨their✨ branding 💅

🐛 BUGS 🐛

Bestie. Listen. 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. 😭 Nobody wants to file a duplicate, it's so embarrassing for everyone.

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. The community is right there, they're lovely, they will help you. 🫶

👑 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.

not to be dramatic but. legends. absolute icons. 🙇‍♀️

and that's the whole page bestie!! 🎉 this was POV-Ray(1), from the POV-Team, dated July 2021. go render something gorgeous, you ate. 💅✨🦋

📦 where this page comes from