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

FreeBSD Manual Pages


home | help
POV-Ray(1)			  Version 3.6			    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
       System.	Under Linux, POV-Ray can optionally use	the  SVGA  library  to
       preview renderings.

       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.6, 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.

	      Support  for SVGAlib display automatically detects the available
	      SVGA display modes to choose the size which best fits  the  ren-
	      dered  image.  When rendering an image that is too large for the
	      current display, the displayed image is scaled  to  fit  on  the
	      screen.	For  displays  that  do	 not support true-color	modes,
	      Floyd-Steinberg dithering	is used.

	      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.

   Help	options:
       The  help screen	is divided into	several	parts. To access one part just
       enter the number	of the screen after the	-? option or the -help option.
       For  instance, use -?5 or -help5	to see the help	screen about the trac-
       ing options.

       ?[01234567] or help[01234567]
	      Display help on command-line options for section	0  through  7.
	      Note that	most shells will treat the ? as	a shell	globbing char-
	      acter unless it is escaped. The available	sections are:
		Number	Part
		  1	Parsing	Options
		  2	Output Options
		  3	Output Options - display related
		  4	Output Options - file related
		  5	Tracing	Options
		  6	Animation Options
		  7	Redirecting Options

   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.

   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.  SVGA	options	are T for  24-bit  true-color,
	      and  H for 15-bit	high-color display, in addition	to the default
	      256-color	palette.  To specify the palette, you must first spec-
	      ify  the	display	type (the second character, shown here as '0')
	      for compatibility	reasons, even though it	 is  ignored  in  UNIX

       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.

   Output options - file related:
       Bn or Buffer_Output=bool	Buffer_Size=integer
	      Use an output buffer n kilobytes in size.

       F[CNPT][n] or Output_to_File=bool Output_File_Type=char
	      Store  the  rendered  image  using one of	the available formats,
	      namely Compressed	TGA, PNG, PPM, and TGA.	 PNG  format  supports
	      the n option to specify the number of bits per color, where 5 <=
	      n	<= 16.	The default is 8.

       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.

       HT[CNPTX] or Histogram_Type=char
	      Create a CPU utilization histogram image in format x.  Available
	      formats are Comma-separated values (CSV),	PNG grayscale, PPM POV
	      heightfield,  uncompressed TGA POV heightfield, or X for no his-
	      togram generation.

       HN_histogram_file_name_ or Histogram_Name=file
	      Output the histogram to the specified file.

       HSx.y or	Histogram_Grid_Size=float
	      Divide the histogram into	x columns and y	rows of	buckets.

   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.

       UV or Vista_Buffer=bool
	      Use vista	buffer to speed	up rendering.

   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.6/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.6/povray.ini,	  then	   in	  PRE-
       FIX/etc/povray/3.6/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.6/povray.conf  file  and	an  user-level
       $HOME/.povray/3.6/povray.conf  file with	more restrictive settings.  In
       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.6, and documentation in
       PREFIX/share/doc/povray-3.6, 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	- 2003 Persistence of Vision Team
	 Copyright 2003	- 2004 Persistence of Vision Raytracer Pty. Ltd.

       For further information see the file povlegal.doc coming	with this pro-

       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

       The SVGA	version	does not currently  generate  an  optimized  grayscale
       palette	for  grayscale preview,	so displays using the G	palette	option
       will use	very few gray levels, and a few	non-gray colors.

       Before reporting	a bug to the authors, 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 (a list of available	groups can be found on  Try to find help and  assistance
       in there	before contacting the authors.

       If you have a repeatable	bug in the most	recent version,	try to isolate
       the bug in the smallest scene file possible.  The POV-Ray Team Co-ordi-
       nator  is  Chris	Cason, and can be reached at
       Do not send large binary	or uuencoded files to Chris without first ask-
       ing permission to do so.

       Primary POV-Ray 3.5/3.6 Developers: (Alphabetically)

	 Chris Cason
	 Thorsten Froehlich
	 Nathan	Kopp
	 Ron Parker

       Contributing Authors: (Alphabetically)

	 Steve Anger	       Eric Barish	     Dieter Bayer
	 Steve A. Bennett      David K.	Buck	     Nicolas Calimet
	 Aaron A. Collins      Chris Dailey	     Steve Demlow
	 Andreas Dilger	       Alexander Enzmann     Dan Farmer
	 Mark Gordon	       Christoph Hormann     Mike Hough
	 Chris Huff	       Kari Kivisalo	     Lutz Kretzschmar
	 Jochen	Lippert	       Pascal Massimino	     Jim McElhiney
	 Douglas Muir	       Juha Nieminen	     Bill Pulver
	 Tim Rowley	       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.

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

POV-Team			   May 2004			    POV-Ray(1)


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

home | help