Difference between revisions of "Documentation:Unix Section 3"

From POV-Wiki
Jump to navigation Jump to search
m (Protected "Documentation:Unix Section 3" [edit=sysop:move=sysop])
m (→‎X Window display: canonicalize a version number)
 
(16 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
<br>
 
<br>
 
<!--</wikitalk>--->
 
<!--</wikitalk>--->
===Getting Started===
+
==Getting Started==
<p>
+
<p>This section will help new users get started with POV-Ray for Unix.</p>
This section will help new users get started with POV-Ray for Unix.
 
</p>
 
  
 
===Available distributions===
 
===Available distributions===
<p>
+
<p>The <em>official</em> distribution for version 3.8 of POV-Ray for Unix is a source code <em>only</em> release. This package contains all the source files and Makefiles required for building POV-Ray.  Building the program from source should work on most Unix/Linux systems. The package uses a configuration mechanism to detect the appropriate settings needed to build POV-Ray on your platform. Since all the required support libraries are <em>NOT</em> included in the package, you need to make sure you have an adequate build environment.</p>
There are two official distributions of POV-Ray for Unix available:
 
</p>
 
  
<ul>
+
<p>The distribution package is available for download via the POV-Ray [http://www.povray.org/ website]. See the INSTALL file in the source package for more details.</p>
<li><em>Source package:</em> this package contains all the source
 
files and Makefiles required for building POV-Ray. Building the
 
program from source should work on most Unix systems. The package
 
uses a configuration mechanism to detect the adequate settings
 
in order to build POV-Ray on your own platform. All required
 
support libraries are included in the package.  See the INSTALL
 
file of the source package for details.</li>
 
  
<li><em>Linux binary package:</em> this package contains a
+
===Configuration===
compiled version of POV-Ray for x86-compatible platforms running
+
<p>All official versions of POV-Ray for Unix come with procedures for correctly installing and configuring POV-RayThese explanations are for reference.</p>
the GNU/Linux operating systemA shell script for easy installation
 
is also included. Further details are given in the README file of
 
this package.</li>
 
</ul>
 
  
<p>
+
====The I/O Restrictions configuration file====
Both distributions are available for download at the  
+
<p>When POV-Ray starts it reads the configuration for the I/O Restriction feature from the <code>povray.conf</code> files.  See the <!--<linkto "I/O Restrictions">I/O Restrictions Documentation</linkto>--->[[Documentation:Unix Section 4#I/O Restrictions|I/O Restrictions Documentation]] for a description of these files.</p>
[http://www.povray.org/|_new <span title="Opens A New Window!">POV-Ray website</span>]
 
and on the POV-Ray FTP server (<code>ftp.povray.org</code>).
 
</p>
 
  
===Configuration===
+
====The main POV-Ray INI file====
<p>
+
<p>When starting, POV-Ray for UNIX searches for an INI file containing default configuration options.  The details can be found in the <!--<linkto "INI Files">INI File Documentation</linkto>--->[[Documentation:Tutorial Section 2.2#Using INI Files|INI File Documentation]].</p>
All official versions of POV-Ray for Unix come with procedures for
 
correctly installing and configuring POV-Ray. These explanations are
 
for reference.
 
</p>
 
  
===The I/O Restrictions configuration file===
+
===Starting a Render Job===
<p>
+
<p>Starting POV-Ray rendering any scene file is as simple as running <code>povray</code> from a command-line with the scene file name as an argumentThis will work with either a POV file or an INI file (as long as it has an associated POV file). See <!--<linkto "Understanding File Types">Understanding File Types</linkto>--->[[Documentation:Unix Section 5#Understanding File Types|Understanding File Types]]. The scene is rendered with the current POV-Ray 3 options (see
When POV-Ray starts it reads the configuration for the I/O Restriction
+
<!--<linkto "Understanding POV-Ray Options">Understanding POV-Ray Options</linkto>--->[[Documentation:Unix Section 6#Understanding POV-Ray Options|Understanding POV-Ray Options]]).</p>
feature from the <code>povray.conf</code> files.  See the  
 
<!--<linkto "I/O Restrictions">I/O Restrictions Documentation</linkto>--->[[Documentation:Unix Section 2#I/O Restrictions|I/O Restrictions Documentation]] for a
 
description of these files.
 
</p>
 
  
===The main POV-Ray INI file===
+
<p class="Note"><strong>Note:</strong> One of the more common errors new users make is turning off the display option. The Display option <code>+d</code> is ON by default. If you turn this OFF in the INI file or on the command
<p>
+
line, POV-Ray will not display the file as you render.</p>
When starting, POV-Ray for UNIX searches for an INI file
 
containing default configuration options. The details can be found in the
 
<!--<linkto "INI Files">INI File Documentation</linkto>--->[[Documentation:Tutorial Section 2.2#Using INI Files|INI File Documentation]].
 
</p>
 
  
===Starting a Render Job===
+
<p>Please also note that POV-Ray for Unix will write the output file to a .png by default. There is no way to 'save the render window' after rendering is completed. If you turned file output off before starting the render, and change your mind, you will have to start the rendering all over again. We recommend that you just leave file output on all the time.</p>
<p>
 
Starting POV-Ray rendering any scene file is as simple as running <code>povray</code> from a command-line
 
with the scene file name as an argument.  This will work with either a POV file or an INI
 
file (as long as it has an associated POV file). See
 
<!--<linkto "Understanding File Types">Understanding File Types</linkto>--->[[Documentation:Unix Section 5#Understanding File Types|Understanding File Types]]. The scene is rendered
 
with the current POV-Ray 3 options (see
 
<!--<linkto "Understanding POV-Ray Options">Understanding POV-Ray Options</linkto>--->[[Documentation:Unix Section 6#Understanding POV-Ray Options|Understanding POV-Ray Options]]).
 
</p>
 
<p class="Note"><strong>Note:</strong>
 
One of the more common errors new users make is turning off the display option. The
 
Display option (<code>+d</code>) is ON by default. If you turn this OFF in the INI file or on the command
 
line, POV-Ray will not display the file as you render.
 
</p>
 
<p>
 
Please also note that POV-Ray for Unix will write the output file to a .png by default.
 
There is no way to 'save the render window' after rendering is completed. If you turned file
 
output off before starting the render, and change your mind, you will have to start the
 
rendering all over again. We recommend that you just leave file output on all the time.
 
</p>
 
  
===X Window display===
+
====X Window display====
<p>
+
<p>When the X Window display is used, the rendered image is displayed in a graphics window. During rendering, the window will be updated after every scanline has been rendered, or sooner if the rendering is taking a long time.  To update it sooner you can click any mouse button in the window or press (almost) any key.  Pressing <code>&lt;CTRL-R&gt;</code> or <code>&lt;CTRL-L&gt;</code> during rendering will refresh the whole screen.  If you have the <code>Exit_Enable</code> or <code>+X</code> flag set, pressing 'q' or 'Q' at any time during the rendering will stop POV-Ray rendering and exit.  The rendering will pause when complete if the <code>Pause_When_Done</code> or <code>+P</code> flag is set.  To exit at this point, press the 'q' or 'Q' key or click any mouse button in the window.</p>
When the X Window display is used, the rendered image is displayed in a
 
graphics window. During rendering, the window will be updated after  
 
every scanline has been rendered, or sooner if the rendering is taking  
 
a long time.  To update it sooner you can click any mouse button in  
 
the window or press (almost) any key.  Pressing <code>&lt;CTRL-R&gt;</code>  
 
or <code>&lt;CTRL-L&gt;</code> during
 
rendering will refresh the whole screen.  If you have the <code>Exit_Enable</code>
 
or <code>+X</code> flag set, pressing 'q' or 'Q' at any time during the rendering
 
will stop POV-Ray rendering and exit.  The rendering will pause when
 
complete if the <code>Pause_When_Done</code> (or <code>+P</code>) flag is set.  To exit at
 
this point, press the 'q' or 'Q' key or click any mouse button in
 
the window.
 
</p>
 
  
<p>
+
<p>POV-Ray v3.7 includes a color icon in the program if it was compiled with libXpm (which is available on most platforms where the X Window System is installed). If this icon is used for the render view window depends on the window manager
POV-Ray 3.6 includes a color icon in the program if it was compiled with libXpm (which is available on most platforms where the X Window System is installed).  
+
being used (KDE, Gnome, fvwm, or ...). POV-Ray also comes with a separate color icon <code>xpovicon.xpm</code>
If this icon is used for the render view window depends on the window manager
+
for use with the window managers that can use external icons.  For instance, to have fvwm use this icon, copy the icon file to one of the directories pointed to by PixmapPath (or ImagePath) which is defined in your <code>$HOME/.fvwmrc</code>.  Then, add the following line in <code>$HOME/.fvwmrc</code>:</p>
being used (KDE, Gnome, fvwm, ...).
 
POV-Ray also comes with a separate color icon (<code>xpovicon.xpm</code>)
 
for use with the window
 
managers that can use external icons.  For instance, to have fvwm use this icon,
 
copy the icon file to one of the directories pointed to by PixmapPath (or ImagePath)
 
which is defined in your <code>$HOME/.fvwmrc</code>.  Then, add the following line
 
in <code>$HOME/.fvwmrc</code>:
 
</p>
 
  
 
<pre>Style &quot;Povray&quot; Icon xpovicon.xpm</pre>
 
<pre>Style &quot;Povray&quot; Icon xpovicon.xpm</pre>
  
<p>
+
<p>and re-start the X Window server, re-starting fvwm will not be enough. Using this icon with another window manager may use a different procedure.</p>
and re-start the X Window server (re-starting fvwm will not be enough).
 
Using this icon with another window manager may use a different procedure.
 
</p>
 
  
<p>
+
<p>Documentation of the special command line options to configure the X Window display can be found in <!--<linkto "Special Command-Line Options">Special Command-Line Options</linkto>--->[[Documentation:Unix Section 6#Special Command-Line Options|Special Command-Line Options]].</p>
Documentation of the special command line options to configure the  
 
X Window display can be found in
 
<!--<linkto "Special Command-Line Options">Special Command-Line Options</linkto>--->[[Documentation:Unix Section 6#Special Command-Line Options|Special Command-Line Options]].
 
</p>
 
  
===SVGAlib display===
+
====SVGAlib display====
<p>
+
<p>For GNU/Linux systems that don't have the X Window System installed, or for those Linux users who prefer to run on the console, it is possible to use the SVGA library to display directly to the screen.  For SVGAlib display, the <code>povray</code> binary must be installed as a setuid root executable. If POV-Ray does not use SVGAlib display, first try as root:</p>
For GNU/Linux systems that don't have the X Window System installed,
 
or for those Linux users who prefer to run on the console,
 
it is possible to use the SVGA library to display directly to the
 
screen.  For SVGAlib display, the
 
<code>povray</code> binary must be installed as a setuid root executable.
 
If POV-Ray does not use SVGAlib display, first try (as root):
 
</p>
 
  
 
<pre>
 
<pre>
Line 138: Line 54:
 
</pre>
 
</pre>
  
<p class="Note"><strong>Note:</strong>
+
<p class="Note"><strong>Note:</strong> Doing this may have serious security implications.  Running POV-Ray as root or through 'sudo' might be a better idea.</p>
Doing this may have serious security implications.  Running
 
POV-Ray as root or through 'sudo' might be a better idea.
 
</p>
 
  
<p>
+
<p>If it still doesn't work then make sure SVGAlib is installed on your machine and works properly.  Anything that can at least use the 320x200x256 mode (regular VGA) should be fine, although modes up to 1280x1024x16M are possible.  If you do not have root privileges or can't have the system admin install POV-Ray, then you must use the X Window or text display which do not require any special system privileges to run.  If you are using a display resolution that is lower than what you are rendering, the display will be scaled to fit as much of the viewing window as possible.</p>
If it still doesn't work then make sure SVGAlib is installed on your
 
machine and works properly.  Anything that can at least use the  
 
320x200x256 mode (ie regular VGA) should be fine, although modes up to  
 
1280x1024x16M are possible.  If you do not have root priviledges or  
 
can't have the system admin install POV-Ray, then you must use the  
 
X Window or text display which do not require any special system  
 
priviledges to run.  If you are using a display resolution that is  
 
lower than what you are rendering, the display will be scaled to fit  
 
as much of the viewing window as possible.
 
</p>
 
  
===Output file formats===
+
====Output file formats====
<p>
+
<p>The default output file format of POV-Ray for Unix is PNG, or <code>+fn</code>.</p>
The default output file format of POV-Ray for Unix
+
<p>This can be changed at runtime by setting the <code>Output_File_Type</code> or <code>+fx</code> option.</p> <p>Alternately the default format can be changed at compile time by changing <code>DEFAULT_OUTPUT_FORMAT</code> in the <code>syspovconfig.h</code> file located in the <code>~vfe/unix</code> directory of the source code distribution.</p>
is PNG (+fn). This can be changed at runtime by setting the
 
<code>Output_File_Type</code> or <code>+fx</code> option.
 
Eventually, the default format can be changed at compile time
 
by setting <code>DEFAULT_FILE_FORMAT</code> in the  
 
<code>config.h</code> file located in the unix/ directory.
 
</p>
 
  
<p>  
+
<p>Other convenient formats on Unix systems might be PPM <code>+fp</code> and TGA <code>+ft</code>.</p>
Other convenient formats on Unix systems might be PPM (+fp)
+
<p>For more information about output file formats see <!--<linkto "File Output Options">File Output Options</linkto>--->[[Reference:File Output Options|File Output Options]].</p>
and TGA (+ft). For more information about output file formats see
 
<!--<linkto "File Output Options">File Output Options</linkto>--->[[Documentation:Reference Section 1.1#File Output Options|File Output Options]].
 
</p>
 
  
<p>  
+
<p> If you are generating histogram files (See <!--<linkto "CPU Utilization Histogram">CPU Utilization Histogram</linkto>--->[[Reference:File Output Options#CPU Utilization Histogram|CPU Utilization Histogram]]) in the CSV format (comma separated values), then the units of time are in tens of microseconds (10 x 10<sup>-6</sup> s), and each grid block can store times up to 12 hours.</p>
If you are generating histogram files  
 
(See <!--<linkto "CPU Utilization Histogram">CPU Utilization Histogram</linkto>--->[[Documentation:Reference Section 1.1#CPU Utilization Histogram|CPU Utilization Histogram]])
 
in the CSV format (comma separated values), then the units of time are in  
 
tens of microseconds (10 x 10<sup>-6</sup> s), and each grid block can store times up  
 
to 12 hours.
 
</p>
 
  
 
===Interrupting POV-Ray===
 
===Interrupting POV-Ray===
<p>
+
<p>To interrupt a rendering in progress, you can use CTRL-C (SIGINT), which will allow POV-Ray to finish writing out any rendered data before it quits.  When graphics display mode is used, you can also press the 'q' or 'Q' keys in the rendering preview window to interrupt the trace if the <code>Test_Abort</code> or <code>+X</code> flag is set.</p>
To interrupt a rendering in progress, you can use CTRL-C (SIGINT),
 
which will allow POV-Ray to finish writing out any rendered data
 
before it quits.  When graphics display mode is used, you can also press
 
the 'q' or 'Q' keys in the rendering preview window to interrupt the
 
trace if the Test_Abort (or +X) flag is set.
 
</p>
 
  
 
===Tutorials===
 
===Tutorials===
<p>
+
<p>There is a comprehensive <!--<linkto "Getting Started">beginner's tutorial</linkto>--->[[Documentation:Tutorial Section 2#Getting Started|beginner's tutorial]] included in this help file. It relates to the use of POV-Ray in general, on all platforms, not only Unix, so we recommend that you read the rest of section 1 first before attempting to go any further, as section 1 tells you how to use the interface of POV-Ray for Unix itself. The more ambitious may like to check out the <!--<linkto "Advanced Features">advanced features</linkto>--->[[Documentation:Tutorial Section 3#Advanced Features|advanced features]] section.</p>
There is a comprehensive <!--<linkto "Getting Started">beginner's tutorial</linkto>--->[[Documentation:Tutorial Section 2#Getting Started|beginner's tutorial]] included in
 
this help file. It relates to the use of POV-Ray in general (i.e. on all platforms, not only
 
Unix), so we recommend that you read the rest of section 1 first before attempting to go
 
any further, as section 1 tells you how to use the interface of POV-Ray for Unix itself.
 
The more ambitious may like to check out the <!--<linkto "Advanced Features">advanced features</linkto>--->[[Documentation:Tutorial Table of Contents#Advanced Features|advanced features]]
 
section.
 
</p>
 
  
 
===Rendering the Sample Scenes===
 
===Rendering the Sample Scenes===
<p>
+
<p>POV-Ray for Unix comes with a set of shell scripts to automatically render the sample scenes coming with POV-Ray.</p>
POV-Ray for Unix comes with a set of shell scripts to automatically  
 
render the sample scenes coming with POV-Ray.
 
</p>
 
  
<p>
+
<p>These shell scripts are usually installed in <code>/usr/local/share/povray/vX.y/scripts</code>.  They require a bash  
These shell scripts are usually installed in  
+
compatible shell.  There are three scripts that are supposed to be called by the user.</p>
<code>/usr/local/share/povray-3.6/scripts</code>.  They require a bash  
 
compatible shell.  There are three scripts that are supposed to be  
 
called by the user.
 
</p>
 
  
 
<ul>
 
<ul>
 
<li><code>allscene.sh</code>:
 
<li><code>allscene.sh</code>:
<p>
+
<p>renders all stills.  The syntax is:</p>
renders all stills.  The syntax is:
+
<pre>allscene.sh [log] [all] [-d scene_directory] [-o output_directory] [-h html_file]</pre>
</p>
+
<p>If <code>html_file</code> is specified a HTML listing of the rendered scenes is generated. If [http://www.imagemagick.org/ ImageMagick] is installed the listing will also contain thumbnails of the rendered images.
    <pre>allscene.sh [log] [all] [-d scene_directory] [-o output_directory] [-h html_file]</pre>
 
<p>
 
If <code>html_file</code> is specified a HTML listing of the rendered scenes is generated.
 
if [http://www.imagemagick.org/|_new <span title="Opens A New Window!">ImageMagick</span>] is installed the  
 
listing will also contain thumbnails of the rendered images.
 
 
</p>
 
</p>
  
 
<li><code>allanim.sh</code>:
 
<li><code>allanim.sh</code>:
<p>
+
<p>renders all animations.  The syntax is:</p>
renders all animations.  The syntax is:
+
<pre>allanim.sh [log] [-d scene_directory] [-o output_directory] [-h html_file]</pre>
</p>
+
<p>If [http://ffmpeg.org/ ffmpeg] is installed the script will compile mpeg files from the rendered animations.</p>
    <pre>allanim.sh [log] [-d scene_directory] [-o output_directory] [-h html_file]</pre>
 
<p>
 
If [http://ffmpeg.sourceforge.net/|_new <span title="Opens A New Window!">ffmpeg</span>] is installed
 
the script will compile mpeg files from the rendered animations.
 
</p>
 
  
 
<li><code>portfolio.sh</code>:
 
<li><code>portfolio.sh</code>:
<p>
+
<p>renders the portfolio.  The syntax is:</p>
renders the portfolio.  The syntax is:
+
<pre>portfolio.sh [log] [-d scene_directory] [-o output_directory]</pre>
</p>
+
<p>The portfolio is a collection of images illustrating the POV-Ray features and include files coming with the package.</p>
    <pre>portfolio.sh [log] [-d scene_directory] [-o output_directory]</pre>
 
<p>
 
The portfolio is a collection of images illustrating the POV-Ray features
 
and include files coming with the package.
 
</p>
 
 
</ul>
 
</ul>
  
<p>
+
<p>If the option <code>log</code> is specified, a log file with the complete text output from POV-Ray is written to filename <code>log.txt</code></p>
If the option <code>log</code> is specified, a log file with the complete text output from
 
POV-Ray is written (filename <code>log.txt</code>)
 
</p>
 
  
<p>
+
<p>If <code>scene_directory</code> is specified, the sample scenes in this directory are rendered, otherwise the scene directory is determined form the main povray ini file, usually <code>/usr/local/share/povray/vX.y/scenes</code>.</p>
If <code>scene_directory</code> is specified, the sample scenes in this directory  
 
are rendered, otherwise the scene directory is determined form the main  
 
povray ini file (usually <code>/usr/local/share/povray-3.6/scenes</code>).
 
</p>
 
  
<p>
+
<p>If <code>output_directory</code> is specified, all images are written to this directory; if it is not specified the images are written into the scene file directories.  If the directories are not writable, the images are written in the current directory.  All other files (html files, thumbnails) are written here as well.</p>
If <code>output_directory</code> is specified, all images are written to  
 
this directory; if it is not specified the images are written into the scene  
 
file directories.  If the directories are not writable, the images are written in the current  
 
directory.  All other files (html files, thumbnails) are written here as well.
 
</p>
 
  
<p>
+
<p>To determine the correct render options the scripts analyze the beginning of the scene files.  They search for a comment of the form:</p>
To determine the correct render options the scripts analyze the beginning of
 
the scene files.  They search for a comment of the form
 
</p>
 
  
 
<pre>// -w320 -h240 +a0.3</pre>
 
<pre>// -w320 -h240 +a0.3</pre>
  
<p>
+
<p>in the first 50 lines of the scene.  The animation script possibly also uses an INI file with the same basename as the scene file.  The <code>allscene.sh</code> has the additional <code>all</code> option which <em>if specified</em> renders also scenes without such an options comment (using default options then).</p>
in the first 50 lines of the scene.  The animation script possibly also uses an INI  
 
file with the same basename as the scene file.  The <code>allscene.sh</code> has
 
the additional <code>all</code> option which - if specified - renders also scenes
 
without such an options comment (using default options then).
 
</p>
 
  
 
===POV-Ray for Unix Tips===
 
===POV-Ray for Unix Tips===
  
  
===Automated execution===
+
====Automated execution====
<p>
+
<p>POV-Ray for Unix is well suited for automated execution, for example, for rendering diagrams displaying statistical data on a regular basis or similar things.</p>
POV-Ray for Unix is well suited for automated execution, for example, for
 
rendering diagrams displaying statistical data on a regular basis or similar things.
 
</p>
 
  
<p>
+
<p>POV-Ray can also write its image output directly to stdout.  Therefore the image data can be piped in another program for further processing.  To do this the special output filename '-' needs to be specified.  For instance:</p>
POV-Ray can also write its image output directly to stdout.  Therefore the
 
image data can be piped in another program for further processing.  To do this
 
the special output filename '-' needs to be specified.  For instance:
 
</p>
 
  
 
<pre>
 
<pre>
Line 295: Line 121:
 
</pre>
 
</pre>
  
<p>
+
<p>will pass the image data to the <code>cjpeg</code> utility which writes the image in the JPEG format.</p>
will pass the image data to the <code>cjpeg</code> utility which writes the
 
image in the JPEG format.
 
</p>
 
  
<p>
+
<p>The text output of POV-Ray is always written to stderr, it can be redirected to a file with (using a Bourne-compatible shell):</p>
The text output of POV-Ray is always written to stderr, it can be redirected  
 
to a file with (using a Bourne-compatible shell):
 
</p>
 
  
 
<pre>
 
<pre>
Line 309: Line 129:
 
</pre>
 
</pre>
  
<p>
+
<p>See also <!--<linkto "Directing Text Streams to Files">Directing Text Streams to Files</linkto>--->[[Reference:Text Output Options#Directing Text Streams to Files|Directing Text Streams to Files]].</p>
See also <!--<linkto "Directing Text Streams to Files">Directing Text Streams to Files</linkto>--->[[Documentation:Reference Section 1.3#Directing Text Streams to Files|Directing Text Streams to Files]].
 
</p>
 
  
<p>
+
<p>For remote execution of POV-Ray, as for example in a rendering service on the web, make sure you read and comply with the <!--<linkto "POV-Ray License">POV-Ray License</linkto>--->[[Documentation:Tutorial Section 5#POV-Ray License|POV-Ray Legal Document]].</p>
For remote execution of POV-Ray, as for example in a rendering service on the
 
web, make sure you read and comply with the  
 
<!--<linkto "POV-Ray Legal Document">POV-Ray Legal Document</linkto>--->[[Documentation:Tutorial Section 5#POV-Ray User License|POV-Ray Legal Document]].
 
</p>
 
  
===Post-processing Images===
+
====Post-processing Images====
<p>
+
<p>For Unix systems, the PBM utilities ([http://www.acme.com/software/pbmplus PBMPLUS], [http://netpbm.sourceforge.net NetPBM]) and [http://www.imagemagick.org ImageMagick] are an excellent choice for post-processing utilities, especially if you only have a command-line interface to Unix.</p>
For Unix systems, the PBM utilities
 
([http://www.acme.com/software/pbmplus|_new <span title="Opens A New Window!">PBMPLUS</span>],
 
[http://netpbm.sourceforge.net|_new <span title="Opens A New Window!">NetPBM</span>])
 
and [http://www.imagemagick.org|_new <span title="Opens A New Window!">ImageMagick</span>]
 
are an excellent choice for post-processing utilities, especially if
 
you only have a command-line interface to Unix.
 
</p>
 
  
 
<!--<wikinav>--->
 
<!--<wikinav>--->

Latest revision as of 15:38, 9 June 2021

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.


Getting Started

This section will help new users get started with POV-Ray for Unix.

Available distributions

The official distribution for version 3.8 of POV-Ray for Unix is a source code only release. This package contains all the source files and Makefiles required for building POV-Ray. Building the program from source should work on most Unix/Linux systems. The package uses a configuration mechanism to detect the appropriate settings needed to build POV-Ray on your platform. Since all the required support libraries are NOT included in the package, you need to make sure you have an adequate build environment.

The distribution package is available for download via the POV-Ray website. See the INSTALL file in the source package for more details.

Configuration

All official versions of POV-Ray for Unix come with procedures for correctly installing and configuring POV-Ray. These explanations are for reference.

The I/O Restrictions configuration file

When POV-Ray starts it reads the configuration for the I/O Restriction feature from the povray.conf files. See the I/O Restrictions Documentation for a description of these files.

The main POV-Ray INI file

When starting, POV-Ray for UNIX searches for an INI file containing default configuration options. The details can be found in the INI File Documentation.

Starting a Render Job

Starting POV-Ray rendering any scene file is as simple as running povray from a command-line with the scene file name as an argument. This will work with either a POV file or an INI file (as long as it has an associated POV file). See Understanding File Types. The scene is rendered with the current POV-Ray 3 options (see Understanding POV-Ray Options).

Note: One of the more common errors new users make is turning off the display option. The Display option +d is ON by default. If you turn this OFF in the INI file or on the command line, POV-Ray will not display the file as you render.

Please also note that POV-Ray for Unix will write the output file to a .png by default. There is no way to 'save the render window' after rendering is completed. If you turned file output off before starting the render, and change your mind, you will have to start the rendering all over again. We recommend that you just leave file output on all the time.

X Window display

When the X Window display is used, the rendered image is displayed in a graphics window. During rendering, the window will be updated after every scanline has been rendered, or sooner if the rendering is taking a long time. To update it sooner you can click any mouse button in the window or press (almost) any key. Pressing <CTRL-R> or <CTRL-L> during rendering will refresh the whole screen. If you have the Exit_Enable or +X flag set, pressing 'q' or 'Q' at any time during the rendering will stop POV-Ray rendering and exit. The rendering will pause when complete if the Pause_When_Done or +P flag is set. To exit at this point, press the 'q' or 'Q' key or click any mouse button in the window.

POV-Ray v3.7 includes a color icon in the program if it was compiled with libXpm (which is available on most platforms where the X Window System is installed). If this icon is used for the render view window depends on the window manager being used (KDE, Gnome, fvwm, or ...). POV-Ray also comes with a separate color icon xpovicon.xpm for use with the window managers that can use external icons. For instance, to have fvwm use this icon, copy the icon file to one of the directories pointed to by PixmapPath (or ImagePath) which is defined in your $HOME/.fvwmrc. Then, add the following line in $HOME/.fvwmrc:

Style "Povray" Icon xpovicon.xpm

and re-start the X Window server, re-starting fvwm will not be enough. Using this icon with another window manager may use a different procedure.

Documentation of the special command line options to configure the X Window display can be found in Special Command-Line Options.

SVGAlib display

For GNU/Linux systems that don't have the X Window System installed, or for those Linux users who prefer to run on the console, it is possible to use the SVGA library to display directly to the screen. For SVGAlib display, the povray binary must be installed as a setuid root executable. If POV-Ray does not use SVGAlib display, first try as root:

chown root.root povray
chmod 4755 povray

Note: Doing this may have serious security implications. Running POV-Ray as root or through 'sudo' might be a better idea.

If it still doesn't work then make sure SVGAlib is installed on your machine and works properly. Anything that can at least use the 320x200x256 mode (regular VGA) should be fine, although modes up to 1280x1024x16M are possible. If you do not have root privileges or can't have the system admin install POV-Ray, then you must use the X Window or text display which do not require any special system privileges to run. If you are using a display resolution that is lower than what you are rendering, the display will be scaled to fit as much of the viewing window as possible.

Output file formats

The default output file format of POV-Ray for Unix is PNG, or +fn.

This can be changed at runtime by setting the Output_File_Type or +fx option.

Alternately the default format can be changed at compile time by changing DEFAULT_OUTPUT_FORMAT in the syspovconfig.h file located in the ~vfe/unix directory of the source code distribution.

Other convenient formats on Unix systems might be PPM +fp and TGA +ft.

For more information about output file formats see File Output Options.

If you are generating histogram files (See CPU Utilization Histogram) in the CSV format (comma separated values), then the units of time are in tens of microseconds (10 x 10-6 s), and each grid block can store times up to 12 hours.

Interrupting POV-Ray

To interrupt a rendering in progress, you can use CTRL-C (SIGINT), which will allow POV-Ray to finish writing out any rendered data before it quits. When graphics display mode is used, you can also press the 'q' or 'Q' keys in the rendering preview window to interrupt the trace if the Test_Abort or +X flag is set.

Tutorials

There is a comprehensive beginner's tutorial included in this help file. It relates to the use of POV-Ray in general, on all platforms, not only Unix, so we recommend that you read the rest of section 1 first before attempting to go any further, as section 1 tells you how to use the interface of POV-Ray for Unix itself. The more ambitious may like to check out the advanced features section.

Rendering the Sample Scenes

POV-Ray for Unix comes with a set of shell scripts to automatically render the sample scenes coming with POV-Ray.

These shell scripts are usually installed in /usr/local/share/povray/vX.y/scripts. They require a bash compatible shell. There are three scripts that are supposed to be called by the user.

  • allscene.sh:

    renders all stills. The syntax is:

    allscene.sh [log] [all] [-d scene_directory] [-o output_directory] [-h html_file]

    If html_file is specified a HTML listing of the rendered scenes is generated. If ImageMagick is installed the listing will also contain thumbnails of the rendered images.

  • allanim.sh:

    renders all animations. The syntax is:

    allanim.sh [log] [-d scene_directory] [-o output_directory] [-h html_file]

    If ffmpeg is installed the script will compile mpeg files from the rendered animations.

  • portfolio.sh:

    renders the portfolio. The syntax is:

    portfolio.sh [log] [-d scene_directory] [-o output_directory]

    The portfolio is a collection of images illustrating the POV-Ray features and include files coming with the package.

If the option log is specified, a log file with the complete text output from POV-Ray is written to filename log.txt

If scene_directory is specified, the sample scenes in this directory are rendered, otherwise the scene directory is determined form the main povray ini file, usually /usr/local/share/povray/vX.y/scenes.

If output_directory is specified, all images are written to this directory; if it is not specified the images are written into the scene file directories. If the directories are not writable, the images are written in the current directory. All other files (html files, thumbnails) are written here as well.

To determine the correct render options the scripts analyze the beginning of the scene files. They search for a comment of the form:

// -w320 -h240 +a0.3

in the first 50 lines of the scene. The animation script possibly also uses an INI file with the same basename as the scene file. The allscene.sh has the additional all option which if specified renders also scenes without such an options comment (using default options then).

POV-Ray for Unix Tips

Automated execution

POV-Ray for Unix is well suited for automated execution, for example, for rendering diagrams displaying statistical data on a regular basis or similar things.

POV-Ray can also write its image output directly to stdout. Therefore the image data can be piped in another program for further processing. To do this the special output filename '-' needs to be specified. For instance:

povray -iscene.pov +fp -o- | cjpeg > scene.jpg

will pass the image data to the cjpeg utility which writes the image in the JPEG format.

The text output of POV-Ray is always written to stderr, it can be redirected to a file with (using a Bourne-compatible shell):

povray [Options] 2> log.txt

See also Directing Text Streams to Files.

For remote execution of POV-Ray, as for example in a rendering service on the web, make sure you read and comply with the POV-Ray Legal Document.

Post-processing Images

For Unix systems, the PBM utilities (PBMPLUS, NetPBM) and ImageMagick are an excellent choice for post-processing utilities, especially if you only have a command-line interface to Unix.


KDE Integration I/O Restrictions


This document is protected, so submissions, corrections and discussions should be held on this documents talk page.