1POV-Ray(1)                        Version 3.7                       POV-Ray(1)
2
3
4

NAME

6       povray - POV-Ray: The Persistence of Vision Ray Tracer
7
8

SYNOPSIS

10       povray [+Ooutput_file] [+/-option ...]  [input_file]
11
12       povray [+Iinput_file] [+Ooutput_file] [+/-option ...] [INI_file]
13
14

DESCRIPTION

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
21       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
31       Some of the UNIX-specific features are:
32
33              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
40              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
45              ASCII graphics in the text-mode version allow a  basic  view  of
46              the current rendering on text-only terminals.
47
48              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
54              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
59

OPTIONS

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
68       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
74
75   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
80       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
85       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
91       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
96       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
100       UR or Remove_Bounds=bool
101              Remove unnecessary  bounding  objects.   This  allows  automatic
102              bounding of older scene files to take place.
103
104       BM1 or Bounding_Method=1
105              Enable BVH (Bounding Volume Hierarchy) bounding (the default).
106
107       BM2 or Bounding_Method=2
108              Enable BSP (Binary Space Partitioning) tree bounding.
109
110   Output options:
111       Hn or Height=integer
112              The image should be n pixels high.
113
114       Wn or Width=integer
115              The image should be n pixels wide.
116
117       SRn or Start_Row=integer
118              Start the rendering at row n from the top of the screen.
119
120       SR0.n or Start_Row=float
121              Start the rendering n percent from the top of the screen.
122
123       ERn or End_Row=integer
124              End the rendering at row n from the top of the screen.
125
126       ER0.n or End_Row=float
127              End the rendering at n percent from the top of the screen.
128
129       SCn or Start_Column=integer
130              Start the rendering at column n from the left of the screen.
131
132       SC0.n or Start_Column=float
133              Start the rendering at n percent from the left of the screen.
134
135       ECn or Start_Column=integer
136              End the rendering at column n from the left of the screen.
137
138       EC0.n or Start_Column=float
139              End the rendering at n percent from the left of the screen.
140
141       C or Continue_Trace=bool
142              Continue a previously interrupted trace.
143
144       P or Pause_When_Done=bool
145              If previewing, pause when the rendering is complete before clos‐
146              ing the window.
147
148       V or Verbose=bool
149              Output verbose status messages on the progress of the rendering.
150
151       WLn or Warning_Level=integer
152              Set warning level to n.
153
154       X or Test_Abort=bool
155              Enable the  'q'  and  'Q'  keys  to  interrupt  a  rendering  in
156              progress.
157
158       Xn or Test_Abort_Count=integer
159              Only check every n pixels for a user abort.
160
161
162   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
173       SPn or Preview_Start_Size=integer
174              Start mosaic preview with blocks n pixels square.
175
176       EPn or Preview_End_Size=integer
177              End mosaic preview with blocks n pixels square.
178
179       UD or Draw_Vistas=bool
180              Draw vista rectangles before rendering has been deprecated.
181
182   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
188       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
192       MIn or Max_Image_Buffer_Memory=n
193              Sets the allowable size of the output image cache in megabytes.
194
195   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
200       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
205       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
210       AMn or Sampling_Method=integer
211              Specify the method of antialiasing used, non-adaptive (n  =  1),
212              or adaptive antialiasing (n = 2).
213
214       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
218       Rn or Antialias_Depth=integer
219              Set the maximum recursion depth for antialiased  pixel  sub-sam‐
220              pling.
221
222       UA or Output_Alpha=bool
223              Use alpha channel for transparency mask.
224
225       UL or Light_Buffer=bool
226              Use light buffer to speed up rendering has been deprecated.
227
228       UV or Vista_Buffer=bool
229              Use vista buffer to speed up rendering has been deprecated.
230
231
232   Animation options:
233       Kn.n or Clock=float
234              Render a single frame of an animation with the clock value n.n.
235
236       KFIn or Initial_Frame=integer
237              Specify the initial frame number for an animation.
238
239       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
244       KIn.n or Initial_Clock=float
245              Specify the clock value for the initial frame of an animation.
246
247       KFn.n or Final_Clock=float
248              Specify the clock value for the frame final of an animation.
249
250       SFn or Subset_Start_Frame=integer
251              Render  a  subset of frames from an animation, starting at frame
252              n.
253
254       SF0.n or Subset_Start_Frame=float
255              Render a subset of frames from an animation, starting n  percent
256              into the animation.
257
258       EFn or Subset_End_Frame=integer
259              Render  a  subset of frames from an animation, stopping at frame
260              n.
261
262       EF0.n or Subset_End_Frame=float
263              Render a subset of frames from an animation, stopping n  percent
264              into the animation.
265
266       KC or Cyclic_Animation=bool
267              Generate clock values for a cyclic animation.
268
269       UF or Field_Render=bool
270              Render  alternate frames using odd/even fields, suitable for in‐
271              terlaced output.
272
273       UO or Odd_Field=bool
274              Start a field rendered animation on the odd field,  rather  than
275              the even field.
276
277
278   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
283       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
288
289   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
294       -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
299       -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
306       -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
309       -icon  Start the preview window as an icon.
310
311       -title <window_title>
312              Override the default preview window title with window_title.
313
314       -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
320

RESOURCES

322       Currently no X resource or app-default files are supported  for  the  X
323       Window options.
324
325

FILES

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
339       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
350       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
358       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
362

SEE ALSO

364       X(1), kill(1), The POV-Ray Manual
365
366
368       Persistence of Vision Ray Tracer (POV-Ray)
369         Copyright 1991-2013 Persistence of Vision Raytracer Pty. Ltd.
370
371       For further information see the file povlegal.doc that comes with  this
372       program.
373
374       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
380

TRADEMARKS

382       The terms Persistence of Vision Raytracer and POV-Ray are trademarks of
383       Persistence of Vision Raytracer Pty. Ltd.
384
385       UNIX is a registered trademark of The Open Group in the  US  and  other
386       countries.
387
388

BUGS

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
397

AUTHORS

399       Primary POV-Ray 3.7 Architects/Developers: (Alphabetically)
400
401         Chris Cason         Thorsten Froehlich  Christoph Lipka
402
403       With Assistance From: (Alphabetically)
404
405         Ton van den Broek   Nicolas  Calimet      Jerome  Grimbert      James
406       Holsenback
407         Christoph Hormann   Nathan Kopp         Juha Nieminen
408
409       Past Contributors: (Alphabetically)
410
411         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
431       Other contributors are listed in the documentation.
432
433

ACKNOWLEDGEMENT

435       POV-Ray is based on DKBTrace  2.12  by  David  K.  Buck  and  Aaron  A.
436       Collins.
437
438
439
440POV-Team                           July 2021                        POV-Ray(1)
Impressum