Documentation:Unix Section 3

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.