Ubuntu Manpage: ranimate - compute a RADIANCE animation

Provided by: radiance_4R1+20120125-1.1_amd64

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.