man/man1/ranimove.1

.\" RCSid "$Id"
.SH NAME
ranimove - render a RADIANCE animation with motion
.SH SYNOPSIS
.B ranimove
[
.B \-s
][
.B \-e
][
.B \-w
][
.B "\-f beg,end"
][
.B "\-n nprocs"
][
.B "\-t sec"
][
.B "\-d jnd"
]
.B rnmfile
.SH DESCRIPTION
.I Ranimove
is a program for progressive animation rendering.
Variables in the given
.I rnmfile
indicate input files, output file names,
and various other controls and options.
.PP
Normally, progress reports are written to the standard output, but the
.I \-s
option tells
.I ranimove
to do its work silently.
The
.I \-e
option tells
.I ranimove
to explicate all variables used for the animation, including
default values not specified in the input file, and print them on
the standard output.
The
.I \-w
option turns off warnings about multiply and misassigned variables and
non-fatal rendering problems.
.PP
Normally,
.I ranimove
will produce one animation frame for each view given in the specified
view file.
If the
.I \-f
option is specified, the animation will resume at the given frame, and
continue to the end of the sequence, or to the second frame if one is given
(separated from the first by a comma but no space).
.PP
The
.I \-n
option specifies the number of processes to use for rendering.
The default value is 1, which is appropriate for most machines
that have a single central processing unit (CPU).
If you are running on a machine with multiple CPUs, a larger
value up to the number of processors may be used
to improve rendering speed, depending on the system load.
.PP
Because
.I ranimove
renders each frame progressively, it needs some criteria for when
to proceed to the next frame in the animation.
The
.I \-t
option is used to specify the maximum number of seconds to spend
on any one frame.
The default value for this option is 60 seconds.
Additionally, the
.I \-d
option may be used to specify a termination
threshold in just-noticeable-differences.
If the error can be reduced below this number of JNDs
over the whole frame before the time allocation is spent,
.I ranimove
will then proceed to the next frame.
A value of 2.0 JNDs is the point at which 75% of the people will notice
a difference, and this is the level usually selected for such a
termination test.
There is no default value for this option, which means that rendering
will proceed until the time allocation is spent for each frame, regardless.
If
.I \-t
is set to 0,
.I ranimove
will spend as much time as it takes to reduce the
visible error below the value set by the
.I \-d
option.
.PP
.I Ranimove
renders each frame in three stages.
In the first stage, a low-quality image
is rendered using one ray sample per 16 pixels.
In the second stage, pixels from the previous frame are extrapolated to
their corresponding positions in
this one, based on the given camera and object movements.
A set of heuristics is applied
to prevent errors in specular highlights and shadows, avoiding
some of the errors typical with the
.I pinterp(1)
program.
In the third stage, additional high-quality samples are used to refine
important regions of the image that are judged to have visible errors.
This proceeds until the stopping criteria specified by the
.I \-t
and
.I -d
options are met,
when the frame is filtered and written to the designated picture file.
.PP
The chief differences between this program and
.I ranimate(1)
are that motion blur is computed for objects as well as camera movement,
and its progressive rendering allows better control over the tradeoff
between frame accuracy and rendering time.
Fewer controls are provided for managing the picture files produced by
.I ranimove,
and no facilities for distributed rendering are available other
than executing
.I ranimove
on different machines using the
.I \-f
option to manually partition the work.
.PP
Animation variable assignments appear one per line in
.I rnmfile.
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.
Comments in
.I rnmfile
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 OCTREE
The name of the base octree file, which should be generated by the
.I oconv(1)
command using the
.I \-f
option.
There is no default value for this variable.
If no
.I RIF
variable is given, the octree must be specified.
.TP
.BR RIF
This variable specifies a
.I rad(1)
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 control rendering parameters.
.I Ranimate
will also extract default settings for the common variables:
.I OCTREE,
.I RESOLUTION,
and
.I EXPOSURE.
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 move
This variable specifies an object (or objects) with a specific
motion and/or rendering priority.
Four value arguments are expected for each appearance of this variable.
The first is the name of a parent move object, or "void" if none.
If given, the object's transformation will be prepended to that
of its parent.
The second argument is the name of this object, which will be used
to name surfaces it contains, and as a modifier for any child objects
that reference it.
The third argument is the transformation string or file for this object.
If this argument is enclosed in quotes and begins with a hyphen
('-'), then it will be interpreted as a
static transform specification a la
.I xform(1).
Otherwise, the argument will be taken as the name of a file that contains
one such transform specification per line, corresponding to frames in the
animation.
A period ('.') may be given if no object transformation is desired.
The fourth argument is the name of a
.I RADIANCE
scene file (or files) to be given to
.I xform
for transformation.
If this argument begins with an exclamation point ('!'), then
it will be interpreted as a command rather than a file.
A final word corresponding to the frame number will be
appended to the command, and its output will be passed to
the input of
.I xform
for each frame.
An optinal fifth argument
specifies the rendering priority for this object.
Values greater than 1 will result in preferential rendering of
this object over other portions of the image when it appears in a frame.
Values less than 1 will cause the rendering to neglect this object in
favor of other parts of the image.
A value of 3.0 can be interpreted as saying the viewer is three times more
likely to look at this object than the background.
A file may be given rather than a floating point value, and this file must
contain one floating point number per line, corresponding to frames in the
animation.
.TP
.BR VIEWFILE
This variable names a file from which
.I ranimove
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.
An exception is made for a view file with only a single view, which
is used for every frame of the animation.
In this case, the
.I END
variable must also be specified.
This variable is required, and there is no default value.
.TP
.BR END
The final frame number in the animation.
The default value is computed from the number of views in the given
.I VIEWFILE.
Normally, this variable will only be given if the view is static.
.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, no exposure adjustments will be made.
.TP
.BR BASENAME
The base output file name for the final frames.
This string 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 ".pic" suffix.
The default value is "frame%03d".
.TP
.BR MBLUR
This variable specifies the fraction of a frame time that the shutter
is simulated as being open for motion blur.
Motion blur is computed by
.I ranimove
using image-based rendering methods, and will not be exact.
The default value is 0, meaning no motion blurring.
.TP
.BR RATE
This variable specifies the animation frame rate, in frames per second.
This is needed to compute the animation error visibility.
The default value is 8.
.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 lowq
This variable may be used to specify rendering options
for the initial, low-quality ray samples.
It may be given either as a list of rendering parameter settings,
or as variable settings for the
.I rad
command, in which case the
.I RIF
variable must also be specified.
.TP
.BR highq
This variable may be used to specify rendering options
for the final, high-quality ray samples.
It may be given either as a list of rendering parameter settings,
or as variable settings for the
.I rad
command, in which case the
.I RIF
variable must also be specified.
.TP
.BR oconv
This variable may be used to specify special options for
.I oconv.
See the
.I oconv(1)
manual page for a list of valid options.
(The
.I \-f
option is specified by default.)\0
.SH EXAMPLES
A minimal input file for
.I ranimove
might look like this:
.IP "" .3i
.nf
::::::::::
sample.rnm
::::::::::
# The rad input file for our static scene:
RIF= tutor.rif
# The view file containing one view per frame:
VIEWFILE= anim1.vf
# Our central character and its motion:
move= void myguy myguy.xf myguy.rad 2.0
.fi
.PP
Note that most of the variables are not set in this file.
If we only want to see what default values
.I ranimove
would use without actually executing anything, we can invoke it
thus:
.IP "" .2i
ranimove -n 0 -e sample.rnm
.PP
This will print the variables we have given as well as default
values
.I ranimove
has assigned for us.
.PP
Usually, we execute
.I ranimove
in the background, redirecting the standard output and standard
error to a file:
.IP "" .2i
ranimove sample.rnm >& sample.err &
.PP
If we decide that the default values
.I ranimove
has chosen for our variables are not all appropriate, we can add
some more assignments to the file:
.IP "" .3i
.nf
RES= 1024                               # shoot for 1024x resolution
MBLUR= .25                              # apply camera motion blur
RATE= 15                                # 15 frames/second
EXP= anim1.exp                          # adjust exposure according to file
lowq= QUAL=Low                          # low quality ray sampling
highq= QUAL=Med                         # high quality ray sampling
.fi
.PP
Note the use of abbreviation for variable names.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
oconv(1), pfilt(1), pinterp(1), rad(1), ranimate(1), rpict(1), xform(1)
Revision:	1.1
Committed:	Tue Mar 11 19:20:21 2003 UTC (21 years, 2 months ago) by greg
Branch:	MAIN
Log Message:	Added documentation to repository
#	Content
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)