RANIMATE(1)                                                        RANIMATE(1)



NNAAMMEE
       ranimate - compute a RADIANCE animation

SSYYNNOOPPSSIISS
       rraanniimmaattee [ --ss ][ --nn ][ --ee ][ --ww ] rraannffiillee

DDEESSCCRRIIPPTTIIOONN
       _R_a_n_i_m_a_t_e is an executive program that reads the given _r_a_n_f_i_l_e and makes
       appropriate calls to _r_a_d_(_1_)_, _r_p_i_c_t_(_1_)_, _p_i_n_t_e_r_p_(_1_)_, and/or  _p_f_i_l_t_(_1_)  to
       render  an  animation.   Variables  in  _r_a_n_f_i_l_e  indicate  input files,
       process servers (execution hosts), output directories and  file  names,
       and various other controls and options.

       Normally,  commands  are echoed to the standard output as they are exe-
       cuted.  The _-_s option tells _r_a_n_i_m_a_t_e to do its work silently.   The  _-_n
       option  tells _r_a_n_i_m_a_t_e not to take any action (ie. not to actually exe-
       cute any commands).  The _-_e option  tells  _r_a_n_i_m_a_t_e  to  explicate  all
       variables  used  for the animation, including default values not speci-
       fied in the input file, and print them on the standard output.

       The _-_w option turns off warnings about multiply and  misassigned  vari-
       ables.

       Normally, _r_a_n_i_m_a_t_e will produce one animation frame for each view given
       in the specified view file.  If an animation has ended or  been  killed
       in an incomplete state, however, _r_a_n_i_m_a_t_e will attempt to pick up where
       the earlier process left off.  If the process is still running, or  was
       started  on  another machine, _r_a_n_i_m_a_t_e will report this information and
       exit.

       Animation variable assignments appear one per  line  in  _r_a_n_f_i_l_e_.   The
       name  of  the  variable  is  followed  by  an equals sign ('=') and its
       value(s).  The end of line may  be  escaped  with  a  backslash  ('\'),
       though it is not usually necessary since additional variable values may
       be given in multiple assignments.  Variables that should have only  one
       value are given in upper case.  Variables that may have multiple values
       are given in lower case.  Variables may be abbreviated by  their  first
       three  letters,  except for "host", which must have all four.  Comments
       in _r_a_n_f_i_l_e start with a pound sign ('#') and  proceed  to  the  end  of
       line.

       The  animation  variables, their interpretations and default values are
       given below.

       DDIIRREECCTTOORRYY The name of the animation  directory.   All  temporary  files
                 generated  during the animation will be placed in this direc-
                 tory, which will be created by _r_a_n_i_m_a_t_e if it does not exist.
                 A  file  named  "STATUS" will also be created there, and will
                 contain current  information  about  the  animation  process.
                 This  variable  has  no  default  value,  and  its setting is
                 required.

       OOCCTTRREEEE    The name of the octree file for a static  scene  walk-through
                 animation.   There is no default value for this variable, and
                 any setting will be ignored if the _A_N_I_M_A_T_E variable  is  also
                 set (see below).

       AANNIIMMAATTEE   The  scene  generation command for a dynamic animation.  This
                 command, if given, will be executed with the frame number  as
                 the  final  argument, and on its standard output it must pro-
                 duce the complete octree for that frame.  Care must be  taken
                 that  this  command  does not create any temporary files that
                 might collide with same-named files created by  other  anima-
                 tion  commands running in parallel.  Also, the command should
                 produce no output to the standard error, unless  there  is  a
                 fatal  condition.   (I.e.,  switch  all warnings off; see the
                 BUGS section, below.)  There is no default animation command,
                 and  either this variable or the _O_C_T_R_E_E variable must be set.

       VVIIEEWWFFIILLEE  This variable names a file from which  _r_a_n_i_m_a_t_e  may  extract
                 the  view  for each frame in the animation.  This file should
                 contain one valid view per frame, starting with  frame  1  on
                 line  1, regardless of the setting of the _S_T_A_R_T variable.  An
                 exception is made for a view file with only  a  single  view,
                 which  is  used for every frame of a dynamic scene animation.
                 This variable is required, and there is no default value.

       SSTTAARRTT     The initial frame number in  this  animation  sequence.   The
                 minimum  value  is 1, and if a later starting frame is given,
                 _r_a_n_i_m_a_t_e assumes that the earlier frames are included in some
                 other  _r_a_n_f_i_l_e_, which has been previously executed.  (See the
                 _N_E_X_T_A_N_I_M variable, below.)  The default value is 1.

       EENNDD       The final frame number in this sequence.  The  minimum  value
                 is  equal  to  the _S_T_A_R_T frame, and the default value is com-
                 puted from the number of views in the given _V_I_E_W_F_I_L_E_.

       EEXXPPOOSSUURREE  This variable tells _r_a_n_i_m_a_t_e how to adjust the  exposure  for
                 each  frame.   As in _p_f_i_l_t_, the exposure setting may be given
                 either as a multiplier or as a number of  f-stop  adjustments
                 (eg.  +2  or -1.5).  Alternatively, a file name may be given,
                 which _r_a_n_i_m_a_t_e will interpret as having  one  exposure  value
                 per  line  per frame, beginning with frame 1 at line 1.  (See
                 also the _V_I_E_W_F_I_L_E variable,  above.)   There  is  no  default
                 value  for  this  variable.   If  it is not given, an average
                 level will be computed by _p_f_i_l_t for each frame.

       BBAASSEENNAAMMEE  The base output file name for the final frames.  This  string
                 will  be passed to the _-_o and _-_z options of rpict, along with
                 appropriate suffixes, and thus  should  contain  a  _p_r_i_n_t_f_(_3_)
                 style  integer  field  to  distinguish  one frame number from
                 another.  The final frames will use this name with  a  ".hdr"
                 suffix.  The default value is the assigned _D_I_R_E_C_T_O_R_Y followed
                 by "/frame%03d".

       hhoosstt      A host to use for command execution.  This  variable  may  be
                 assigned  a host name, followed by an optional number of par-
                 allel processes, followed by an optional directory  (relative
                 to the user's home directory on that machine), followed by an
                 alternate user name.  Multiple _h_o_s_t assignments  may  appear.
                 It  is  not  advisable  to specify more than one process on a
                 single-CPU host, as this just tends to slow things down.  The
                 default  value  is "localhost", which starts a single process
                 in the current directory of the local machine.

       RRIIFF       This variable specifies a _r_a_d input file to use as  a  source
                 of  rendering options and other variable settings.  If given,
                 _r_a_n_i_m_a_t_e will execute _r_a_d and create an options file to later
                 pass to _r_p_i_c_t or _r_t_r_a_c_e_.  Besides prepending the _r_e_n_d_e_r vari-
                 able, _r_a_n_i_m_a_t_e will also extract  default  settings  for  the
                 common  variables:  _O_C_T_R_E_E_,  _R_E_S_O_L_U_T_I_O_N_,  _E_X_P_O_S_U_R_E and _p_f_i_l_t_.
                 Following the file name, overriding variable settings may  be
                 given, which will be passed to _r_a_d on the command line.  Set-
                 tings with spaces in them should be enclosed in quotes.   The
                 execution of _r_a_d will also update the contents of the octree,
                 if necessary.  There is no default value for this variable.

       DDIISSKKSSPPAACCEE Specify the amount of disk space (in megabytes) available  on
                 the destination file system for temporary file storage.  _R_a_n_-
                 _i_m_a_t_e will coordinate its  batch  operations  based  on  this
                 amount of storage, assuming that there is either enough addi-
                 tional space for all the final  frames,  or  that  the  given
                 _T_R_A_N_S_F_E_R  command will move the finished frames to some other
                 location (see below).  The default value is 100 megabytes.

       AARRCCHHIIVVEE   After each batch rendering is finished and checked  for  com-
                 pleteness,  _r_a_n_i_m_a_t_e  will execute the given command, passing
                 the names of all the original  pictures  and  z-buffer  files
                 generated by _r_p_i_c_t_.  (The command is executed in the destina-
                 tion directory, and file names will  be  simple.)   Normally,
                 the  archive  command  copies  the  original  files to a tape
                 device or somewhere that they can be retrieved in  the  event
                 of  failure in the frame interpolation stages.  After the ar-
                 chive command has successfully completed, the  original  ren-
                 derings  are  removed.   There  is  no default value for this
                 variable, meaning that the original  unfiltered  frames  will
                 simply  be  removed.   Note that the last one or two rendered
                 frames may not be copied, archived or removed in  case  there
                 is a another sequence picking up where this one left off.

       TTRRAANNSSFFEERR  The  command to transfer the completed animation frames.  The
                 shell changes to the destination directory  and  appends  the
                 names of all the finished frames to this command before it is
                 executed.  Normally, the transfer command does something such
                 as  convert  the frames to another format and/or copy them to
                 tape or some other destination device before  removing  them.
                 The  _f_i_e_l_d_c_o_m_b_(_1_)  script may be used to conveniently combine
                 fields into frames for field-based animations.  If this vari-
                 able  is not given, the final frames are left where they are.
                 (See _B_A_S_E_N_A_M_E_, above.)

       RRSSHH       The command to use instead  of  _s_s_h_(_1_)  to  execute  commands
                 remotely  on  another machine.  The arguments and behavior of
                 this program must be  identical  to  the  UNIX  _s_s_h  command,
                 except  that  the _-_l option will always be used to specify an
                 alternate user name rather  than  the  _u_s_e_r_@_h_o_s_t  convention.
                 The  _-_l  option may or may not appear, but the _-_n option will
                 always be used, and the expected starting directory  will  be
                 that of the remote user, just as with _s_s_h_.

       NNEEXXTTAANNIIMM  This  variable  specifies  the next _r_a_n_f_i_l_e to use after this
                 sequence is completed.  This offers  a  convenient  means  to
                 continue an animation that requires different control options
                 in different segments.  It is important in this case to  cor-
                 rectly  set  the  _S_T_A_R_T  and _E_N_D variables in each _r_a_n_f_i_l_e so
                 that the segments do not overlap frames.

       OOVVEERRSSAAMMPPLLEE
                 This variable sets the multiplier of the original image  size
                 relative  to the final size given by the _R_E_S_O_L_U_T_I_O_N variable.
                 This determines the quality of  anti-aliasing  in  the  final
                 frames.   A value of 1 means no anti-aliasing, and a value of
                 3 produces very good anti-aliasing.  The default value is  2.
                 (A  fractional  value  may  be used for previews, causing low
                 resolution frames with large, blocky pixels to be produced.)

       IINNTTEERRPPOOLLAATTEE
                 This  variable  sets  the  number  of  frames  to interpolate
                 between each rendered frame in a static  scene  walk-through.
                 Z-buffers for each rendered frame will be generated by _r_p_i_c_t_,
                 and _p_i_n_t_e_r_p will be called to perform the actual  "tweening."
                 This  results  in  a  potentially  large savings in rendering
                 time, but should be used with caution since certain  informa-
                 tion  may  be lost or inaccurate, such as specular highlights
                 and reflections, and objects may even break apart if too  few
                 renderings  are  used  to  interpolate  too much motion.  The
                 default value for this variable is 0, meaning  no  interpola-
                 tion.   Interpolation  is  also  switched  off if the _A_N_I_M_A_T_E
                 variable is specified.

       MMBBLLUURR     This variable specifies the fraction of a frame time that the
                 shutter is simulated as being open for motion blur.  A number
                 of samples may be given as a second argument, which  controls
                 the   number  of  additional  frames  computed  and  averaged
                 together by _p_i_n_t_e_r_p_.  If this number is  less  than  2,  then
                 bluring  is  performed  by  _r_p_i_c_t  only, resulting in greater
                 noise than the combination of _r_p_i_c_t and _p_i_n_t_e_r_p  used  other-
                 wise.   (The  default value for number of samples is 5.)  The
                 default fraction is 0,  meaning  no  motion  blurring.   This
                 option  does  not  currently  work with the _A_N_I_M_A_T_E variable,
                 since pinterp only works for static environments.

       DDBBLLUURR     This variable specifies the aperture diameter  for  depth-of-
                 field  blurring,  in world units.  A number of samples may be
                 given as a second argument,  which  controls  the  number  of
                 additional  frames computed and averaged together by _p_i_n_t_e_r_p_.
                 If this number is less than 2, then blurring is performed  by
                 _r_p_i_c_t  only,  resulting in greater noise than the combination
                 of _r_p_i_c_t and _p_i_n_t_e_r_p used otherwise.  (The default value  for
                 number  of  samples is 5.)  To simulate a particular camera's
                 aperture, divide the focal length of the lens by  the  f-num-
                 ber,  then  convert  to  the  corresponding  world coordinate
                 units.  For example, if you wish to simulate a 50mm  lens  at
                 f/2.0  in  a scene modeled in meters, then you divide 50mm by
                 2.0 to get 25mm, which corresponds to an  effective  aperture
                 of  0.025  meters.   The  default  aperture  is 0, meaning no
                 depth-of-field blurring.  This option does not currently work
                 with  the  _A_N_I_M_A_T_E  variable,  since  pinterp  only works for
                 static environments.

       RRTTRRAACCEE    This boolean variable tells _r_a_n_i_m_a_t_e whether or not to employ
                 _r_t_r_a_c_e  during  frame  interpolation  using the _-_f_r option to
                 _p_i_n_t_e_r_p_.  If set to True, then the same rendering options and
                 static  octree  are  passed to _r_t_r_a_c_e as are normally used by
                 _r_p_i_c_t_.  The default value is False.  Note that this  variable
                 only  applies  to  static environment walk-throughs (i.e., no
                 _A_N_I_M_A_T_E command).

       RREESSOOLLUUTTIIOONN
                 This variable specifies the desired final picture resolution.
                 If only a single number is given, this value will be used for
                 both the horizontal and vertical picture dimensions.  If  two
                 numbers are given, the first is the horizontal resolution and
                 the second is the vertical resolution.  If three numbers  are
                 given,  the  third is taken as the pixel aspect ratio for the
                 final picture (a real value).  If the pixel aspect  ratio  is
                 zero,  the  exact  dimensions  given  will be those produced.
                 Otherwise, they will be used as a frame in  which  the  final
                 image  must fit.  The default value for this variable is 640.

       rreennddeerr    This variable may be used to specify  additional  options  to
                 _r_p_i_c_t or _r_t_r_a_c_e_.  These options will appear after the options
                 set automatically by _r_a_d_, and thus will override the  default
                 values.

       ppiinntteerrpp   This  variable  may  be used to specify additional options to
                 _p_i_n_t_e_r_p_, which is used to interpolate  frames  for  a  static
                 scene  walk-through.   (See  the  _p_i_n_t_e_r_p  man  page, and the
                 _I_N_T_E_R_P_O_L_A_T_E variable.)  Do not use this variable to  set  the
                 _p_i_n_t_e_r_p _-_f_r option, but use the _R_T_R_A_C_E setting instead.

       ppffiilltt     This  variable  may  be used to specify additional options to
                 _p_f_i_l_t_.  If this variable is given in the _r_a_n_f_i_l_e_, then  _p_f_i_l_t
                 will always be used.  (Normally, _p_f_i_l_t is called only if _p_i_n_-
                 _t_e_r_p is not needed or automatic exposure is  required.)   See
                 the _p_f_i_l_t manual page for details.

EEXXAAMMPPLLEESS
       A minimal input file for _r_a_n_i_m_a_t_e might look like this:


          ::::::::::
          sample.ran
          ::::::::::
          # The rad input file for our static scene:
          RIF= tutor.rif
          # The spool directory:
          DIRECTORY= anim1
          # The view file containing one view per frame:
          VIEWFILE= anim1.vf
          # The amount of temporary disk space available:
          DISKSPACE= 50  # megabytes

       Note  that  most of the variables are not set in this file.  If we only
       want to see what default values _r_a_n_i_m_a_t_e  would  use  without  actually
       executing anything, we can invoke it thus:

         ranimate -n -e sample.ran

       This  will  print the variables we have given as well as default values
       _r_a_n_i_m_a_t_e has assigned for us.  Also, we will see the list  of  commands
       that _r_a_n_i_m_a_t_e would have executed had the _-_n option not been present.

       Usually,  we  execute _r_a_n_i_m_a_t_e in the background, redirecting the stan-
       dard output and standard error to a file:

         ranimate sample.ran >& sample.err &

       If we decide that the default values _r_a_n_i_m_a_t_e has chosen for our  vari-
       ables  are not all appropriate, we can add some more assignments to the
       file:


          host= rays 3 ~greg/obj/tutor ray   # execute as ray on multi-host "rays"
          host= thishost                # execute one copy on this host also
          INTERP= 3                # render every fourth frame
          RES= 1024                # shoot for 1024x resolution
          MBLUR= .25                    # apply camera motion blur
          EXP= anim1.exp                # adjust exposure according to file
          pfilt= -r .9                  # use Gaussian filtering
          ARCHIVE= tar cf /dev/nrtape        # save original renderings to tape

       Note the use of abbreviation for variable names.

FFIILLEESS
       $(DIRECTORY)/STATUS animation  status  file   $(DIRECTORY)/*      other
       temporary files $(BASENAME).hdr          final animation frames

AAUUTTHHOORR
       Greg Ward

BBUUGGSS
       Due  to  the  difficulty of controlling processes on multiple execution
       hosts, the _-_n option of _r_a_n_i_m_a_t_e is not useful in the same way  as  _r_a_d
       for  generating a script of executable commands to render the sequence.
       It may give an idea of the sequence of events,  but  certain  temporary
       files  and  so  forth  will  not  be  in  the correct state if the user
       attempts to create a separate batch script.

       If multiple processors are available on a given  host  and  the  _R_T_R_A_C_E
       variable  is  set  to  True,  then  the  _-_P_P option of _r_t_r_a_c_e should be
       employed, but it is not.  There is no easy way around this problem, but
       it  has only minor consequences in most cases.  (The _-_P_P option is used
       for _r_p_i_c_t_, however.)

       The current implementation of the remote shell does not return the exit
       status of the remote process, which makes it difficult to determine for
       sure if there has been a serious error or not.  Because of this,  _r_a_n_i_-
       _m_a_t_e  normally turns off warnings on all rendering processes, and takes
       any output to standard error from a remote command as  a  sign  that  a
       fatal  error  has  occurred.   (This  also  precludes the use of the _-_t
       option to report rendering progress.)  If the error  was  caused  by  a
       process  server  going down, the server is removed from the active list
       and frame recovery takes place.   Otherwise,  _r_a_n_i_m_a_t_e  quits  at  that
       point in the animation.

       The  current execution environment, in particular the RAYPATH variable,
       will not be passed during remote command execution, so it is  necessary
       to  set  whatever  variables are important in the remote startup script
       (e.g., ".cshrc" for the C-shell).  This requirement may be circumvented
       by  substituting  the  _o_n_(_1_)  command  for _s_s_h_(_1_) using the _R_S_H control
       variable, or by writing a custom remote execution script.

       If a different remote user name is used,  _r_a_n_i_m_a_t_e  first  attempts  to
       change  to  the original user's directory with a command of the form _c_d
       _u_n_a_m_e _.  This works under _c_s_h_(_1_)_, but may fail under other shells  such
       as _s_h_(_1_)_.

       If  multiple hosts with different floating point formats are used, _p_i_n_-
       _t_e_r_p will  fail  because  the  Z-buffer  files  will  be  inconsistent.
       (Recall  that  _p_i_n_t_e_r_p  is  called  if  INTERPOLATE > 0 and/or MBLUR is
       assigned.)  Since most modern machines use IEEE floating point, this is
       not usually a problem, but it is something to keep in mind.

SSEEEE AALLSSOO
       fieldcomb(1),  pfilt(1),  pinterp(1),  pmblur(1),  rad(1), ran2tiff(1),
       ranimove(1), rpict(1), ssh(1), rtrace(1)



RADIANCE                            6/24/98                        RANIMATE(1)
