1 |
.\" RCSid "$Id: ranimate.1,v 1.3 2005/01/18 03:59:40 greg Exp $" |
2 |
.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 |
number of f-stop adjustments (eg. +2 or -1.5). |
161 |
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 |
The final frames will use this name with a ".pic" suffix. |
184 |
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 |
If this variable is not given, the final frames are left where they |
275 |
are. |
276 |
(See |
277 |
.I BASENAME, |
278 |
above.)\0 |
279 |
.TP |
280 |
.BR RSH |
281 |
The command to use instead of |
282 |
.I rsh(1) |
283 |
to execute commands remotely on another machine. |
284 |
The arguments and behavior of this program must be identical to the UNIX |
285 |
.I rsh |
286 |
command, except that the |
287 |
.I -l |
288 |
option will always be used to specify an alternate user name rather than the |
289 |
.I "user@host" |
290 |
convention. |
291 |
Th |
292 |
.I -l |
293 |
option may or may not appear, but the |
294 |
.I -n |
295 |
option will always be used, and the expected starting directory will |
296 |
be that of the remote user, just as with |
297 |
.I rsh. |
298 |
.TP |
299 |
.BR NEXTANIM |
300 |
This variable specifies the next |
301 |
.I ranfile |
302 |
to use after this sequence is completed. |
303 |
This offers a convenient means to continue an animation that |
304 |
requires different control options in different segments. |
305 |
It is important in this case to correctly set the |
306 |
.I START |
307 |
and |
308 |
.I END |
309 |
variables in each |
310 |
.I ranfile |
311 |
so that the segments do not overlap frames. |
312 |
.TP |
313 |
.BR OVERSAMPLE |
314 |
This variable sets the multiplier of the original image size |
315 |
relative to the final size given by the |
316 |
.I RESOLUTION |
317 |
variable. |
318 |
This determines the quality of anti-aliasing in the final frames. |
319 |
A value of 1 means no anti-aliasing, and a value of 3 produces very |
320 |
good anti-aliasing. |
321 |
The default value is 2. |
322 |
(A fractional value may be used for previews, causing low |
323 |
resolution frames with large, blocky pixels to be produced.)\0 |
324 |
.TP |
325 |
.BR INTERPOLATE |
326 |
This variable sets the number of frames to interpolate between each |
327 |
rendered frame in a static scene walk-through. |
328 |
Z-buffers for each rendered frame will be generated by |
329 |
.I rpict, |
330 |
and |
331 |
.I pinterp |
332 |
will be called to perform the actual "tweening." |
333 |
This results in a potentially large savings in rendering time, but |
334 |
should be used with caution since certain information may be lost or |
335 |
inaccurate, such as specular highlights and reflections, and objects |
336 |
may even break apart if too few renderings are used to interpolate |
337 |
too much motion. |
338 |
The default value for this variable is 0, meaning no interpolation. |
339 |
Interpolation is also switched off if the |
340 |
.I ANIMATE |
341 |
variable is specified. |
342 |
.TP |
343 |
.BR MBLUR |
344 |
This variable specifies the fraction of a frame time that the shutter |
345 |
is simulated as being open for motion blur. |
346 |
A number of samples may be given as a second argument, which |
347 |
controls the number of additional frames computed and averaged |
348 |
together by |
349 |
.I pinterp. |
350 |
If this number is less than 2, then bluring is performed by |
351 |
.I rpict |
352 |
only, resulting in greater noise than the combination of |
353 |
.I rpict |
354 |
and |
355 |
.I pinterp |
356 |
used otherwise. |
357 |
(The default value for number of samples is 5.)\0 |
358 |
The default fraction is 0, meaning no motion blurring. |
359 |
This option does not currently work with the |
360 |
.I ANIMATE |
361 |
variable, since pinterp only works for static environments. |
362 |
.TP |
363 |
.BR DBLUR |
364 |
This variable specifies the aperture diameter for depth-of-field blurring, |
365 |
in world units. |
366 |
A number of samples may be given as a second argument, which controls the |
367 |
number of additional frames computed and averaged together by |
368 |
.I pinterp. |
369 |
If this number is less than 2, then blurring is performed by |
370 |
.I rpict |
371 |
only, resulting in greater noise than the combination of |
372 |
.I rpict |
373 |
and |
374 |
.I pinterp |
375 |
used otherwise. |
376 |
(The default value for number of samples is 5.)\0 |
377 |
To simulate a particular camera's aperture, divide the focal length of |
378 |
the lens by the f-number, then convert to the corresponding |
379 |
world coordinate units. |
380 |
For example, if you wish to simulate a 50mm lens at f/2.0 in |
381 |
a scene modeled in meters, then you divide 50mm by 2.0 to get 25mm, |
382 |
which corresponds to an effective aperture of 0.025 meters. |
383 |
The default aperture is 0, meaning no depth-of-field blurring. |
384 |
This option does not currently work with the |
385 |
.I ANIMATE |
386 |
variable, since pinterp only works for static environments. |
387 |
.TP |
388 |
.BR RTRACE |
389 |
This boolean variable tells |
390 |
.I ranimate |
391 |
whether or not to employ |
392 |
.I rtrace |
393 |
during frame interpolation using the |
394 |
.I \-fr |
395 |
option to |
396 |
.I pinterp. |
397 |
If set to True, then the same rendering options and static octree |
398 |
are passed to |
399 |
.I rtrace |
400 |
as are normally used by |
401 |
.I rpict. |
402 |
The default value is False. |
403 |
Note that this variable only applies to static environment |
404 |
walk-throughs (i.e., no |
405 |
.I ANIMATE |
406 |
command). |
407 |
.TP |
408 |
.BR RESOLUTION |
409 |
This variable specifies the desired final picture resolution. |
410 |
If only a single number is given, this value will be used for both |
411 |
the horizontal and vertical picture dimensions. |
412 |
If two numbers are given, the first is the horizontal resolution and |
413 |
the second is the vertical resolution. |
414 |
If three numbers are given, the third is taken as the pixel aspect |
415 |
ratio for the final picture (a real value). |
416 |
If the pixel aspect ratio is zero, the exact dimensions given will |
417 |
be those produced. |
418 |
Otherwise, they will be used as a frame in which the final image |
419 |
must fit. |
420 |
The default value for this variable is 640. |
421 |
.TP |
422 |
.BR render |
423 |
This variable may be used to specify additional options to |
424 |
.I rpict |
425 |
or |
426 |
.I rtrace. |
427 |
These options will appear after the options set automatically by |
428 |
.I rad, |
429 |
and thus will override the default values. |
430 |
.TP |
431 |
.BR pinterp |
432 |
This variable may be used to specify additional options to |
433 |
.I pinterp, |
434 |
which is used to interpolate frames for a static scene walk-through. |
435 |
(See the |
436 |
.I pinterp |
437 |
man page, and the |
438 |
.I INTERPOLATE |
439 |
variable.)\0 |
440 |
Do not use this variable to set the |
441 |
.I pinterp |
442 |
.I \-fr |
443 |
option, but use the |
444 |
.I RTRACE |
445 |
setting instead. |
446 |
.TP |
447 |
.BR pfilt |
448 |
This variable may be used to specify additional options to |
449 |
.I pfilt. |
450 |
If this variable is given in the |
451 |
.I ranfile, |
452 |
then |
453 |
.I pfilt |
454 |
will always be used. |
455 |
(Normally, |
456 |
.I pfilt |
457 |
is called only if |
458 |
.I pinterp |
459 |
is not needed or automatic exposure is required.)\0 |
460 |
See the |
461 |
.I pfilt |
462 |
manual page for details. |
463 |
.SH EXAMPLES |
464 |
A minimal input file for |
465 |
.I ranimate |
466 |
might look like this: |
467 |
.IP "" .3i |
468 |
.nf |
469 |
:::::::::: |
470 |
sample.ran |
471 |
:::::::::: |
472 |
# The rad input file for our static scene: |
473 |
RIF= tutor.rif |
474 |
# The spool directory: |
475 |
DIRECTORY= anim1 |
476 |
# The view file containing one view per frame: |
477 |
VIEWFILE= anim1.vf |
478 |
# The amount of temporary disk space available: |
479 |
DISKSPACE= 50 # megabytes |
480 |
.fi |
481 |
.PP |
482 |
Note that most of the variables are not set in this file. |
483 |
If we only want to see what default values |
484 |
.I ranimate |
485 |
would use without actually executing anything, we can invoke it |
486 |
thus: |
487 |
.IP "" .2i |
488 |
ranimate -n -e sample.ran |
489 |
.PP |
490 |
This will print the variables we have given as well as default |
491 |
values |
492 |
.I ranimate |
493 |
has assigned for us. |
494 |
Also, we will see the list of commands that |
495 |
.I ranimate |
496 |
would have executed had the |
497 |
.I \-n |
498 |
option not been present. |
499 |
.PP |
500 |
Usually, we execute |
501 |
.I ranimate |
502 |
in the background, redirecting the standard output and standard |
503 |
error to a file: |
504 |
.IP "" .2i |
505 |
ranimate sample.ran >& sample.err & |
506 |
.PP |
507 |
If we decide that the default values |
508 |
.I ranimate |
509 |
has chosen for our variables are not all appropriate, we can add |
510 |
some more assignments to the file: |
511 |
.IP "" .3i |
512 |
.nf |
513 |
host= rays 3 ~greg/obj/tutor ray # execute as ray on multi-host "rays" |
514 |
host= thishost # execute one copy on this host also |
515 |
INTERP= 3 # render every fourth frame |
516 |
RES= 1024 # shoot for 1024x resolution |
517 |
MBLUR= .25 # apply camera motion blur |
518 |
EXP= anim1.exp # adjust exposure according to file |
519 |
pfilt= -r .9 # use Gaussian filtering |
520 |
ARCHIVE= tar cf /dev/nrtape # save original renderings to tape |
521 |
.fi |
522 |
.PP |
523 |
Note the use of abbreviation for variable names. |
524 |
.SH FILES |
525 |
$(DIRECTORY)/STATUS animation status file |
526 |
$(DIRECTORY)/* other temporary files |
527 |
$(BASENAME).pic final animation frames |
528 |
.SH AUTHOR |
529 |
Greg Ward |
530 |
.SH BUGS |
531 |
Due to the difficulty of controlling processes on multiple execution |
532 |
hosts, the |
533 |
.I \-n |
534 |
option of |
535 |
.I ranimate |
536 |
is not useful in the same way as |
537 |
.I rad |
538 |
for generating a script of executable commands to render the |
539 |
sequence. |
540 |
It may give an idea of the sequence of events, but certain temporary |
541 |
files and so forth will not be in the correct state if the user |
542 |
attempts to create a separate batch script. |
543 |
.PP |
544 |
If multiple processors are available on a given host and the |
545 |
.I RTRACE |
546 |
variable is set to True, then the |
547 |
.I \-PP |
548 |
option of |
549 |
.I rtrace |
550 |
should be employed, but it is not. |
551 |
There is no easy way around this problem, but it has only minor |
552 |
consequences in most cases. |
553 |
(The |
554 |
.I \-PP |
555 |
option is used for |
556 |
.I rpict, |
557 |
however.)\0 |
558 |
.I |
559 |
.PP |
560 |
The current implementation of the remote shell does not return the |
561 |
exit status of the remote process, which makes it difficult to |
562 |
determine for sure if there has been a serious error or not. |
563 |
Because of this, |
564 |
.I ranimate |
565 |
normally turns off warnings on all rendering processes, and takes |
566 |
any output to standard error from a remote command as a sign that a |
567 |
fatal error has occurred. |
568 |
(This also precludes the use of the |
569 |
.I \-t |
570 |
option to report rendering progress.)\0 |
571 |
If the error was caused by a process server going down, the server |
572 |
is removed from the active list and frame recovery takes place. |
573 |
Otherwise, |
574 |
.I ranimate |
575 |
quits at that point in the animation. |
576 |
.PP |
577 |
The current execution environment, in particular the RAYPATH variable, |
578 |
will not be passed during remote command execution, so it is necessary |
579 |
to set whatever variables are important in the remote startup script |
580 |
(e.g., ".cshrc" for the C-shell). |
581 |
This requirement may be circumvented by substituting the |
582 |
.I on(1) |
583 |
command for |
584 |
.I rsh(1) |
585 |
using the |
586 |
.I RSH |
587 |
control variable, or by writing a custom remote execution script. |
588 |
.PP |
589 |
If a different remote user name is used, |
590 |
.I ranimate |
591 |
first attempts to change to the original user's directory with a |
592 |
command of the form |
593 |
.I "cd \~uname". |
594 |
This works under |
595 |
.I csh(1), |
596 |
but may fail under other shells such as |
597 |
.I sh(1). |
598 |
.PP |
599 |
If multiple hosts with different floating point formats are used, |
600 |
.I pinterp |
601 |
will fail because the Z-buffer files will be inconsistent. |
602 |
(Recall that |
603 |
.I pinterp |
604 |
is called if INTERPOLATE > 0 and/or MBLUR is assigned.)\0 |
605 |
Since most modern machines use IEEE floating point, this is not |
606 |
usually a problem, but it is something to keep in mind. |
607 |
.SH "SEE ALSO" |
608 |
pfilt(1), pinterp(1), pmblur(1), rad(1), |
609 |
ranimove(1), rpict(1), rsh(1), rtrace(1) |