xenial (1) ranimove.1.gz

Provided by: radiance_4R1+20120125-1.1_amd64 bug

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

SEE ALSO

       fieldcomb(1), oconv(1), pfilt(1), pinterp(1), rad(1), ran2tiff(1), ranimate(1), rpict(1), xform(1)