ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/ranimove.1
Revision: 1.9
Committed: Fri Oct 5 00:59:38 2012 UTC (11 years, 7 months ago) by greg
Branch: MAIN
CVS Tags: rad5R4, rad5R2, rad4R2P2, rad5R0, rad5R1, rad4R2, rad4R2P1, rad5R3, HEAD
Changes since 1.8: +24 -10 lines
Log Message:
Created pmblur2 command to compute better motion blur from ranimove runs

File Contents

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