1POV-Ray(1) Version 3.7 POV-Ray(1)
2
6 povray - POV-Ray: The Persistence of Vision Ray Tracer
7
10 povray [+Ooutput_file] [+/-option ...] [input_file]
11 povray [+Iinput_file] [+Ooutput_file] [+/-option ...] [INI_file]
13
16 POV-Ray is a free, full-featured ray tracer, written and maintained by
17 a team of volunteers on the Internet. On the UNIX platform POV-Ray can
18 be compiled with support for preview capabilities using the X Window
19 System.
20 This manual page only lists the basic POV-Ray and UNIX specific fea‐
22 tures and command-line options for this version of POV-Ray. For a com‐
23 plete description of the features of POV-Ray and its scene description
24 language (a.k.a. POV-Ray SDL), or for a better explanation of the mean‐
25 ing of the command-line and INI file options, please consult the docu‐
26 mentation that should accompany all versions of POV-Ray. The documen‐
27 tation is installed in PREFIX/share/doc/povray-3.7, where PREFIX is
28 /usr/local by default, or a path specified when configuring the source
29 package for compilation and installation.
30 Some of the UNIX-specific features are:
32 Support for X Window display automatically uses the best visual
34 class and deepest depth available. For visuals that do not sup‐
35 port 24 bits of color per pixel, Floyd-Steinberg error diffusion
36 dithering is used, along with a dynamically allocated and opti‐
37 mized palette to produce the best display possible with the cur‐
38 rent visual, depth, and available colormap.
39 ICCCM compliance for the X Window version means that the preview
41 window will behave like standard X Window programs, communicate
42 properly with the window manager, and will accept the standard
43 command-line options. See X(1) for more information.
44 ASCII graphics in the text-mode version allow a basic view of
46 the current rendering on text-only terminals.
47 An interrupt handler allows rendering to be interrupted in a
49 safe way, so that any data not currently written to disk will be
50 saved before exiting. Control-C or SIGINT will cause a user
51 abort, and save the current rendering, before exiting. See
52 kill(1) for more information.
53 Platform and architecture-independent rendering means that the
55 same scene will render in the same way on all computers and op‐
56 erating systems (with the exception of the rendering speed, of
57 course).
58
61 Options can be specified with either a leading '+' or a leading '-'.
62 Many options are switches, meaning a '+' turns the option on, and a '-'
63 turns the option off. For other options, it doesn't matter if a '+' or
64 a '-' is used. Most options cannot have spaces in them so you should
65 specify +FN rather than +F N, and combining options is not allowed, so
66 +SC is very different from +S +C. Options are not case sensitive.
67 The command-line options are shown below with their corresponding INI
69 file options. If the same option is specified multiple times, whether
70 in INI files or on the command-line, the last such option overrides any
71 previous ones, with the exception of the +L or Library_Path option,
72 which is cumulative.
73 Parsing options:
76 I<input_file_name> or Input_File_Name=file
77 Specifies the input file to use. If the input file name is '-',
78 the scene description will be read from the standard input. The
79 HI<header_include_file_name> or Include_Header=file
81 Specifies a file as the first include file of a scene file.
82 This can be used to always include a specific set of default in‐
83 clude files used by all your scenes.
84 L<library_path> or Library_Path=path
86 Specifies a directory to search for input files, include files,
87 fonts, and image maps, if the specified file is not in the cur‐
88 rent directory. This may be specified multiple times to in‐
89 crease the number of directories to search.
90 MVn.n or Version=float
92 Treat scene files as if they were version n.n instead of the
93 current version. This may be overridden from within the scene
94 file.
95 SU or Split_Unions=bool
97 Split bounded CSG unions if children are finite. This allows
98 automatic bounding of CSG objects to take place.
99 UR or Remove_Bounds=bool
101 Remove unnecessary bounding objects. This allows automatic
102 bounding of older scene files to take place.
103 BM1 or Bounding_Method=1
105 Enable BVH (Bounding Volume Hierarchy) bounding (the default).
106 BM2 or Bounding_Method=2
108 Enable BSP (Binary Space Partitioning) tree bounding.
109 Output options:
111 Hn or Height=integer
112 The image should be n pixels high.
113 Wn or Width=integer
115 The image should be n pixels wide.
116 SRn or Start_Row=integer
118 Start the rendering at row n from the top of the screen.
119 SR0.n or Start_Row=float
121 Start the rendering n percent from the top of the screen.
122 ERn or End_Row=integer
124 End the rendering at row n from the top of the screen.
125 ER0.n or End_Row=float
127 End the rendering at n percent from the top of the screen.
128 SCn or Start_Column=integer
130 Start the rendering at column n from the left of the screen.
131 SC0.n or Start_Column=float
133 Start the rendering at n percent from the left of the screen.
134 ECn or Start_Column=integer
136 End the rendering at column n from the left of the screen.
137 EC0.n or Start_Column=float
139 End the rendering at n percent from the left of the screen.
140 C or Continue_Trace=bool
142 Continue a previously interrupted trace.
143 P or Pause_When_Done=bool
145 If previewing, pause when the rendering is complete before clos‐
146 ing the window.
147 V or Verbose=bool
149 Output verbose status messages on the progress of the rendering.
150 WLn or Warning_Level=integer
152 Set warning level to n.
153 X or Test_Abort=bool
155 Enable the 'q' and 'Q' keys to interrupt a rendering in
156 progress.
157 Xn or Test_Abort_Count=integer
159 Only check every n pixels for a user abort.
160 Output options - display related:
163 D[0][GHT] or Display=bool Palette=char
164 Display the rendering in progress, optionally specifying the
165 palette. The only valid X Window palette option is G, which
166 forces grayscale preview. The X Window palette is based on the
167 visual used, whether selected automatically by POV-Ray or via
168 the -visual option. To specify the palette, you must first
169 specify the display type (the second character, shown here as
170 '0') for compatibility reasons, even though it is ignored in
171 UNIX versions.
172 SPn or Preview_Start_Size=integer
174 Start mosaic preview with blocks n pixels square.
175 EPn or Preview_End_Size=integer
177 End mosaic preview with blocks n pixels square.
178 UD or Draw_Vistas=bool
180 Draw vista rectangles before rendering has been deprecated.
181 Output options - file related:
183 F[CEHJNPST][n] or Output_to_File=bool Output_File_Type=char
184 Store the rendered image using one of the available formats,
185 namely Compressed TGA, OpenEXR, Radiance High Dynamic-Range,
186 JPEG, PNG, PPM, System specific (PNG) and TGA.
187 O<output_file> or Output_File_Name=file
189 Write the output to the file named output_file, or the standard
190 output if '-' is given as the output file name.
191 MIn or Max_Image_Buffer_Memory=n
193 Sets the allowable size of the output image cache in megabytes.
194 Tracing options:
196 MBn or Bounding=bool Bounding_Threshold=integer
197 Use automatic bounding slabs if more than n objects are in the
198 scene.
199 Qn or Quality=integer
201 Render at quality n. Qualities range from 0 for rough images
202 and 9 for complete ray-tracing and textures, and 10 and 11 add
203 radiosity.
204 A0.n or Antialias=bool Antialias_Threshold=integer
206 Do antialiasing on the pixels until the difference between adja‐
207 cent pixels is less that 0.n, or the maximum recursion depth is
208 reached.
209 AMn or Sampling_Method=integer
211 Specify the method of antialiasing used, non-adaptive (n = 1),
212 or adaptive antialiasing (n = 2).
213 Jn.n or Jitter=bool Jitter_Amount=float
215 Specify maximum radius, in pixels, that antialiased samples
216 should be jittered from their true centers.
217 Rn or Antialias_Depth=integer
219 Set the maximum recursion depth for antialiased pixel sub-sam‐
220 pling.
221 UA or Output_Alpha=bool
223 Use alpha channel for transparency mask.
224 UL or Light_Buffer=bool
226 Use light buffer to speed up rendering has been deprecated.
227 UV or Vista_Buffer=bool
229 Use vista buffer to speed up rendering has been deprecated.
230 Animation options:
233 Kn.n or Clock=float
234 Render a single frame of an animation with the clock value n.n.
235 KFIn or Initial_Frame=integer
237 Specify the initial frame number for an animation.
238 KFFn or Final_Frame=integer
240 Specify the final frame number for an animation. This must be
241 set at a value other that 1 in order to render multiple frames
242 at once.
243 KIn.n or Initial_Clock=float
245 Specify the clock value for the initial frame of an animation.
246 KFn.n or Final_Clock=float
248 Specify the clock value for the frame final of an animation.
249 SFn or Subset_Start_Frame=integer
251 Render a subset of frames from an animation, starting at frame
252 n.
253 SF0.n or Subset_Start_Frame=float
255 Render a subset of frames from an animation, starting n percent
256 into the animation.
257 EFn or Subset_End_Frame=integer
259 Render a subset of frames from an animation, stopping at frame
260 n.
261 EF0.n or Subset_End_Frame=float
263 Render a subset of frames from an animation, stopping n percent
264 into the animation.
265 KC or Cyclic_Animation=bool
267 Generate clock values for a cyclic animation.
268 UF or Field_Render=bool
270 Render alternate frames using odd/even fields, suitable for in‐
271 terlaced output.
272 UO or Odd_Field=bool
274 Start a field rendered animation on the odd field, rather than
275 the even field.
276 Redirecting options:
279 GI<name> or Create_Ini=bool or Create_Ini=file
280 Write all INI parameters to a file named after the input scene
281 file, or one with the specified name.
282 G[ADFRSW]<name> or <Stream>_File=bool or <Stream>_File=file
284 Write the stream to the console and/or the specified file. The
285 streams are All_File (except status), Debug_File, Fatal_File,
286 Render_File, Statistics_File, and the Warning_File.
287 X Window System options:
290 In addition to the standard command-line options, POV-Ray recognizes
291 additional command-line switches related to the X Window System. See
292 X(1) for a complete description of these options.
293 -display <display_name>
295 Display preview on display_name rather than the default display.
296 This is meant to be used to change the display to a remote host.
297 The normal dispay option +d is still valid.
298 -geometry [WIDTHxHEIGHT][+XOFF+YOFF]
300 Render the image with WIDTH and HEIGHT as the dimensions, and
301 locate the window XOFF from the left edge, and YOFF from the top
302 edge of the screen (or if negative the right and bottom edges
303 respectively). The WIDTH and HEIGHT, if given, override any
304 previous Wn and Hn settings.
305 -help Display the X Window System-specific options. Use -H by itself
307 on the command-line to output the general POV-Ray options.
308 -icon Start the preview window as an icon.
310 -title <window_title>
312 Override the default preview window title with window_title.
313 -visual <visual_type>
315 Use the deepest visual of visual_type, if available, instead of
316 the automatically selected visual. Valid visuals are Stat‐
317 icGray, GrayScale, StaticColor, PseudoColor, TrueColor, or Di‐
318 rectColor.
319
322 Currently no X resource or app-default files are supported for the X
323 Window options.
324
327 POV-Ray for UNIX allows a povray.ini file in the current directory to
328 override the individual setting in $HOME/.povray/3.7/povray.ini.
329 POV-Ray looks for initial configuration information, like the Li‐
330 brary_Path settings, which gives the location for the standard include
331 files, first in the environment variable $POVINI, then in ./povray.ini,
332 then in $HOME/.povray/3.7/povray.ini, then in PRE‐
333 FIX/etc/povray/3.7/povray.ini. The PREFIX directory can be changed at
334 compile-time using the --prefix option of the configure script. For
335 backward compatibility with POV-Ray version 3.5 and earlier, the
336 $HOME/.povrayrc and $PREFIX/etc/povray.ini files are also searched for
337 when none of the above files were found.
338 Since version 3.5 POV-Ray features an I/O Restriction mechanism. I/O
340 Restrictions attempt to at least partially protect a machine running
341 POV-Ray from having files read or written outside of a given set of di‐
342 rectories. The settings are defined in two configuration files, a sys‐
343 tem-level PREFIX/etc/povray/3.7/povray.conf file and an user-level
344 $HOME/.povray/3.7/povray.conf file with more restrictive settings. As
345 of POV-Ray 3.6 the format of these configuration files has changed, and
346 no backward compatibility is retained with the configuration files in
347 POV-Ray 3.5. See the documentation for further details and examples of
348 I/O Restriction settings.
349 povlegal.doc should accompany all installations of POV-Ray, and out‐
351 lines specific conditions and restrictions on the POV-Ray software. A
352 condition of povlegal.doc requires that documentation, INI and scene
353 files be available to all users of POV-Ray. Scene and INI files are
354 typically installed in PREFIX/share/povray-3.7, and documentation in
355 PREFIX/share/doc/povray-3.7, but these may be in other locations on
356 some systems.
357 The most recent version of POV-Ray and its documentation can always be
359 retrieved via anonymous FTP at ftp.povray.org or via HTTP at
360 povray.org, as well as many other locations.
361
364 X(1), kill(1), The POV-Ray Manual
365
368 Persistence of Vision Ray Tracer (POV-Ray)
369 Copyright 1991-2013 Persistence of Vision Raytracer Pty. Ltd.
370 For further information see the file povlegal.doc that comes with this
372 program.
373 The X Window System is
375 Copyright 1984 - 1991 the Massachusetts Institute of Technology
376 Copyright 1992 - 1996 the X Consortium, Inc.
377 Copyright 1998 the Open Group, L.L.C.
378 Copyright 1999 - 2004 the X.Org Foundation, L.L.C.
379
382 The terms Persistence of Vision Raytracer and POV-Ray are trademarks of
383 Persistence of Vision Raytracer Pty. Ltd.
384 UNIX is a registered trademark of The Open Group in the US and other
386 countries.
387
390 Before reporting a bug to our bug-tracking system bugs.povray.org you
391 should make sure you have the latest version of the software, in case
392 the bug has already been fixed. There are a large number of POV-Ray
393 users on the POV-Ray newsserver news.povray.org and a list of available
394 groups can be found on povray.org/resources/newsgroups. You should try
395 to find help and assistance in there before lodging a bug report.
396
399 Primary POV-Ray 3.7 Architects/Developers: (Alphabetically)
400 Chris Cason Thorsten Froehlich Christoph Lipka
402 With Assistance From: (Alphabetically)
404 Ton van den Broek Nicolas Calimet Jerome Grimbert James
406 Holsenback
407 Christoph Hormann Nathan Kopp Juha Nieminen
408 Past Contributors: (Alphabetically)
410 Steve Anger Eric Barish Dieter Bayer David K.
412 Buck
413 Nicolas Calimet Chris Cason Aaron A. Collins Chris
414 Dailey
415 Steve Demlow Andreas Dilger Alexander Enzmann Dan
416 Farmer
417 Thorsten Froehlich Mark Gordon James Holsenback Christoph
418 Hormann
419 Mike Hough Chris Huff Kari Kivisalo Nathan
420 Kopp
421 Lutz Kretzschmar Christoph Lipka Jochen Lippert Pascal
422 Massimino
423 Jim McElhiney Douglas Muir Juha Nieminen Ron
424 Parker
425 Bill Pulver Eduard Schwan Wlodzimierz Skiba Robert
426 Skinner
427 Yvo Smellenbergh Zsolt Szalavari Scott Taylor Massimo
428 Valentini
429 Timothy Wegner Drew Wells Chris Young
430 Other contributors are listed in the documentation.
432
435 POV-Ray is based on DKBTrace 2.12 by David K. Buck and Aaron A.
436 Collins.
437POV-Team July 2021 POV-Ray(1)