xenial (1) rpiece.1.gz

NAME

       rpiece - render pieces of a RADIANCE picture

SYNOPSIS

       rpiece  [  -v  ][  -x  xres ][ -y yres ][ -X xdiv ][ -Y ydiv ][ -F|R syncfile ][ -T timelim ] [ $EVAR ] [
       @file ] [ rpict options ] -o picture octree

DESCRIPTION

       Rpiece renders a RADIANCE picture a piece at a time, calling rpict(1) to do the  actual  work.   This  is
       useful  for running multiple rpict processes on cooperating machines to render a single picture, which is
       a shared file specified with the -o option.  The overall picture dimensions will  be  xres  by  yres  (or
       smaller, depending on the -pa option and other view options), and the picture will be rendered in xdiv by
       ydiv pieces.

       There are two basic methods for telling rpiece which piece(s) of  a  picture  to  render.   The  explicit
       method  is to write on the standard input the X and Y position of the desired piece(s), where X runs from
       zero to xdiv-1 and Y runs from zero to ydiv-1.  (The lower left piece of a picture corresponds  to  (0,0)
       in  this  system.)   Alternatively,  the  implicit  specification  method  uses a synchronization file to
       determine which piece is to be rendered next.  Specified with the -F option, syncfile initially  contains
       the  values  for  xdiv  and  ydiv,  so the -X and -Y options are unnecessary.  (However, they are used if
       syncfile does not exist.)  The first rpiece process puts a lock on syncfile  and  modifies  its  contents
       before  starting  work  on  the first piece of the image.  It writes the X and Y position of the piece it
       will work on, so the next rpiece process to modify syncfile will start  on  the  next  piece.   (When  it
       finishes  with  its  piece, it appends the index to the end of syncfile.)  This procedure continues until
       all the pieces are done, at which point all of the rpiece processes will terminate.

       The -R option may be used instead of -F if some of the pieces were  not  properly  finished  by  previous
       (killed) runs of rpiece.  This option should be used by at most one rpiece process, which must be started
       first and with no other rpiece processes running or else it will rerender the same pieces other processes
       have  begun.   Once  the  recover  process  is started, you may start other rpiece processes using the -F
       option to run simultaneously.  If some processes die during execution, leaving one or more  half-finished
       pieces in the picture even though the other processes think the work is done, you may run a single rpiece
       with the -R option by itself to repair the holes.

       The -v flag switches on verbose mode, where rpiece reports to the standard output after each piece begins
       and after each piece is finished.

       Options  may  be  given  on the command line and/or read from the environment and/or read from a file.  A
       command argument beginning with a dollar sign ('$') is immediately replaced by the contents of the  given
       environment  variable.  A command argument beginning with an at sign ('@') is immediately replaced by the
       contents of the given file.

EXAMPLE

       First rpiece process is started on the machine "goober":

         goober% echo 1 8 > syncfile
         goober% echo -F syncfile -x 1024 -y 1024 -vf view -o picture octree > args
         goober% rpiece @args &

       Second rpiece processes is started on the machine "sucker":

         sucker% rpiece @args &

NOTES

       Due to NFS file buffering, the network lock manager is employed to guarantee consistency  in  the  output
       file  even  though  non-overlapping  writes are used.  This would tend to slow the process down if rpiece
       were to wait for this I/O to complete before starting  on  the  next  piece,  so  rpiece  forks  separate
       processes  to  hang around waiting for I/O completion.  The number of processes thus designated is set by
       the MAXFORK macro in the program (compiled in the src/util directory).  If the fork call  is  slow  on  a
       system,  it  may actually be better to set MAXFORK to zero.  In other cases, the network lock manager may
       be so slow that this value should be increased to get the best utilization.

       The output picture is not run-length  encoded,  and  can  be  quite  large.   The  approximate  size  (in
       kilobytes) can be computed by the simple formula:

         filesize = xres*yres/256

       Make sure that there is enough space on the filesystem to hold the entire picture before beginning.  Once
       the picture is finished, the ra_rgbe(1) program with the -r option may be used to convert to a run-length
       encoded  picture  for  more  efficient  storage,  although  pfilt(1) or any of the other Radiance picture
       filters will do the same thing.

       The ALRM signal may be used to gracefully terminate an rpiece  process  after  it  finishes  the  current
       piece.   This  permits  other  currently  running  or subsequently started rpiece process(es) to continue
       rendering the picture without loss.  The -T option  will  send  the  ALRM  signal  to  rpiece  after  the
       specified  number  of  (decimal)  hours.   This is the best way to force a time limit on the computation,
       since information will not be lost, though the process may continue for some time  afterwards  to  finish
       its current piece.

BUGS

       This  program  may  not  work  on some systems whose NFS lock manager is unreliable.  In particular, some
       System V derivative UNIX systems often have problems with the network lock manager.   If  the  output  is
       scrambled or rpict aborts with some ambient file related problem, you should just remove the ambient file
       and go back to normal rendering.

AUTHOR

       Greg Ward

SEE ALSO

       getinfo(1), pfilt(1), ra_rgbe(1), rpict(1), ximage(1)