Ubuntu Manpage: ranimove - render a RADIANCE animation with motion

Provided by: radiance_4R1+20120125-1.1_amd64

NAME

       ranimove - render a RADIANCE animation with motion

SYNOPSIS

       ranimove [ -s ][ -e ][ -w ][ -f beg,end ][ -n nprocs ][ -t sec ][ -d jnd ] rnmfile

DESCRIPTION

Ranimove is a program for progressive animation rendering. Variables in the given rnmfile
indicate input files, output file names, and various other controls and options.

Normally, progress reports are written to the standard output, but the -s option tells
ranimove to do its work silently. The -e option tells ranimove 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, ranimove will produce one animation frame for each view given in the specified
view file. If the -f option is specified, the animation 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 processors may be used to improve rendering speed, depending on the system load.

Because ranimove renders each frame progressively, it needs some criteria 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. Additionally, 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, ranimove 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, regardless. If -t is set to 0, ranimove will spend as
much time as it takes to reduce the visible error below the value set by the -d option.

Ranimove 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 pinterp(1)
program. In the third stage, additional high-quality samples are used to refine important
regions of the image that are judged to have visible errors. This proceeds until the
stopping criteria specified by the -t and -d options are met, when the frame is filtered
and written to the designated picture file.

The chief differences between this program and ranimate(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 ranimove, and no
facilities for distributed rendering are available other than executing ranimove on
different machines using the -f option to manually partition the work.

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

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

OCTREE The name of the base octree file, which should be generated by the oconv(1)
command using the -f option. There is no default value for this variable. If
no RIF variable is given, the octree must be specified.

RIF This variable specifies a rad(1) 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 control rendering parameters. Ranimate will also
extract default settings for the common variables: OCTREE, RESOLUTION, and
EXPOSURE. 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.

move This variable specifies an object (or objects) with a specific 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 xform(1).
Otherwise, the argument 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 RADIANCE scene file (or files) to be given to xform
for transformation. If this argument begins with an exclamation 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 xform 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 animation.

VIEWFILE This variable names a file from which ranimove 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 END variable must also be specified. This variable is required, and there
is no default value.

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

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

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

MBLUR 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 ranimove
using image-based rendering methods, and will not be exact. The default value
is 0, meaning no motion blurring.

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

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.

lowq 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 rad command, in which case the RIF
variable must also be specified.

highq 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 rad command, in which case the RIF
variable must also be specified.

oconv This variable may be used to specify special options for oconv. See the
oconv(1) manual page for a list of valid options. (The -f option is specified
by default.)

EXAMPLES

       A minimal input file for ranimove 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  ranimove  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  ranimove  has
       assigned for us.

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

         ranimove sample.rnm >& sample.err &

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

AUTHOR

       Greg Ward

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

AUTHOR

SEE ALSO