man/man1/ranimate.1

.\" RCSid "$Id: ranimate.1,v 1.10 2008/11/10 19:08:17 greg Exp $"
.TH RANIMATE 1 6/24/98 RADIANCE
.SH NAME
ranimate - compute a RADIANCE animation
.SH SYNOPSIS
.B ranimate
[
.B \-s
][
.B \-n
][
.B \-e
][
.B \-w
]
.B ranfile
.SH DESCRIPTION
.I Ranimate
is an executive program that reads the given
.I ranfile
and makes appropriate calls to
.I rad(1),
.I rpict(1),
.I pinterp(1),
and/or
.I pfilt(1)
to render an animation.
Variables in
.I ranfile
indicate input files, process servers (execution hosts), output
directories and file names, and various other controls and options.
.PP
Normally, commands are echoed to the standard output as they are
executed.
The
.I \-s
option tells
.I ranimate
to do its work silently.
The
.I \-n
option tells
.I ranimate
not to take any action (ie. not to actually execute any commands).
The
.I \-e
option tells
.I 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.
.PP
The
.I \-w
option turns off warnings about multiply and misassigned variables.
.PP
Normally,
.I 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,
.I ranimate
will attempt to pick up where the earlier process left off.
If the process is still running, or was started on another machine,
.I ranimate
will report this information and exit.
.PP
Animation variable assignments appear one per line in
.I 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
.I ranfile
start with a pound sign ('#') and proceed to the end of line.
.PP
The animation variables, their interpretations and default values
are given below.
.TP 10n
.BR 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
.I 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.
.TP
.BR 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
.I ANIMATE
variable is also set (see below).
.TP
.BR 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.)\0
There is no default animation command, and either this variable or the
.I OCTREE
variable must be set.
.TP
.BR VIEWFILE
This variable names a file from which
.I 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
.I 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.
.TP
.BR START
The initial frame number in this animation sequence.
The minimum value is 1, and if a later starting frame is given,
.I ranimate
assumes that the earlier frames are included in some other
.I ranfile,
which has been previously executed.
(See the
.I NEXTANIM
variable, below.)\0
The default value is 1.
.TP
.BR END
The final frame number in this sequence.
The minimum value is equal to the
.I START
frame,
and the default value is computed from the number of views in the
given
.I VIEWFILE.
.TP
.BR EXPOSURE
This variable tells
.I ranimate
how to adjust the exposure for each frame.
As in
.I 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
.I ranimate
will interpret as having one exposure value per line per frame,
beginning with frame 1 at line 1.
(See also the
.I VIEWFILE
variable, above.)\0
There is no default value for this variable.
If it is not given, an average level will be computed by
.I pfilt
for each frame.
.TP
.BR BASENAME
The base output file name for the final frames.
This string will be passed to the
.I \-o
and
.I \-z
options of rpict, along with appropriate suffixes,
and thus should contain a
.I 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
.I DIRECTORY
followed by "/frame%03d".
.TP
.BR 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
.I 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.
.TP
.BR RIF
This variable specifies a
.I rad
input file to use as a source of rendering options and other
variable settings.
If given,
.I ranimate
will execute
.I rad
and create an options file to later pass to
.I rpict
or
.I rtrace.
Besides prepending the
.I render
variable,
.I ranimate
will also extract default settings for the common variables:
.I OCTREE,
.I RESOLUTION,
.I EXPOSURE
and
.I pfilt.
Following the file name, overriding variable settings may be given,
which will be passed to
.I rad
on the command line.
Settings with spaces in them should be enclosed in quotes.
The execution of
.I rad
will also update the contents of the octree, if necessary.
There is no default value for this variable.
.TP
.BR DISKSPACE
Specify the amount of disk space (in megabytes) available on the
destination file system for temporary file storage.
.I 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
.I TRANSFER
command will move the finished frames to some other location (see
below).
The default value is 100 megabytes.
.TP
.BR ARCHIVE
After each batch rendering is finished and checked for completeness,
.I ranimate
will execute the given command, passing the names of all the
original pictures and z-buffer files generated by
.I rpict.
(The command is executed in the destination directory, and file names
will be simple.)\0
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.
.TP
.BR 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
.I 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
.I BASENAME,
above.)\0
.TP
.BR RSH
The command to use instead of
.I ssh(1)
to execute commands remotely on another machine.
The arguments and behavior of this program must be identical to the UNIX
.I ssh
command, except that the
.I -l
option will always be used to specify an alternate user name rather than the
.I "user@host"
convention.
The
.I -l
option may or may not appear, but the
.I -n
option will always be used, and the expected starting directory will
be that of the remote user, just as with
.I ssh.
.TP
.BR NEXTANIM
This variable specifies the next
.I 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
.I START
and
.I END
variables in each
.I ranfile
so that the segments do not overlap frames.
.TP
.BR OVERSAMPLE
This variable sets the multiplier of the original image size
relative to the final size given by the
.I 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.)\0
.TP
.BR 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
.I rpict,
and
.I 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
.I ANIMATE
variable is specified.
.TP
.BR 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
.I pinterp.
If this number is less than 2, then bluring is performed by
.I rpict
only, resulting in greater noise than the combination of
.I rpict
and
.I pinterp
used otherwise.
(The default value for number of samples is 5.)\0
The default fraction is 0, meaning no motion blurring.
This option does not currently work with the
.I ANIMATE
variable.
.TP
.BR 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
.I pinterp.
If this number is less than 2, then blurring is performed by
.I rpict
only, resulting in greater noise than the combination of
.I rpict
and
.I pinterp
used otherwise.
(The default value for number of samples is 5.)\0
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 focus distance is determined by the length of the view directon vector.
The default aperture is 0, meaning no depth-of-field blurring.
.TP
.BR RTRACE
This boolean variable tells
.I ranimate
whether or not to employ
.I rtrace
during frame interpolation using the
.I \-fr
option to
.I pinterp.
If set to True, then the same rendering options and static octree
are passed to
.I rtrace
as are normally used by
.I rpict.
The default value is False.
Note that this variable only applies to static environment
walk-throughs (i.e., no
.I ANIMATE
command).
.TP
.BR 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.
.TP
.BR render
This variable may be used to specify additional options to
.I rpict
or
.I rtrace.
These options will appear after the options set automatically by
.I rad,
and thus will override the default values.
.TP
.BR pinterp
This variable may be used to specify additional options to
.I pinterp,
which is used to interpolate frames for a static scene walk-through.
(See the
.I pinterp
man page, and the
.I INTERPOLATE
variable.)\0
Do not use this variable to set the
.I pinterp
.I \-fr
option, but use the
.I RTRACE
setting instead.
.TP
.BR pfilt
This variable may be used to specify additional options to
.I pfilt.
If this variable is given in the
.I ranfile,
then
.I pfilt
will always be used.
(Normally,
.I pfilt
is called only if
.I pinterp
is not needed or automatic exposure is required.)\0
See the
.I pfilt
manual page for details.
.SH EXAMPLES
A minimal input file for
.I ranimate
might look like this:
.IP "" .3i
.nf
::::::::::
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
.fi
.PP
Note that most of the variables are not set in this file.
If we only want to see what default values
.I ranimate
would use without actually executing anything, we can invoke it
thus:
.IP "" .2i
ranimate \-n \-e sample.ran
.PP
This will print the variables we have given as well as default
values
.I ranimate
has assigned for us.
Also, we will see the list of commands that
.I ranimate
would have executed had the
.I \-n
option not been present.
.PP
Usually, we execute
.I ranimate
in the background, redirecting the standard output and standard
error to a file:
.IP "" .2i
ranimate sample.ran >& sample.err &
.PP
If we decide that the default values
.I ranimate
has chosen for our variables are not all appropriate, we can add
some more assignments to the file:
.IP "" .3i
.nf
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
.fi
.PP
Note the use of abbreviation for variable names.
.SH FILES
$(DIRECTORY)/STATUS     animation status file
$(DIRECTORY)/*          other temporary files
$(BASENAME).hdr         final animation frames
.SH AUTHOR
Greg Ward
.SH BUGS
Due to the difficulty of controlling processes on multiple execution
hosts, the
.I \-n
option of
.I ranimate
is not useful in the same way as
.I 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.
.PP
If multiple processors are available on a given host and the
.I RTRACE
variable is set to True, then the
.I \-PP
option of
.I 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
.I \-PP
option is used for
.I rpict,
however.)\0
.I
.PP
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,
.I 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
.I \-t
option to report rendering progress.)\0
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,
.I ranimate
quits at that point in the animation.
.PP
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
.I on(1)
command for
.I ssh(1)
using the
.I RSH
control variable, or by writing a custom remote execution script.
.PP
If a different remote user name is used,
.I ranimate
first attempts to change to the original user's directory with a
command of the form
.I "cd \~uname".
This works under
.I csh(1),
but may fail under other shells such as
.I sh(1).
.PP
If multiple hosts with different floating point formats are used,
.I pinterp
will fail because the Z-buffer files will be inconsistent.
(Recall that
.I pinterp
is called if INTERPOLATE > 0 and/or MBLUR is assigned.)\0
Since most modern machines use IEEE floating point, this is not
usually a problem, but it is something to keep in mind.
.SH "SEE ALSO"
fieldcomb(1), pfilt(1), pinterp(1), pmblur(1), rad(1),
ran2tiff(1), ranimove(1), rpict(1), ssh(1), rtrace(1)
Revision:	1.11
Committed:	Wed Jun 1 16:59:34 2022 UTC (2 years, 3 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, HEAD
Changes since 1.10:	+3 -5 lines
Log Message:	docs(ranimate): Clarified exceptions for MBLUR and DBLUR settings
#	User	Rev	Content
1	greg	1.11	.\" RCSid "$Id: ranimate.1,v 1.10 2008/11/10 19:08:17 greg Exp $"
2	greg	1.1	.TH RANIMATE 1 6/24/98 RADIANCE
3			.SH NAME
4			ranimate - compute a RADIANCE animation
5			.SH SYNOPSIS
6			.B ranimate
7			[
8			.B \-s
9			][
10			.B \-n
11			][
12			.B \-e
13			][
14			.B \-w
15			]
16			.B ranfile
17			.SH DESCRIPTION
18			.I Ranimate
19			is an executive program that reads the given
20			.I ranfile
21			and makes appropriate calls to
22			.I rad(1),
23			.I rpict(1),
24			.I pinterp(1),
25			and/or
26			.I pfilt(1)
27			to render an animation.
28			Variables in
29			.I ranfile
30			indicate input files, process servers (execution hosts), output
31			directories and file names, and various other controls and options.
32			.PP
33			Normally, commands are echoed to the standard output as they are
34			executed.
35			The
36			.I \-s
37			option tells
38			.I ranimate
39			to do its work silently.
40			The
41			.I \-n
42			option tells
43			.I ranimate
44			not to take any action (ie. not to actually execute any commands).
45			The
46			.I \-e
47			option tells
48			.I ranimate
49			to explicate all variables used for the animation, including
50			default values not specified in the input file, and print them on
51			the standard output.
52			.PP
53			The
54			.I \-w
55			option turns off warnings about multiply and misassigned variables.
56			.PP
57			Normally,
58			.I ranimate
59			will produce one animation frame for each view given in the specified
60			view file.
61			If an animation has ended or been killed in an incomplete state, however,
62			.I ranimate
63			will attempt to pick up where the earlier process left off.
64			If the process is still running, or was started on another machine,
65			.I ranimate
66			will report this information and exit.
67			.PP
68			Animation variable assignments appear one per line in
69			.I ranfile.
70			The name of the variable is followed by an equals sign
71			('=') and its value(s).
72			The end of line may be escaped with a backslash ('\\'), though it is
73			not usually necessary since additional variable values may be given
74			in multiple assignments.
75			Variables that should have only one value are given in upper case.
76			Variables that may have multiple values are given in lower case.
77			Variables may be abbreviated by their first three letters, except
78			for "host", which must have all four.
79			Comments in
80			.I ranfile
81			start with a pound sign ('#') and proceed to the end of line.
82			.PP
83			The animation variables, their interpretations and default values
84			are given below.
85			.TP 10n
86			.BR DIRECTORY
87			The name of the animation directory.
88			All temporary files generated during the animation will be placed in
89			this directory, which will be created by
90			.I ranimate
91			if it does not exist.
92			A file named "STATUS" will also be created there, and will contain current
93			information about the animation process.
94			This variable has no default value, and its setting is required.
95			.TP
96			.BR OCTREE
97			The name of the octree file for a static scene walk-through
98			animation.
99			There is no default value for this variable, and any
100			setting will be ignored if the
101			.I ANIMATE
102			variable is also set (see below).
103			.TP
104			.BR ANIMATE
105			The scene generation command for a dynamic animation.
106			This command, if given, will be executed with the frame number as the
107			final argument, and on its standard output it must produce
108			the complete octree for that frame.
109			Care must be taken that this command does not create any temporary files
110			that might collide with same-named files created by other
111			animation commands running in parallel.
112			Also, the command should produce no output to the standard error, unless
113			there is a fatal condition.
114			(I.e., switch all warnings off;
115			see the BUGS section, below.)\0
116			There is no default animation command, and either this variable or the
117			.I OCTREE
118			variable must be set.
119			.TP
120			.BR VIEWFILE
121			This variable names a file from which
122			.I ranimate
123			may extract the view for each frame in the animation.
124			This file should contain one valid view per frame, starting with
125			frame 1 on line 1, regardless of the setting of the
126			.I START
127			variable.
128			An exception is made for a view file with only a single view, which
129			is used for every frame of a dynamic scene animation.
130			This variable is required, and there is no default value.
131			.TP
132			.BR START
133			The initial frame number in this animation sequence.
134			The minimum value is 1, and if a later starting frame is given,
135			.I ranimate
136			assumes that the earlier frames are included in some other
137			.I ranfile,
138			which has been previously executed.
139			(See the
140			.I NEXTANIM
141			variable, below.)\0
142			The default value is 1.
143			.TP
144			.BR END
145			The final frame number in this sequence.
146			The minimum value is equal to the
147			.I START
148			frame,
149			and the default value is computed from the number of views in the
150			given
151			.I VIEWFILE.
152			.TP
153			.BR EXPOSURE
154			This variable tells
155			.I ranimate
156			how to adjust the exposure for each frame.
157			As in
158			.I pfilt,
159			the exposure setting may be given either as a multiplier or as a
160	greg	1.9	number of f\-stop adjustments (eg. +2 or \-1.5).
161	greg	1.1	Alternatively, a file name may be given, which
162			.I ranimate
163			will interpret as having one exposure value per line per frame,
164			beginning with frame 1 at line 1.
165			(See also the
166			.I VIEWFILE
167			variable, above.)\0
168			There is no default value for this variable.
169			If it is not given, an average level will be computed by
170			.I pfilt
171			for each frame.
172			.TP
173			.BR BASENAME
174			The base output file name for the final frames.
175			This string will be passed to the
176			.I \-o
177			and
178			.I \-z
179			options of rpict, along with appropriate suffixes,
180			and thus should contain a
181			.I printf(3)
182			style integer field to distinguish one frame number from another.
183	greg	1.10	The final frames will use this name with a ".hdr" suffix.
184	greg	1.1	The default value is the assigned
185			.I DIRECTORY
186			followed by "/frame%03d".
187			.TP
188			.BR host
189			A host to use for command execution.
190			This variable may be assigned a host name, followed by an optional
191			number of parallel processes, followed by an optional
192			directory (relative to the user's home directory on that machine),
193			followed by an alternate user name.
194			Multiple
195			.I host
196			assignments may appear.
197			It is not advisable to specify more than one process on a single-CPU
198			host, as this just tends to slow things down.
199			The default value is "localhost", which starts a single process in
200			the current directory of the local machine.
201			.TP
202			.BR RIF
203			This variable specifies a
204			.I rad
205			input file to use as a source of rendering options and other
206			variable settings.
207			If given,
208			.I ranimate
209			will execute
210			.I rad
211			and create an options file to later pass to
212			.I rpict
213			or
214			.I rtrace.
215			Besides prepending the
216			.I render
217			variable,
218			.I ranimate
219			will also extract default settings for the common variables:
220			.I OCTREE,
221			.I RESOLUTION,
222			.I EXPOSURE
223			and
224			.I pfilt.
225			Following the file name, overriding variable settings may be given,
226			which will be passed to
227			.I rad
228			on the command line.
229			Settings with spaces in them should be enclosed in quotes.
230			The execution of
231			.I rad
232			will also update the contents of the octree, if necessary.
233			There is no default value for this variable.
234			.TP
235			.BR DISKSPACE
236			Specify the amount of disk space (in megabytes) available on the
237			destination file system for temporary file storage.
238			.I Ranimate
239			will coordinate its batch operations based on this amount of storage,
240			assuming that there is either enough additional space for all the
241			final frames, or that the given
242			.I TRANSFER
243			command will move the finished frames to some other location (see
244			below).
245			The default value is 100 megabytes.
246			.TP
247			.BR ARCHIVE
248			After each batch rendering is finished and checked for completeness,
249			.I ranimate
250			will execute the given command, passing the names of all the
251			original pictures and z-buffer files generated by
252			.I rpict.
253			(The command is executed in the destination directory, and file names
254			will be simple.)\0
255			Normally, the archive command copies the original files to a tape device
256			or somewhere that they can be retrieved in the event of failure in
257			the frame interpolation stages.
258			After the archive command has successfully completed, the original
259			renderings are removed.
260			There is no default value for this variable, meaning that the
261			original unfiltered frames will simply be removed.
262			Note that the last one or two rendered frames may not be copied, archived
263			or removed in case there is a another sequence picking up where this
264			one left off.
265			.TP
266			.BR TRANSFER
267			The command to transfer the completed animation frames.
268			The shell changes to the destination directory and appends
269			the names of all the finished frames to this command
270			before it is executed.
271			Normally, the transfer command does something such as convert the
272			frames to another format and/or copy them to tape or some other
273			destination device before removing them.
274	greg	1.6	The
275			.I fieldcomb(1)
276			script may be used to conveniently combine fields into frames for
277			field-based animations.
278	greg	1.1	If this variable is not given, the final frames are left where they
279			are.
280			(See
281			.I BASENAME,
282			above.)\0
283			.TP
284			.BR RSH
285			The command to use instead of
286	greg	1.5	.I ssh(1)
287	greg	1.1	to execute commands remotely on another machine.
288			The arguments and behavior of this program must be identical to the UNIX
289	greg	1.5	.I ssh
290	greg	1.1	command, except that the
291			.I -l
292			option will always be used to specify an alternate user name rather than the
293			.I "user@host"
294			convention.
295	greg	1.8	The
296	greg	1.1	.I -l
297			option may or may not appear, but the
298			.I -n
299			option will always be used, and the expected starting directory will
300			be that of the remote user, just as with
301	greg	1.5	.I ssh.
302	greg	1.1	.TP
303			.BR NEXTANIM
304			This variable specifies the next
305			.I ranfile
306			to use after this sequence is completed.
307			This offers a convenient means to continue an animation that
308			requires different control options in different segments.
309			It is important in this case to correctly set the
310			.I START
311			and
312			.I END
313			variables in each
314			.I ranfile
315			so that the segments do not overlap frames.
316			.TP
317			.BR OVERSAMPLE
318			This variable sets the multiplier of the original image size
319			relative to the final size given by the
320			.I RESOLUTION
321			variable.
322			This determines the quality of anti-aliasing in the final frames.
323			A value of 1 means no anti-aliasing, and a value of 3 produces very
324			good anti-aliasing.
325			The default value is 2.
326			(A fractional value may be used for previews, causing low
327			resolution frames with large, blocky pixels to be produced.)\0
328			.TP
329			.BR INTERPOLATE
330			This variable sets the number of frames to interpolate between each
331			rendered frame in a static scene walk-through.
332			Z-buffers for each rendered frame will be generated by
333			.I rpict,
334			and
335			.I pinterp
336			will be called to perform the actual "tweening."
337			This results in a potentially large savings in rendering time, but
338			should be used with caution since certain information may be lost or
339			inaccurate, such as specular highlights and reflections, and objects
340			may even break apart if too few renderings are used to interpolate
341			too much motion.
342			The default value for this variable is 0, meaning no interpolation.
343			Interpolation is also switched off if the
344			.I ANIMATE
345			variable is specified.
346			.TP
347			.BR MBLUR
348			This variable specifies the fraction of a frame time that the shutter
349			is simulated as being open for motion blur.
350			A number of samples may be given as a second argument, which
351			controls the number of additional frames computed and averaged
352			together by
353			.I pinterp.
354			If this number is less than 2, then bluring is performed by
355			.I rpict
356			only, resulting in greater noise than the combination of
357			.I rpict
358			and
359	greg	1.3	.I pinterp
360			used otherwise.
361	greg	1.1	(The default value for number of samples is 5.)\0
362	greg	1.3	The default fraction is 0, meaning no motion blurring.
363			This option does not currently work with the
364			.I ANIMATE
365	greg	1.11	variable.
366	greg	1.3	.TP
367			.BR DBLUR
368			This variable specifies the aperture diameter for depth-of-field blurring,
369			in world units.
370			A number of samples may be given as a second argument, which controls the
371			number of additional frames computed and averaged together by
372			.I pinterp.
373			If this number is less than 2, then blurring is performed by
374			.I rpict
375			only, resulting in greater noise than the combination of
376			.I rpict
377			and
378	greg	1.1	.I pinterp
379	greg	1.3	used otherwise.
380			(The default value for number of samples is 5.)\0
381	greg	1.4	To simulate a particular camera's aperture, divide the focal length of
382			the lens by the f-number, then convert to the corresponding
383			world coordinate units.
384			For example, if you wish to simulate a 50mm lens at f/2.0 in
385			a scene modeled in meters, then you divide 50mm by 2.0 to get 25mm,
386			which corresponds to an effective aperture of 0.025 meters.
387	greg	1.11	The focus distance is determined by the length of the view directon vector.
388	greg	1.3	The default aperture is 0, meaning no depth-of-field blurring.
389	greg	1.1	.TP
390			.BR RTRACE
391			This boolean variable tells
392			.I ranimate
393			whether or not to employ
394			.I rtrace
395			during frame interpolation using the
396			.I \-fr
397			option to
398			.I pinterp.
399			If set to True, then the same rendering options and static octree
400			are passed to
401			.I rtrace
402			as are normally used by
403			.I rpict.
404			The default value is False.
405			Note that this variable only applies to static environment
406			walk-throughs (i.e., no
407			.I ANIMATE
408			command).
409			.TP
410			.BR RESOLUTION
411			This variable specifies the desired final picture resolution.
412			If only a single number is given, this value will be used for both
413			the horizontal and vertical picture dimensions.
414			If two numbers are given, the first is the horizontal resolution and
415			the second is the vertical resolution.
416			If three numbers are given, the third is taken as the pixel aspect
417			ratio for the final picture (a real value).
418			If the pixel aspect ratio is zero, the exact dimensions given will
419			be those produced.
420			Otherwise, they will be used as a frame in which the final image
421			must fit.
422			The default value for this variable is 640.
423			.TP
424			.BR render
425			This variable may be used to specify additional options to
426			.I rpict
427			or
428			.I rtrace.
429			These options will appear after the options set automatically by
430			.I rad,
431			and thus will override the default values.
432			.TP
433			.BR pinterp
434			This variable may be used to specify additional options to
435			.I pinterp,
436			which is used to interpolate frames for a static scene walk-through.
437			(See the
438			.I pinterp
439			man page, and the
440			.I INTERPOLATE
441			variable.)\0
442			Do not use this variable to set the
443			.I pinterp
444			.I \-fr
445			option, but use the
446			.I RTRACE
447			setting instead.
448			.TP
449			.BR pfilt
450			This variable may be used to specify additional options to
451			.I pfilt.
452			If this variable is given in the
453			.I ranfile,
454			then
455			.I pfilt
456			will always be used.
457			(Normally,
458			.I pfilt
459			is called only if
460			.I pinterp
461			is not needed or automatic exposure is required.)\0
462			See the
463			.I pfilt
464			manual page for details.
465			.SH EXAMPLES
466			A minimal input file for
467			.I ranimate
468			might look like this:
469			.IP "" .3i
470			.nf
471			::::::::::
472			sample.ran
473			::::::::::
474			# The rad input file for our static scene:
475			RIF= tutor.rif
476			# The spool directory:
477			DIRECTORY= anim1
478			# The view file containing one view per frame:
479			VIEWFILE= anim1.vf
480			# The amount of temporary disk space available:
481			DISKSPACE= 50 # megabytes
482			.fi
483			.PP
484			Note that most of the variables are not set in this file.
485			If we only want to see what default values
486			.I ranimate
487			would use without actually executing anything, we can invoke it
488			thus:
489			.IP "" .2i
490	greg	1.9	ranimate \-n \-e sample.ran
491	greg	1.1	.PP
492			This will print the variables we have given as well as default
493			values
494			.I ranimate
495			has assigned for us.
496			Also, we will see the list of commands that
497			.I ranimate
498			would have executed had the
499			.I \-n
500			option not been present.
501			.PP
502			Usually, we execute
503			.I ranimate
504			in the background, redirecting the standard output and standard
505			error to a file:
506			.IP "" .2i
507			ranimate sample.ran >& sample.err &
508			.PP
509			If we decide that the default values
510			.I ranimate
511			has chosen for our variables are not all appropriate, we can add
512			some more assignments to the file:
513			.IP "" .3i
514			.nf
515			host= rays 3 ~greg/obj/tutor ray # execute as ray on multi-host "rays"
516			host= thishost # execute one copy on this host also
517			INTERP= 3 # render every fourth frame
518			RES= 1024 # shoot for 1024x resolution
519			MBLUR= .25 # apply camera motion blur
520			EXP= anim1.exp # adjust exposure according to file
521	greg	1.9	pfilt= \-r .9 # use Gaussian filtering
522	greg	1.1	ARCHIVE= tar cf /dev/nrtape # save original renderings to tape
523			.fi
524			.PP
525			Note the use of abbreviation for variable names.
526			.SH FILES
527			$(DIRECTORY)/STATUS animation status file
528			$(DIRECTORY)/* other temporary files
529	greg	1.10	$(BASENAME).hdr final animation frames
530	greg	1.1	.SH AUTHOR
531			Greg Ward
532			.SH BUGS
533			Due to the difficulty of controlling processes on multiple execution
534			hosts, the
535			.I \-n
536			option of
537			.I ranimate
538			is not useful in the same way as
539			.I rad
540			for generating a script of executable commands to render the
541			sequence.
542			It may give an idea of the sequence of events, but certain temporary
543			files and so forth will not be in the correct state if the user
544			attempts to create a separate batch script.
545			.PP
546			If multiple processors are available on a given host and the
547			.I RTRACE
548			variable is set to True, then the
549			.I \-PP
550			option of
551			.I rtrace
552			should be employed, but it is not.
553			There is no easy way around this problem, but it has only minor
554			consequences in most cases.
555			(The
556			.I \-PP
557			option is used for
558			.I rpict,
559			however.)\0
560			.I
561			.PP
562			The current implementation of the remote shell does not return the
563			exit status of the remote process, which makes it difficult to
564			determine for sure if there has been a serious error or not.
565			Because of this,
566			.I ranimate
567			normally turns off warnings on all rendering processes, and takes
568			any output to standard error from a remote command as a sign that a
569			fatal error has occurred.
570			(This also precludes the use of the
571			.I \-t
572			option to report rendering progress.)\0
573			If the error was caused by a process server going down, the server
574			is removed from the active list and frame recovery takes place.
575			Otherwise,
576			.I ranimate
577			quits at that point in the animation.
578			.PP
579			The current execution environment, in particular the RAYPATH variable,
580			will not be passed during remote command execution, so it is necessary
581			to set whatever variables are important in the remote startup script
582			(e.g., ".cshrc" for the C-shell).
583			This requirement may be circumvented by substituting the
584			.I on(1)
585			command for
586	greg	1.5	.I ssh(1)
587	greg	1.1	using the
588			.I RSH
589			control variable, or by writing a custom remote execution script.
590			.PP
591			If a different remote user name is used,
592			.I ranimate
593			first attempts to change to the original user's directory with a
594			command of the form
595			.I "cd \~uname".
596			This works under
597			.I csh(1),
598			but may fail under other shells such as
599			.I sh(1).
600			.PP
601			If multiple hosts with different floating point formats are used,
602			.I pinterp
603			will fail because the Z-buffer files will be inconsistent.
604			(Recall that
605			.I pinterp
606			is called if INTERPOLATE > 0 and/or MBLUR is assigned.)\0
607			Since most modern machines use IEEE floating point, this is not
608			usually a problem, but it is something to keep in mind.
609			.SH "SEE ALSO"
610	greg	1.6	fieldcomb(1), pfilt(1), pinterp(1), pmblur(1), rad(1),
611	greg	1.7	ran2tiff(1), ranimove(1), rpict(1), ssh(1), rtrace(1)