Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
POV-Ray(1)			  Version 3.7			    POV-Ray(1)

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

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

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

       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

       This manual page	only lists the basic POV-Ray and  UNIX	specific  fea-
       tures and command-line options for this version of POV-Ray.  For	a com-
       plete 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 mean-
       ing of the command-line and INI file options, please consult the	 docu-
       mentation  that should accompany	all versions of	POV-Ray.  The documen-
       tation 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 sup-
	      port 24 bits of color per	pixel, Floyd-Steinberg error diffusion
	      dithering	 is used, along	with a dynamically allocated and opti-
	      mized palette to produce the best	display	possible with the cur-
	      rent 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) for more information.

	      Platform	and  architecture-independent rendering	means that the
	      same scene will render in	the same way on	all computers and  op-
	      erating  systems	(with the exception of the rendering speed, of

       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 in-
	      clude 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 cur-
	      rent directory.  This may	be specified  multiple	times  to  in-
	      crease 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

       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 clos-
	      ing 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

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

       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.

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

       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

       A0.n or Antialias=bool Antialias_Threshold=integer
	      Do antialiasing on the pixels until the difference between adja-
	      cent  pixels is less that	0.n, or	the maximum recursion depth is

       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-sam-

       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:
       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

       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

       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 in-
	      terlaced 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	 Stat-
	      icGray,  GrayScale,  StaticColor,	PseudoColor, TrueColor,	or Di-

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

       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 Li-
       brary_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	  PRE-
       FIX/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 di-
       rectories. The settings are defined in two configuration	files, a  sys-
       tem-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  out-
       lines  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  or	 via  HTTP  at, as well as many other locations.

       X(1), kill(1), The POV-Ray Manual

       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

       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.

       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

       Before  reporting  a bug	to our bug-tracking system 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 and a list of available
       groups  can be found on	You should try
       to find help and	assistance in there before lodging a bug report.

       Primary POV-Ray 3.7 Architects/Developers: (Alphabetically)

	 Chris Cason	     Thorsten Froehlich	 Christoph Lipka

       With Assistance From: (Alphabetically)

	 Nicolas Calimet     Jerome Grimbert	 James Holsenback    Christoph
	 Nathan	Kopp	     Juha Nieminen

       Past Contributors: (Alphabetically)

	 Steve	Anger	      Eric Barish	  Dieter Bayer	      David K.
	 Nicolas Calimet     Chris Cason	  Aaron	 A.  Collins	 Chris
	 Steve	Demlow	       Andreas	Dilger	     Alexander	Enzmann	   Dan
	 Thorsten Froehlich  Mark Gordon	 James Holsenback    Christoph
	 Mike  Hough	       Chris  Huff	    Kari Kivisalo	Nathan
	 Lutz Kretzschmar    Christoph Lipka	  Jochen  Lippert	Pascal
	 Jim  McElhiney	       Douglas	Muir	     Juha  Nieminen	   Ron
	 Bill Pulver	     Eduard Schwan	  Wlodzimierz  Skiba	Robert
	 Yvo  Smellenbergh     Zsolt Szalavari	   Scott Taylor	       Massimo
	 Timothy Wegner	     Drew Wells		 Chris Young

       Other contributors are listed in	the documentation.

       POV-Ray is based	on DKBTrace  2.12  by  David  K.  Buck	and  Aaron  A.

POV-Team			  August 2013			    POV-Ray(1)


Want to link to this manual page? Use this URL:

home | help