1 |
.\" RCSid "$Id" |
2 |
.SH NAME |
3 |
ranimove - render a RADIANCE animation with motion |
4 |
.SH SYNOPSIS |
5 |
.B ranimove |
6 |
[ |
7 |
.B \-s |
8 |
][ |
9 |
.B \-e |
10 |
][ |
11 |
.B \-w |
12 |
][ |
13 |
.B "\-f beg,end" |
14 |
][ |
15 |
.B "\-n nprocs" |
16 |
][ |
17 |
.B "\-t sec" |
18 |
][ |
19 |
.B "\-d jnd" |
20 |
] |
21 |
.B rnmfile |
22 |
.SH DESCRIPTION |
23 |
.I Ranimove |
24 |
is a program for progressive animation rendering. |
25 |
Variables in the given |
26 |
.I rnmfile |
27 |
indicate input files, output file names, |
28 |
and various other controls and options. |
29 |
.PP |
30 |
Normally, progress reports are written to the standard output, but the |
31 |
.I \-s |
32 |
option tells |
33 |
.I ranimove |
34 |
to do its work silently. |
35 |
The |
36 |
.I \-e |
37 |
option tells |
38 |
.I ranimove |
39 |
to explicate all variables used for the animation, including |
40 |
default values not specified in the input file, and print them on |
41 |
the standard output. |
42 |
The |
43 |
.I \-w |
44 |
option turns off warnings about multiply and misassigned variables and |
45 |
non-fatal rendering problems. |
46 |
.PP |
47 |
Normally, |
48 |
.I ranimove |
49 |
will produce one animation frame for each view given in the specified |
50 |
view file. |
51 |
If the |
52 |
.I \-f |
53 |
option is specified, the animation will resume at the given frame, and |
54 |
continue to the end of the sequence, or to the second frame if one is given |
55 |
(separated from the first by a comma but no space). |
56 |
.PP |
57 |
The |
58 |
.I \-n |
59 |
option specifies the number of processes to use for rendering. |
60 |
The default value is 1, which is appropriate for most machines |
61 |
that have a single central processing unit (CPU). |
62 |
If you are running on a machine with multiple CPUs, a larger |
63 |
value up to the number of processors may be used |
64 |
to improve rendering speed, depending on the system load. |
65 |
.PP |
66 |
Because |
67 |
.I ranimove |
68 |
renders each frame progressively, it needs some criteria for when |
69 |
to proceed to the next frame in the animation. |
70 |
The |
71 |
.I \-t |
72 |
option is used to specify the maximum number of seconds to spend |
73 |
on any one frame. |
74 |
The default value for this option is 60 seconds. |
75 |
Additionally, the |
76 |
.I \-d |
77 |
option may be used to specify a termination |
78 |
threshold in just-noticeable-differences. |
79 |
If the error can be reduced below this number of JNDs |
80 |
over the whole frame before the time allocation is spent, |
81 |
.I ranimove |
82 |
will then proceed to the next frame. |
83 |
A value of 2.0 JNDs is the point at which 75% of the people will notice |
84 |
a difference, and this is the level usually selected for such a |
85 |
termination test. |
86 |
There is no default value for this option, which means that rendering |
87 |
will proceed until the time allocation is spent for each frame, regardless. |
88 |
If |
89 |
.I \-t |
90 |
is set to 0, |
91 |
.I ranimove |
92 |
will spend as much time as it takes to reduce the |
93 |
visible error below the value set by the |
94 |
.I \-d |
95 |
option. |
96 |
.PP |
97 |
.I Ranimove |
98 |
renders each frame in three stages. |
99 |
In the first stage, a low-quality image |
100 |
is rendered using one ray sample per 16 pixels. |
101 |
In the second stage, pixels from the previous frame are extrapolated to |
102 |
their corresponding positions in |
103 |
this one, based on the given camera and object movements. |
104 |
A set of heuristics is applied |
105 |
to prevent errors in specular highlights and shadows, avoiding |
106 |
some of the errors typical with the |
107 |
.I pinterp(1) |
108 |
program. |
109 |
In the third stage, additional high-quality samples are used to refine |
110 |
important regions of the image that are judged to have visible errors. |
111 |
This proceeds until the stopping criteria specified by the |
112 |
.I \-t |
113 |
and |
114 |
.I -d |
115 |
options are met, |
116 |
when the frame is filtered and written to the designated picture file. |
117 |
.PP |
118 |
The chief differences between this program and |
119 |
.I ranimate(1) |
120 |
are that motion blur is computed for objects as well as camera movement, |
121 |
and its progressive rendering allows better control over the tradeoff |
122 |
between frame accuracy and rendering time. |
123 |
Fewer controls are provided for managing the picture files produced by |
124 |
.I ranimove, |
125 |
and no facilities for distributed rendering are available other |
126 |
than executing |
127 |
.I ranimove |
128 |
on different machines using the |
129 |
.I \-f |
130 |
option to manually partition the work. |
131 |
.PP |
132 |
Animation variable assignments appear one per line in |
133 |
.I rnmfile. |
134 |
The name of the variable is followed by an equals sign |
135 |
('=') and its value(s). |
136 |
The end of line may be escaped with a backslash ('\\'), though it is |
137 |
not usually necessary since additional variable values may be given |
138 |
in multiple assignments. |
139 |
Variables that should have only one value are given in upper case. |
140 |
Variables that may have multiple values are given in lower case. |
141 |
Variables may be abbreviated by their first three letters. |
142 |
Comments in |
143 |
.I rnmfile |
144 |
start with a pound sign ('#') and proceed to the end of line. |
145 |
.PP |
146 |
The animation variables, their interpretations and default values |
147 |
are given below. |
148 |
.TP 10n |
149 |
.BR OCTREE |
150 |
The name of the base octree file, which should be generated by the |
151 |
.I oconv(1) |
152 |
command using the |
153 |
.I \-f |
154 |
option. |
155 |
There is no default value for this variable. |
156 |
If no |
157 |
.I RIF |
158 |
variable is given, the octree must be specified. |
159 |
.TP |
160 |
.BR RIF |
161 |
This variable specifies a |
162 |
.I rad(1) |
163 |
input file to use as a source of rendering options and other |
164 |
variable settings. |
165 |
If given, |
166 |
.I ranimate |
167 |
will execute |
168 |
.I rad |
169 |
and create an options file to control rendering parameters. |
170 |
.I Ranimate |
171 |
will also extract default settings for the common variables: |
172 |
.I OCTREE, |
173 |
.I RESOLUTION, |
174 |
and |
175 |
.I EXPOSURE. |
176 |
Following the file name, overriding variable settings may be given, |
177 |
which will be passed to |
178 |
.I rad |
179 |
on the command line. |
180 |
Settings with spaces in them should be enclosed in quotes. |
181 |
The execution of |
182 |
.I rad |
183 |
will also update the contents of the octree, if necessary. |
184 |
There is no default value for this variable. |
185 |
.TP |
186 |
.BR move |
187 |
This variable specifies an object (or objects) with a specific |
188 |
motion and/or rendering priority. |
189 |
Four value arguments are expected for each appearance of this variable. |
190 |
The first is the name of a parent move object, or "void" if none. |
191 |
If given, the object's transformation will be prepended to that |
192 |
of its parent. |
193 |
The second argument is the name of this object, which will be used |
194 |
to name surfaces it contains, and as a modifier for any child objects |
195 |
that reference it. |
196 |
The third argument is the transformation string or file for this object. |
197 |
If this argument is enclosed in quotes and begins with a hyphen |
198 |
('-'), then it will be interpreted as a |
199 |
static transform specification a la |
200 |
.I xform(1). |
201 |
Otherwise, the argument will be taken as the name of a file that contains |
202 |
one such transform specification per line, corresponding to frames in the |
203 |
animation. |
204 |
A period ('.') may be given if no object transformation is desired. |
205 |
The fourth argument is the name of a |
206 |
.I RADIANCE |
207 |
scene file (or files) to be given to |
208 |
.I xform |
209 |
for transformation. |
210 |
If this argument begins with an exclamation point ('!'), then |
211 |
it will be interpreted as a command rather than a file. |
212 |
A final word corresponding to the frame number will be |
213 |
appended to the command, and its output will be passed to |
214 |
the input of |
215 |
.I xform |
216 |
for each frame. |
217 |
An optinal fifth argument |
218 |
specifies the rendering priority for this object. |
219 |
Values greater than 1 will result in preferential rendering of |
220 |
this object over other portions of the image when it appears in a frame. |
221 |
Values less than 1 will cause the rendering to neglect this object in |
222 |
favor of other parts of the image. |
223 |
A value of 3.0 can be interpreted as saying the viewer is three times more |
224 |
likely to look at this object than the background. |
225 |
A file may be given rather than a floating point value, and this file must |
226 |
contain one floating point number per line, corresponding to frames in the |
227 |
animation. |
228 |
.TP |
229 |
.BR VIEWFILE |
230 |
This variable names a file from which |
231 |
.I ranimove |
232 |
may extract the view for each frame in the animation. |
233 |
This file should contain one valid view per frame, starting with |
234 |
frame 1 on line 1. |
235 |
An exception is made for a view file with only a single view, which |
236 |
is used for every frame of the animation. |
237 |
In this case, the |
238 |
.I END |
239 |
variable must also be specified. |
240 |
This variable is required, and there is no default value. |
241 |
.TP |
242 |
.BR END |
243 |
The final frame number in the animation. |
244 |
The default value is computed from the number of views in the given |
245 |
.I VIEWFILE. |
246 |
Normally, this variable will only be given if the view is static. |
247 |
.TP |
248 |
.BR EXPOSURE |
249 |
This variable tells |
250 |
.I ranimate |
251 |
how to adjust the exposure for each frame. |
252 |
As in |
253 |
.I pfilt, |
254 |
the exposure setting may be given either as a multiplier or as a |
255 |
number of f-stop adjustments (eg. +2 or -1.5). |
256 |
Alternatively, a file name may be given, which |
257 |
.I ranimate |
258 |
will interpret as having one exposure value per line per frame, |
259 |
beginning with frame 1 at line 1. |
260 |
(See also the |
261 |
.I VIEWFILE |
262 |
variable, above.)\0 |
263 |
There is no default value for this variable. |
264 |
If it is not given, no exposure adjustments will be made. |
265 |
.TP |
266 |
.BR BASENAME |
267 |
The base output file name for the final frames. |
268 |
This string should contain a |
269 |
.I printf(3) |
270 |
style integer field to distinguish one frame number from another. |
271 |
The final frames will use this name with a ".pic" suffix. |
272 |
The default value is "frame%03d". |
273 |
.TP |
274 |
.BR MBLUR |
275 |
This variable specifies the fraction of a frame time that the shutter |
276 |
is simulated as being open for motion blur. |
277 |
Motion blur is computed by |
278 |
.I ranimove |
279 |
using image-based rendering methods, and will not be exact. |
280 |
The default value is 0, meaning no motion blurring. |
281 |
.TP |
282 |
.BR RATE |
283 |
This variable specifies the animation frame rate, in frames per second. |
284 |
This is needed to compute the animation error visibility. |
285 |
The default value is 8. |
286 |
.TP |
287 |
.BR RESOLUTION |
288 |
This variable specifies the desired final picture resolution. |
289 |
If only a single number is given, this value will be used for both |
290 |
the horizontal and vertical picture dimensions. |
291 |
If two numbers are given, the first is the horizontal resolution and |
292 |
the second is the vertical resolution. |
293 |
If three numbers are given, the third is taken as the pixel aspect |
294 |
ratio for the final picture (a real value). |
295 |
If the pixel aspect ratio is zero, the exact dimensions given will |
296 |
be those produced. |
297 |
Otherwise, they will be used as a frame in which the final image |
298 |
must fit. |
299 |
The default value for this variable is 640. |
300 |
.TP |
301 |
.BR lowq |
302 |
This variable may be used to specify rendering options |
303 |
for the initial, low-quality ray samples. |
304 |
It may be given either as a list of rendering parameter settings, |
305 |
or as variable settings for the |
306 |
.I rad |
307 |
command, in which case the |
308 |
.I RIF |
309 |
variable must also be specified. |
310 |
.TP |
311 |
.BR highq |
312 |
This variable may be used to specify rendering options |
313 |
for the final, high-quality ray samples. |
314 |
It may be given either as a list of rendering parameter settings, |
315 |
or as variable settings for the |
316 |
.I rad |
317 |
command, in which case the |
318 |
.I RIF |
319 |
variable must also be specified. |
320 |
.TP |
321 |
.BR oconv |
322 |
This variable may be used to specify special options for |
323 |
.I oconv. |
324 |
See the |
325 |
.I oconv(1) |
326 |
manual page for a list of valid options. |
327 |
(The |
328 |
.I \-f |
329 |
option is specified by default.)\0 |
330 |
.SH EXAMPLES |
331 |
A minimal input file for |
332 |
.I ranimove |
333 |
might look like this: |
334 |
.IP "" .3i |
335 |
.nf |
336 |
:::::::::: |
337 |
sample.rnm |
338 |
:::::::::: |
339 |
# The rad input file for our static scene: |
340 |
RIF= tutor.rif |
341 |
# The view file containing one view per frame: |
342 |
VIEWFILE= anim1.vf |
343 |
# Our central character and its motion: |
344 |
move= void myguy myguy.xf myguy.rad 2.0 |
345 |
.fi |
346 |
.PP |
347 |
Note that most of the variables are not set in this file. |
348 |
If we only want to see what default values |
349 |
.I ranimove |
350 |
would use without actually executing anything, we can invoke it |
351 |
thus: |
352 |
.IP "" .2i |
353 |
ranimove -n 0 -e sample.rnm |
354 |
.PP |
355 |
This will print the variables we have given as well as default |
356 |
values |
357 |
.I ranimove |
358 |
has assigned for us. |
359 |
.PP |
360 |
Usually, we execute |
361 |
.I ranimove |
362 |
in the background, redirecting the standard output and standard |
363 |
error to a file: |
364 |
.IP "" .2i |
365 |
ranimove sample.rnm >& sample.err & |
366 |
.PP |
367 |
If we decide that the default values |
368 |
.I ranimove |
369 |
has chosen for our variables are not all appropriate, we can add |
370 |
some more assignments to the file: |
371 |
.IP "" .3i |
372 |
.nf |
373 |
RES= 1024 # shoot for 1024x resolution |
374 |
MBLUR= .25 # apply camera motion blur |
375 |
RATE= 15 # 15 frames/second |
376 |
EXP= anim1.exp # adjust exposure according to file |
377 |
lowq= QUAL=Low # low quality ray sampling |
378 |
highq= QUAL=Med # high quality ray sampling |
379 |
.fi |
380 |
.PP |
381 |
Note the use of abbreviation for variable names. |
382 |
.SH AUTHOR |
383 |
Greg Ward |
384 |
.SH "SEE ALSO" |
385 |
oconv(1), pfilt(1), pinterp(1), rad(1), ranimate(1), rpict(1), xform(1) |