1 |
.\" RCSid "$Id: ranimate.1,v 1.6 2005/09/06 17:59:42 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 |
The |
275 |
.I fieldcomb(1) |
276 |
script may be used to conveniently combine fields into frames for |
277 |
field-based animations. |
278 |
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 |
.I ssh(1) |
287 |
to execute commands remotely on another machine. |
288 |
The arguments and behavior of this program must be identical to the UNIX |
289 |
.I ssh |
290 |
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 |
Th |
296 |
.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 |
.I ssh. |
302 |
.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 |
.I pinterp |
360 |
used otherwise. |
361 |
(The default value for number of samples is 5.)\0 |
362 |
The default fraction is 0, meaning no motion blurring. |
363 |
This option does not currently work with the |
364 |
.I ANIMATE |
365 |
variable, since pinterp only works for static environments. |
366 |
.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 |
.I pinterp |
379 |
used otherwise. |
380 |
(The default value for number of samples is 5.)\0 |
381 |
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 |
The default aperture is 0, meaning no depth-of-field blurring. |
388 |
This option does not currently work with the |
389 |
.I ANIMATE |
390 |
variable, since pinterp only works for static environments. |
391 |
.TP |
392 |
.BR RTRACE |
393 |
This boolean variable tells |
394 |
.I ranimate |
395 |
whether or not to employ |
396 |
.I rtrace |
397 |
during frame interpolation using the |
398 |
.I \-fr |
399 |
option to |
400 |
.I pinterp. |
401 |
If set to True, then the same rendering options and static octree |
402 |
are passed to |
403 |
.I rtrace |
404 |
as are normally used by |
405 |
.I rpict. |
406 |
The default value is False. |
407 |
Note that this variable only applies to static environment |
408 |
walk-throughs (i.e., no |
409 |
.I ANIMATE |
410 |
command). |
411 |
.TP |
412 |
.BR RESOLUTION |
413 |
This variable specifies the desired final picture resolution. |
414 |
If only a single number is given, this value will be used for both |
415 |
the horizontal and vertical picture dimensions. |
416 |
If two numbers are given, the first is the horizontal resolution and |
417 |
the second is the vertical resolution. |
418 |
If three numbers are given, the third is taken as the pixel aspect |
419 |
ratio for the final picture (a real value). |
420 |
If the pixel aspect ratio is zero, the exact dimensions given will |
421 |
be those produced. |
422 |
Otherwise, they will be used as a frame in which the final image |
423 |
must fit. |
424 |
The default value for this variable is 640. |
425 |
.TP |
426 |
.BR render |
427 |
This variable may be used to specify additional options to |
428 |
.I rpict |
429 |
or |
430 |
.I rtrace. |
431 |
These options will appear after the options set automatically by |
432 |
.I rad, |
433 |
and thus will override the default values. |
434 |
.TP |
435 |
.BR pinterp |
436 |
This variable may be used to specify additional options to |
437 |
.I pinterp, |
438 |
which is used to interpolate frames for a static scene walk-through. |
439 |
(See the |
440 |
.I pinterp |
441 |
man page, and the |
442 |
.I INTERPOLATE |
443 |
variable.)\0 |
444 |
Do not use this variable to set the |
445 |
.I pinterp |
446 |
.I \-fr |
447 |
option, but use the |
448 |
.I RTRACE |
449 |
setting instead. |
450 |
.TP |
451 |
.BR pfilt |
452 |
This variable may be used to specify additional options to |
453 |
.I pfilt. |
454 |
If this variable is given in the |
455 |
.I ranfile, |
456 |
then |
457 |
.I pfilt |
458 |
will always be used. |
459 |
(Normally, |
460 |
.I pfilt |
461 |
is called only if |
462 |
.I pinterp |
463 |
is not needed or automatic exposure is required.)\0 |
464 |
See the |
465 |
.I pfilt |
466 |
manual page for details. |
467 |
.SH EXAMPLES |
468 |
A minimal input file for |
469 |
.I ranimate |
470 |
might look like this: |
471 |
.IP "" .3i |
472 |
.nf |
473 |
:::::::::: |
474 |
sample.ran |
475 |
:::::::::: |
476 |
# The rad input file for our static scene: |
477 |
RIF= tutor.rif |
478 |
# The spool directory: |
479 |
DIRECTORY= anim1 |
480 |
# The view file containing one view per frame: |
481 |
VIEWFILE= anim1.vf |
482 |
# The amount of temporary disk space available: |
483 |
DISKSPACE= 50 # megabytes |
484 |
.fi |
485 |
.PP |
486 |
Note that most of the variables are not set in this file. |
487 |
If we only want to see what default values |
488 |
.I ranimate |
489 |
would use without actually executing anything, we can invoke it |
490 |
thus: |
491 |
.IP "" .2i |
492 |
ranimate -n -e sample.ran |
493 |
.PP |
494 |
This will print the variables we have given as well as default |
495 |
values |
496 |
.I ranimate |
497 |
has assigned for us. |
498 |
Also, we will see the list of commands that |
499 |
.I ranimate |
500 |
would have executed had the |
501 |
.I \-n |
502 |
option not been present. |
503 |
.PP |
504 |
Usually, we execute |
505 |
.I ranimate |
506 |
in the background, redirecting the standard output and standard |
507 |
error to a file: |
508 |
.IP "" .2i |
509 |
ranimate sample.ran >& sample.err & |
510 |
.PP |
511 |
If we decide that the default values |
512 |
.I ranimate |
513 |
has chosen for our variables are not all appropriate, we can add |
514 |
some more assignments to the file: |
515 |
.IP "" .3i |
516 |
.nf |
517 |
host= rays 3 ~greg/obj/tutor ray # execute as ray on multi-host "rays" |
518 |
host= thishost # execute one copy on this host also |
519 |
INTERP= 3 # render every fourth frame |
520 |
RES= 1024 # shoot for 1024x resolution |
521 |
MBLUR= .25 # apply camera motion blur |
522 |
EXP= anim1.exp # adjust exposure according to file |
523 |
pfilt= -r .9 # use Gaussian filtering |
524 |
ARCHIVE= tar cf /dev/nrtape # save original renderings to tape |
525 |
.fi |
526 |
.PP |
527 |
Note the use of abbreviation for variable names. |
528 |
.SH FILES |
529 |
$(DIRECTORY)/STATUS animation status file |
530 |
$(DIRECTORY)/* other temporary files |
531 |
$(BASENAME).pic final animation frames |
532 |
.SH AUTHOR |
533 |
Greg Ward |
534 |
.SH BUGS |
535 |
Due to the difficulty of controlling processes on multiple execution |
536 |
hosts, the |
537 |
.I \-n |
538 |
option of |
539 |
.I ranimate |
540 |
is not useful in the same way as |
541 |
.I rad |
542 |
for generating a script of executable commands to render the |
543 |
sequence. |
544 |
It may give an idea of the sequence of events, but certain temporary |
545 |
files and so forth will not be in the correct state if the user |
546 |
attempts to create a separate batch script. |
547 |
.PP |
548 |
If multiple processors are available on a given host and the |
549 |
.I RTRACE |
550 |
variable is set to True, then the |
551 |
.I \-PP |
552 |
option of |
553 |
.I rtrace |
554 |
should be employed, but it is not. |
555 |
There is no easy way around this problem, but it has only minor |
556 |
consequences in most cases. |
557 |
(The |
558 |
.I \-PP |
559 |
option is used for |
560 |
.I rpict, |
561 |
however.)\0 |
562 |
.I |
563 |
.PP |
564 |
The current implementation of the remote shell does not return the |
565 |
exit status of the remote process, which makes it difficult to |
566 |
determine for sure if there has been a serious error or not. |
567 |
Because of this, |
568 |
.I ranimate |
569 |
normally turns off warnings on all rendering processes, and takes |
570 |
any output to standard error from a remote command as a sign that a |
571 |
fatal error has occurred. |
572 |
(This also precludes the use of the |
573 |
.I \-t |
574 |
option to report rendering progress.)\0 |
575 |
If the error was caused by a process server going down, the server |
576 |
is removed from the active list and frame recovery takes place. |
577 |
Otherwise, |
578 |
.I ranimate |
579 |
quits at that point in the animation. |
580 |
.PP |
581 |
The current execution environment, in particular the RAYPATH variable, |
582 |
will not be passed during remote command execution, so it is necessary |
583 |
to set whatever variables are important in the remote startup script |
584 |
(e.g., ".cshrc" for the C-shell). |
585 |
This requirement may be circumvented by substituting the |
586 |
.I on(1) |
587 |
command for |
588 |
.I ssh(1) |
589 |
using the |
590 |
.I RSH |
591 |
control variable, or by writing a custom remote execution script. |
592 |
.PP |
593 |
If a different remote user name is used, |
594 |
.I ranimate |
595 |
first attempts to change to the original user's directory with a |
596 |
command of the form |
597 |
.I "cd \~uname". |
598 |
This works under |
599 |
.I csh(1), |
600 |
but may fail under other shells such as |
601 |
.I sh(1). |
602 |
.PP |
603 |
If multiple hosts with different floating point formats are used, |
604 |
.I pinterp |
605 |
will fail because the Z-buffer files will be inconsistent. |
606 |
(Recall that |
607 |
.I pinterp |
608 |
is called if INTERPOLATE > 0 and/or MBLUR is assigned.)\0 |
609 |
Since most modern machines use IEEE floating point, this is not |
610 |
usually a problem, but it is something to keep in mind. |
611 |
.SH "SEE ALSO" |
612 |
fieldcomb(1), pfilt(1), pinterp(1), pmblur(1), rad(1), |
613 |
ran2tiff(1), ranimove(1), rpict(1), ssh(1), rtrace(1) |