imagico.de
imagico.de

imagico.de

POV-Anywhere

POV-Anywhere - Documentation

If something is not clear about the usage of the tools it is often the best idea to have a look at the code. If you have additional questions you can preferably ask them in the external linkPOV-Ray newsgroups.

What's new in version 0.3?

How does POV-Anywhere work?

POV-Anywhere is a set of independent tools that all together allow to split the render of a POV-Ray scene into several parts and render them on different computers. It has also some basic support for rendering animations.

The system used to exchange the scenes and the render results between the nodes of the distributed rendering system is quite simple. The files are stored in a directory structure called workspace and the distributed render can be accomplished by either directly accessing these files or by additional means of communication like the email module which is included in this version. I strongly encourage users to write additional tools that use other network protocols or offer a graphical user interface. The POV-Anywhere system is designed to allow such extensions, the scripts included should be understood as a reference implementation.

What is required to use POV-Anywhere?

To use POV-Anywhere you need:

Installing POV-Anywhere

On Windows systems make sure you have Cygwin correctly installed including bash, all basis packages and bc (a command line calculator that is required for POV-Anywhere).

  1. Get the POV-Anywhere from the POV-Anywhere page (if you are reading this you probably already are there).
  2. Unzip this package on your local harddisk somewhere (if you are reading this from a local file you probably already have).
  3. Open a shell (on Windows: a Cygwin shell, not a DOS Prompt).
  4. Change to the directory where you unzipped the package.
  5. Run ./install and follow the instructions.

Distributed rendering of scenes

To render a scene distributed on several computers POV-Anywhere needs to exchange data and control messages between the computers. By default this is done through a shared workspace directory but in version 0.2 there is a new mode to exchange the data via email. The email feature exchanges data between the workspaces of the different computers.

The use of the email communication system is described on a separate page, the following steps are necessary for a file system based distribution. There is a sample project prepared by the install script which can be rendered by doing steps 3 to 5. Step 1 to 3 are also necessary for the email distribution.

  1. Create an ini file for the scene to be rendered and copy it to the scenes directory together with all supplementary pov and include files.
  2. Create a project file for this ini file.
  3. Create the job files for this project with the project manager tool - this tool can also be run in loop mode to regularly do this for new projects.
  4. Start the client script on one or more computers to render the jobs, this script can run in loop mode as well.
  5. Run the project manager again when all jobs have been rendered to assemble the final image.

Description of the POV-Anywhere tools

As written above POV-Anywhere by default uses the file system to exchange data between the different computers. Even if you use a different mechanism to exchange the files (like the integrated email system) all files that have to be exchanged by default are placed in one directory, the workspace. Inside this directory are three subdirectories:

In addition the client tool has an additional directory called local workspace where the renders are made. This directory should be on a local harddisk for best performance, by default it is set to $HOME/.povany/work.

Here follows a short description of each of the scripts and programs that come with POV-Anywhere.

All tools by default are started in loop mode. With the -c option you can turn this off to run only once. In loop mode the scripts should not be stopped by pressing CTRL-C but using the stop mode (-s) of the same script. This makes sure the script exits in a clean state.

the project manager povany_pm

The purpose of this script is to insert new render projects into the POV-Anywhere system and to assemble finished renders.

When started without parameters it runs in loop mode, that means it runs in a loop until it is interrupted. The -c option can be used to turn this off. This feature is especially useful to run povany_pm automatically with cron or similar tools.

Other available command line options are:
-h <hostname>: the hostname that is used to identify the node. (if not given this is the system hostname)
-v: verbose text output to stdout
-q: minimal text output to log
-s: stop mode - send a stop signal to all running project managers
-S: force stop mode - clear the stop and running signal files
-x: clear mode - remove all generated files from projects and exit

The project manager looks for project files (extension .prj) in the jobs directory that have not yet been processed (no job files exist and the project is not marked finished). These projects are then split into tiles according to the project definition and job files are generated for the tiles.

Furthermore it checks if there are any projects where all jobs have been rendered. For these projects the partial images are compiled into the final image using the povtile program. All the partial images and the final image as well as the .finished files are then written to the result-directory - a subdirectory of jobs with the project name.

the client program povany_client

This script is designed to render the jobs generated by the project manager.

When started without parameters it runs in loop mode, that means it runs in a loop until it is interrupted. The -c option can be used to turn this off. This feature is especially useful to run povany_client automatically with cron or similar tools.

Other available command line options are:
-h <hostname>: the hostname that is used to identify the node. (if not given this is the system hostname)
-v: verbose text output to stdout
-q: minimal text output to log
-b: background mode. The POV-Ray renders are started in background then. It is recommended to use this option if the computer the client runs on is not running all the time because it makes it possible to interrupt a running render with the stop mode (see below).
-s: stop mode - send a stop signal to all running clients
-S: force stop mode - clear the stop and running signal files
-x: remove all files in local workspace after execution

The client looks for job files (extension .ini) in the jobs directory that have not yet been rendered (no .finished file in the run directory) and that have not yet been started by a client (no .run file in the run directory). The first job found is then processed in the local workspace directory and the resulting partial image is written into the run directory.

the status monitor povany_status

This tool reports the current status of the POV-Anywhere system. When called without parameters it prints the results to stdout, in addition the following options are available:
-o: display a summary of the POV-Anywhere configuration options.
-f: generate a HTML file (by default POVANY_WORKSPACE/status/status.html) instead of text.
-d: generate detailed information on the running and finished jobs, only in file mode (-f), requires ImageMagick to be installed.

the email scripts

these scripts are described in detail on a separate page.

the image tiling tool

This tool is a small C-Program that combines several partial renders from POV-Ray into a large image. It is automatically invoked by the project manager and usually does not have to be called manually. It currently only supports binary ppm/pgm images.

Usage:

  povtile 
    -g tile_width:tile_height[:total_width:total_height]
    -i input_file ... [-o <output_file>] [OPTIONS]

input_file has to be in binary ppm or pgm format. If total_width and total_height are omitted they are determined form the input files. If output_file is not specified output is written to stdout.

Available options are:
-d: write additional debug output
-v: only print version and exit
-h: print this usage info and exit

The input images have to be give line-wise, from left to right, from top to bottom according to the tiling. The program assembles the images pixel by pixel so it can handle large renders without much memory use.

Description of the used file formats

The information that needs to be exchanged between the different tools is stored in text files which are described here.

the main configuration file

The file $HOME/.povany/config contains the configuration settings for the POV-Anywhere tools and is read when a tool is started. The file is directly interpreted by the shell, it can contain any shell script code.

The following variables can be set:

Additional configuration options are described in the email system documentation

the project files

These are the files that define a render project, they are plain text containing the following definitions:

Example:

; sample project file

INI=test1.ini
RENDER_WIDTH=640
RENDER_HEIGHT=480
TILE_COUNT=8
FILES=test1.ini test1.pov

For aniamtions instead of the TILE_COUNT or TILE_SIZE field you have to define:

the job files

The job files are POV-Ray ini files that define the individual tile renders. The client copies them to the local workspace and renders them. They are generated automatically by the project manager.

the .finished files

These files exist for jobs as well as for projects. The are written by one of the scripts when the job/project is finished. They contain three strings in a single line:

  1. the name of the computer that rendered the job.
  2. the time when the job/project was started.
  3. the time when the job/project was finished.

further files related to the email communication module are described on a separate page.