Tutorial for Handling Files
===========================

Content
This tutorial shows how to pass files to and from a remote host. In the example
a tool is developed which allows you to distribute the task of rendering POV
files across a NetSolve network. Povray is executed at the servers to render a
part of the picture and the parts from all the server are put together from the
client. The tutorial includes the following steps:

  1. building and configuring the library
  2. installing the problem to the NetSolve repository
  3. rendering a test image via NetSolve


Requirements
o on each server
  o libpovray.c
  o povray.idl - a file which describes how the problem should be included
               into the NetSolve repository (Interface Definition Language)
  o the image renderer PovRay - available at http://www.povray.org/
o on the client
  o nspovray.c - the client program which invokes the various instances of
    PovRay via NetSolve and puts together the final image
  o *.pov and *.ini - sample PovRay files
  o the image processing tool ImageMagick - available at
    http://www.imagemagick.org/
  o the mpeg encoder mpeg_encode - available at
    http://bmrc.berkeley.edu/frame/research/mpeg/mpeg_encode.html
  o the Netpbm library - available at
    http://netpbm.sourceforge.net/
  o Multiple Move (mmv) - available at
    http://http.us.debian.org/debian/pool/main/m/mmv/mmv_1.01b.orig.tar.gz



Instructions
------------

1. Building and Configuring the Library
o At first make sure to have a working copy of PovRay
  (http://www.povray.org/) on the server. Either it is already installed or
  otherwise download it and run(configure and make). To test povray try to
  render a POV file on the server,e.g. (assuming icl.pov in the current
  directory):
  $ /home/user/povray/src/povray +Iicl.pov +Oicl.png +L/home/user/povray/include

o edit libpovray.c and provide in the first two lines the povray executable (if
  the executable is not in your PATH include the path) and the path to the
  PovRay include directory (contains all the INC files)

o execute the following steps to build libpovray.a
  $ gcc -c libpovray.c
  $ ar rc libpovray.a libpovray.o


2. Installing the Problem to the NetSolve Repository
Use idltopdf to convert povray.idl to povray.pdf. Then copy the PDF to your 
problems subdirectory and add an entry in the file 'server_config'. Set 
NSPOVRAY_LIB to the path where libpovray.a is located and recompile the
server with the command
$ make server

Note: Since the library makes an external call to a programm it can not take
advantage of the Hardware- / Softwareserver feature of NetSolve (i.e., it
cannot be transfered from one server to another). To mark a problem as 
non-moveable use the keyword NONMOVEABLE in the IDL.


3. Rendering a Test Image Via NetSolve
The file nspovray.c demonstrates how to invoke the newly created function povray
via NetSolve.
o edit nspovray.c and provide in the first three lines the path to ImageMagick,
  mpeg_encode and mmv.
o edit animation.parm and set in the 4. line the path to the programm tgatoppm
  if it is not in your path.
o Compile nspovray then with the following command:

$ gcc nspovray.c -o nspovray -I$NETSOLVE_ROOT/include -lnetsolve \
      -L$NETSOLVE_ROOT/lib/$NETSOLVE_ARCH

Note: On Solaris you may also need to add the following two libraries:
  -lsocket lnsl

To render an example file you have the following options:
o blocking calls: provides exactly the same syntax as calling povray, but use
  the command nspovray instead; e.g.:
  $ ./nspovray +Iicl.pov +Oicl.png +H400 +W500

o non-blocking calls: uses non-blocking calls and is invoked with the option
  '-nonblocking'; additionally you can specify with the '-n' option how many
  instances (= parallel NetSolve calls) you want to start;e.g.:
  $ ./nspovray +Iicl1.pov +Oicl1.png +H400 +W500 -n2 -nonblocking

o task-farming: again as above but use with the option '-farming'; to produce an
  animation use for example:
  $ ./nspovray icl_animation.ini -oanimation.mpg -n2 -farming

Note: Be sure to have an agent and at least one instance of the new server
running. Also check that the NETSOLVE_AGENT enironment variable is set on the
client (it should be the same value as the "@AGENT:" line in server_config in
the NetSolve directory).


Last modified: July 27th, 2003
Christoph L. Fabianek, fabianek@cs.utk.edu
