xenial (1) ranimate.1.gz

Provided by: radiance_4R1+20120125-1.1_amd64 bug

NAME

       ranimate - compute a RADIANCE animation

SYNOPSIS

       ranimate [ -s ][ -n ][ -e ][ -w ] ranfile

DESCRIPTION

       Ranimate  is  an  executive  program  that reads the given ranfile and makes appropriate calls to rad(1),
       rpict(1), pinterp(1), and/or pfilt(1) to render an animation.  Variables in ranfile 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 executed.  The -s option tells  ranimate
       to  do  its  work  silently.   The  -n  option tells ranimate not to take any action (ie. not to actually
       execute any commands).  The -e option tells ranimate 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.

       Normally,  ranimate  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, ranimate will attempt to  pick  up
       where  the earlier process left off.  If the process is still running, or was started on another machine,
       ranimate will report this information and exit.

       Animation variable assignments appear one per line in ranfile.  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 ranfile start with a pound sign ('#') and proceed to the
       end of line.

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

       DIRECTORY The name of the animation directory.  All temporary files generated during the  animation  will
                 be  placed  in  this directory, which will be created by ranimate 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.

       OCTREE    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 ANIMATE variable  is  also  set
                 (see below).

       ANIMATE   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  produce  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  animation  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 OCTREE variable must be
                 set.

       VIEWFILE  This variable names a file from which ranimate 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 START 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.

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

       END       The  final  frame  number in this sequence.  The minimum value is equal to the START frame, and
                 the default value is computed from the number of views in the given VIEWFILE.

       EXPOSURE  This variable tells ranimate how to adjust the exposure for  each  frame.   As  in  pfilt,  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 ranimate will interpret as  having
                 one  exposure  value  per  line  per  frame,  beginning  with frame 1 at line 1.  (See also the
                 VIEWFILE variable, above.)  There is no default value for this variable.  If it is  not  given,
                 an average level will be computed by pfilt for each frame.

       BASENAME  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  printf(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  DIRECTORY  followed  by
                 "/frame%03d".

       host      A host to use for command execution.  This variable may be assigned a host name, followed by an
                 optional number of parallel processes, followed by  an  optional  directory  (relative  to  the
                 user's  home  directory  on  that  machine), followed by an alternate user name.  Multiple host
                 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.

       RIF       This variable specifies a rad input file to use as a source  of  rendering  options  and  other
                 variable  settings.   If  given,  ranimate will execute rad and create an options file to later
                 pass to rpict or rtrace.  Besides prepending the render variable, ranimate  will  also  extract
                 default  settings  for the common variables: OCTREE, RESOLUTION, EXPOSURE and pfilt.  Following
                 the file name, overriding variable settings may be given, which will be passed to  rad  on  the
                 command line.  Settings with spaces in them should be enclosed in quotes.  The execution of rad
                 will also update the contents of the octree, if necessary.  There is no default value for  this
                 variable.

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

       ARCHIVE   After  each batch rendering is finished and checked for completeness, ranimate will execute the
                 given command, passing the names of all the original pictures and z-buffer files  generated  by
                 rpict.  (The command is executed in the destination 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 archive
                 command has successfully completed, the original renderings 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.

       TRANSFER  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
                 fieldcomb(1)  script  may  be  used  to conveniently combine fields into frames for field-based
                 animations.  If this variable is not given, the final frames are left  where  they  are.   (See
                 BASENAME, above.)

       RSH       The  command  to  use  instead  of ssh(1) to execute commands remotely on another machine.  The
                 arguments and behavior of this program must be identical to the UNIX ssh command,  except  that
                 the  -l  option will always be used to specify an alternate user name rather than the user@host
                 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 ssh.

       NEXTANIM  This  variable specifies the next ranfile 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 correctly set the START and END variables
                 in each ranfile so that the segments do not overlap frames.

       OVERSAMPLE
                 This variable sets the multiplier of the original image size relative to the final  size  given
                 by  the RESOLUTION 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.)

       INTERPOLATE
                 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 rpict, and pinterp
                 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 information 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 interpolation.  Interpolation is also switched  off  if  the  ANIMATE
                 variable is specified.

       MBLUR     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 pinterp.  If this number is
                 less than 2, then bluring is performed by rpict only,  resulting  in  greater  noise  than  the
                 combination  of  rpict and pinterp used otherwise.  (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 ANIMATE variable, since pinterp only works for static environments.

       DBLUR     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 pinterp.  If this number is less than 2, then blurring
                 is performed by rpict only, resulting in greater  noise  than  the  combination  of  rpict  and
                 pinterp  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-number, 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 ANIMATE variable,  since
                 pinterp only works for static environments.

       RTRACE    This boolean variable tells ranimate whether or not to employ rtrace during frame interpolation
                 using the -fr option to pinterp.  If set to True, then the same rendering  options  and  static
                 octree  are  passed to rtrace as are normally used by rpict.  The default value is False.  Note
                 that this variable only applies to static environment walk-throughs (i.e., no ANIMATE command).

       RESOLUTION
                 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.

       render    This variable may be used to specify additional options to rpict or rtrace.  These options will
                 appear after the options set automatically by rad, and thus will override the default values.

       pinterp   This  variable  may  be  used  to  specify  additional  options  to  pinterp,  which is used to
                 interpolate frames for a static scene  walk-through.   (See  the  pinterp  man  page,  and  the
                 INTERPOLATE  variable.)   Do  not  use this variable to set the pinterp -fr option, but use the
                 RTRACE setting instead.

       pfilt     This variable may be used to specify additional options to pfilt.  If this variable is given in
                 the ranfile, then pfilt will always be used.  (Normally, pfilt is called only if pinterp is not
                 needed or automatic exposure is required.)  See the pfilt manual page for details.

EXAMPLES

       A minimal input file for ranimate 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
       ranimate 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 ranimate has assigned for us.
       Also, we will see the list of commands that ranimate would have executed  had  the  -n  option  not  been
       present.

       Usually,  we  execute ranimate in the background, redirecting the standard output and standard error to a
       file:

         ranimate sample.ran >& sample.err &

       If we decide that the default values ranimate has chosen for our variables 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.

FILES

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

AUTHOR

       Greg Ward

BUGS

       Due to the difficulty of controlling processes on multiple execution hosts, the -n option of ranimate  is
       not  useful in the same way as rad 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 RTRACE variable is set to True, then the -PP
       option of rtrace 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 -PP option is used for rpict, 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,  ranimate  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, ranimate 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 on(1)
       command for ssh(1) using the RSH control variable, or by writing a custom remote execution script.

       If a different remote user name is used, ranimate  first  attempts  to  change  to  the  original  user's
       directory  with  a  command  of  the  form cd  uname .  This works under csh(1), but may fail under other
       shells such as sh(1).

       If multiple hosts with different floating point formats are used, pinterp will fail because the  Z-buffer
       files  will  be  inconsistent.   (Recall  that  pinterp  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.

SEE ALSO

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