RANIMOVE(1)                                                        RANIMOVE(1)



NNAAMMEE
       ranimove - render a RADIANCE animation with motion

SSYYNNOOPPSSIISS
       rraanniimmoovvee  [  --ss  ][ --ee ][ --ww ][ --ff bbeegg,,eenndd ][ --nn nnpprrooccss ][ --tt sseecc ][ --dd
       jjnndd ] rrnnmmffiillee

DDEESSCCRRIIPPTTIIOONN
       _R_a_n_i_m_o_v_e is a program for progressive animation  rendering.   Variables
       in the given _r_n_m_f_i_l_e indicate input files, output file names, and vari-
       ous other controls and options.

       Normally, progress reports are written to the standard output, but  the
       _-_s  option tells _r_a_n_i_m_o_v_e to do its work silently.  The _-_e option tells
       _r_a_n_i_m_o_v_e to explicate all variables used for the  animation,  including
       default  values  not specified in the input file, and print them on the
       standard output.  The _-_w option turns off warnings about  multiply  and
       misassigned variables and non-fatal rendering problems.

       Normally, _r_a_n_i_m_o_v_e will produce one animation frame for each view given
       in the specified view file.  If the _-_f option is specified, the  anima-
       tion  will  resume  at  the given frame, and continue to the end of the
       sequence, or to the second frame if one is given  (separated  from  the
       first by a comma but no space).

       The  _-_n  option specifies the number of processes to use for rendering.
       The default value is 1, which is appropriate  for  most  machines  that
       have  a  single central processing unit (CPU).  If you are running on a
       machine with multiple CPUs, a larger value up to the number of  proces-
       sors  may  be  used to improve rendering speed, depending on the system
       load.

       Because _r_a_n_i_m_o_v_e renders each frame progressively, it needs some crite-
       ria  for  when  to  proceed to the next frame in the animation.  The _-_t
       option is used to specify the maximum number of seconds to spend on any
       one frame.  The default value for this option is 60 seconds.  Addition-
       ally, the _-_d option may be used to specify a termination  threshold  in
       just-noticeable-differences.   If  the  error can be reduced below this
       number of JNDs over the whole  frame  before  the  time  allocation  is
       spent,  _r_a_n_i_m_o_v_e  will  then proceed to the next frame.  A value of 2.0
       JNDs is the point at which 75% of the people will notice a  difference,
       and  this  is  the  level usually selected for such a termination test.
       There is no default value for this option, which means  that  rendering
       will proceed until the time allocation is spent for each frame, regard-
       less.  If _-_t is set to 0, _r_a_n_i_m_o_v_e will spend as much time as it  takes
       to reduce the visible error below the value set by the _-_d option.

       _R_a_n_i_m_o_v_e  renders  each  frame  in three stages.  In the first stage, a
       low-quality image is rendered using one ray sample per 16  pixels.   In
       the  second  stage,  pixels from the previous frame are extrapolated to
       their corresponding positions in this one, based on  the  given  camera
       and object movements.  A set of heuristics is applied to prevent errors
       in specular highlights and shadows, avoiding some of the errors typical
       with the _p_i_n_t_e_r_p_(_1_) program.  In the third stage, additional high-qual-
       ity samples are used to refine important regions of the image that  are
       judged to have visible errors.  This proceeds until the stopping crite-
       ria specified by the _-_t and _-_d options are met, when the frame is  fil-
       tered and written to the designated picture file.

       The  chief  differences  between  this program and _r_a_n_i_m_a_t_e_(_1_) are that
       motion blur is computed for objects as well as camera movement, and its
       progressive  rendering  allows better control over the tradeoff between
       frame accuracy and rendering time.  Fewer  controls  are  provided  for
       managing  the picture files produced by _r_a_n_i_m_o_v_e_, and no facilities for
       distributed rendering are available other than  executing  _r_a_n_i_m_o_v_e  on
       different  machines using the _-_f option to manually partition the work.

       Animation variable assignments appear one per  line  in  _r_n_m_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.   Comments in _r_n_m_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.

       OOCCTTRREEEE    The  name  of the base octree file, which should be generated
                 by the _o_c_o_n_v_(_1_) command using the _-_f  option.   There  is  no
                 default  value  for  this  variable.   If  no _R_I_F variable is
                 given, the octree must be specified.

       RRIIFF       This variable specifies a _r_a_d_(_1_)  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  control rendering parameters.  _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_,  and  _E_X_P_O_S_U_R_E_.   Following  the  file name, overriding
                 variable settings may be given, which will be passed  to  _r_a_d
                 on  the command line.  Settings 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.

       mmoovvee      This variable specifies an object (or objects)  with  a  spe-
                 cific motion and/or rendering priority.  Four value arguments
                 are expected for each appearance of this variable.  The first
                 is  the  name of a parent move object, or "void" if none.  If
                 given, the object's transformation will be prepended to  that
                 of  its  parent.   The  second  argument  is the name of this
                 object, which will be used to name surfaces it contains,  and
                 as  a  modifier for any child objects that reference it.  The
                 third argument is the transformation string or file for  this
                 object.   If  this  argument is enclosed in quotes and begins
                 with a hyphen ('-'), then it will be interpreted as a  static
                 transform  specification a la _x_f_o_r_m_(_1_)_.  Otherwise, the argu-
                 ment will be taken as the name of a file  that  contains  one
                 such  transform  specification  per  line,  corresponding  to
                 frames in the animation.  A period ('.') may be given  if  no
                 object transformation is desired.  The fourth argument is the
                 name of a _R_A_D_I_A_N_C_E scene file (or files) to be given to _x_f_o_r_m
                 for transformation.  If this argument begins with an exclama-
                 tion point ('!'), then it will be interpreted  as  a  command
                 rather  than a file.  A final word corresponding to the frame
                 number will be appended to the command, and its  output  will
                 be  passed  to the input of _x_f_o_r_m for each frame.  An optinal
                 fifth argument specifies  the  rendering  priority  for  this
                 object.   Values  greater  than 1 will result in preferential
                 rendering of this object over other  portions  of  the  image
                 when  it  appears  in a frame.  Values less than 1 will cause
                 the rendering to neglect this object in favor of other  parts
                 of  the  image.   A value of 3.0 can be interpreted as saying
                 the viewer is three times more likely to look at this  object
                 than  the  background.   A  file  may  be given rather than a
                 floating point value, and this file must contain one floating
                 point  number per line, corresponding to frames in the anima-
                 tion.

       VVIIEEWWFFIILLEE  This variable names a file from which  _r_a_n_i_m_o_v_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.   An  exception  is made for a view file with only a
                 single view, which is used for every frame of the  animation.
                 In  this case, the _E_N_D variable must also be specified.  This
                 variable is required, and there is no default value.

       EENNDD       The final frame number in the animation.  The  default  value
                 is  computed  from the number of views in the given _V_I_E_W_F_I_L_E_.
                 Normally, this variable will only be given  if  the  view  is
                 static.

       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,  no  exposure
                 adjustments will be made.

       BBAASSEENNAAMMEE  The  base output file name for the final frames.  This string
                 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
                 "frame%03d".

       MMBBLLUURR     This variable specifies the fraction of a frame time that the
                 shutter is simulated as being open for motion  blur.   Motion
                 blur  is  computed  by  _r_a_n_i_m_o_v_e  using image-based rendering
                 methods, and will not be exact.   The  default  value  is  0,
                 meaning no motion blurring.

       RRAATTEE      This  variable  specifies the animation frame rate, in frames
                 per second.  This is needed to compute  the  animation  error
                 visibility.  The default value is 8.

       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.

       lloowwqq      This  variable  may  be used to specify rendering options for
                 the initial, low-quality ray samples.  It may be given either
                 as  a  list  of  rendering parameter settings, or as variable
                 settings for the _r_a_d command, in which case the _R_I_F  variable
                 must also be specified.

       hhiigghhqq     This  variable  may  be used to specify rendering options for
                 the final, high-quality ray samples.  It may be given  either
                 as  a  list  of  rendering parameter settings, or as variable
                 settings for the _r_a_d command, in which case the _R_I_F  variable
                 must also be specified.

       ooccoonnvv     This  variable  may  be  used  to specify special options for
                 _o_c_o_n_v_.  See the _o_c_o_n_v_(_1_) manual page  for  a  list  of  valid
                 options.  (The _-_f option is specified by default.)

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


          ::::::::::
          sample.rnm
          ::::::::::
          # The rad input file for our static scene:
          RIF= tutor.rif
          # The view file containing one view per frame:
          VIEWFILE= anim1.vf
          # Our central character and its motion:
          move= void myguy myguy.xf myguy.rad 2.0

       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_o_v_e  would  use  without  actually
       executing anything, we can invoke it thus:

         ranimove -n 0 -e sample.rnm

       This  will  print the variables we have given as well as default values
       _r_a_n_i_m_o_v_e has assigned for us.

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

         ranimove sample.rnm >& sample.err &

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


          RES= 1024                # shoot for 1024x resolution
          MBLUR= .25                    # apply camera motion blur
          RATE= 15                 # 15 frames/second
          EXP= anim1.exp                # adjust exposure according to file
          lowq= QUAL=Low                # low quality ray sampling
          highq= QUAL=Med                    # high quality ray sampling

       Note the use of abbreviation for variable names.

AAUUTTHHOORR
       Greg Ward

SSEEEE AALLSSOO
       fieldcomb(1), oconv(1), pfilt(1), pinterp(1), rad(1), ran2tiff(1), ran-
       imate(1), rpict(1), xform(1)



RADIANCE                            1/30/03                        RANIMOVE(1)
