man/man1/rvu.1

.\" RCSid "$Id: rvu.1,v 1.4 2005/06/14 03:34:14 greg Exp $"
.TH RVU 1 1/1/04 RADIANCE
.SH NAME
rvu - generate RADIANCE images interactively
.SH SYNOPSIS
.B rvu
[
.B "rpict options"
][
.B "\-n nproc"
][
.B "\-o dev"
][
.B \-b
][
.B "\-pe exposure"
]
[
.B $EVAR
]
[
.B @file
]
.B octree
.br
.B "rvu [ options ] \-defaults"
.br
.B "rvu \-devices"
.SH DESCRIPTION
.I Rvu
generates RADIANCE images using
.I octree.
(The octree may be given as the output of a command enclosed in quotes
and preceded by a `!'.)\0
Options specify the viewing parameters as well as
giving some control over the calculation.
Options may be given on the command line and/or read from the
environment and/or read from a file.
A command argument beginning with a dollar sign ('$') is immediately
replaced by the contents of the given environment variable.
A command argument beginning with an at sign ('@') is immediately
replaced by the contents of the given file.
The options are the same as for rpict(1), with a few notable exceptions.
The
.I "\-r, \-z, \-S, \-P, \-PP"
and
.I \-t
options are not supported, and
.I \-o
specifies which output device is being used instead of the output
file.
The
.I "\-x, \-y"
and
.I \-pa
options are unnecessary, since
.I rvu
scales the display image to the specified output device.
Additionally, the
.I \-b
option improves the display on greyscale monitors, and
.I \-pe
may be used to set an initial exposure value.
.PP
The
.I \-n
option may be used to specify multiple processes,
to accelerate rendering.
.PP
In the second form, the default values
for the options are printed with a brief explanation.
In the third form, the list of supported output devices
is displayed.
.PP
.I rvu
starts rendering the image from the selected viewpoint and
gradually improves the resolution of the display until
interrupted by keyboard input.
.I rvu
then issues a prompt (usually ':') and accepts a command
line from the user.
.I rvu
may also stop its calculation and wait for command input if
the resolution of the display has reached the resolution of the
graphics device.
At this point, it will give the 'done:' prompt and await further
instructions.
If
.I rvu
runs out of memory due to lack of resources to store its computed
image, it will give the 'out of memory:' prompt.
At this prompt, the user can save the image, quit, or even restart
a new image, although this is not generally recommended
on virtual memory machines for efficiency reasons.
.PP
.I rvu
is not meant to be a rendering program, and we strongly recommend that
.I rpict(1)
be used instead for that purpose.
Since
.I rpict(1)
does not store its image in memory or update any display of its output,
it is much faster and less wasteful of its resources than
.I rvu.
.I rvu
is intended as a quick interactive program for deciding viewpoints
and debugging scene descriptions and is not suited for producing
polished images.
.SH COMMANDS
Once the program starts, a number of commands can be used
to control it.
A command is given by its name, which can be abbreviated,
followed by its arguments.
.TP 10n
.BI aim " [ mag [ x y z ] ]"
Zoom in by
.I "mag"
on point
.I "x y z".
The view point is held constant;
only the view direction and size are changed.
If
.I "x y z"
is missing, the cursor is used to select the view center.
A negative magnification factor means zoom out.
The default factor is one.
.TP
.BR ^C
Interrupt.
Go to the command line.
.TP
.BI exposure " [ spec ]"
Adjust exposure.
The number
.I spec
is a multiplier used to compensate the average exposure.
A value of 1 renormalizes the image to the computed average, which
is usually done immediately after startup.
If
.I spec
begins with a '+' or '-', 
the compensation is interpreted in f-stops (ie. the power of two).
If
.I spec
begins with an '=', an absolute setting is performed.
An '=' by itself permits interactive display and setting of the exposure.
If
.I spec
begins with an '@', the exposure is adjusted to present similar
visibility to what would be experienced in the real environment.
If
.I spec
is absent, or an '@' is followed by nothing, then
the cursor is used to pick a specific image
location for normalization.
.TP
.BI focus " [distance]"
Set focus distance for depth-of-field sampling.
If a distance in world coordinates is absent, then the cursor
is used to choose a point in the scene on which to focus.
(The focus distance setting does not affect rendering in
.I rview,
but can be used in
.I rpict
with the
.I \-pd
option to simulate depth-of-field on views saved from
.I rview.)
.TP
.BI frame " [ xmin ymin xmax ymax ]"
Set frame for refinement.
If coordinates are absent, the cursor is used to
pick frame boundaries.
If ``all'' is specified, the frame is reset to the entire image.
.TP
.BR free
Free cached object structures and associated data.
This command may be useful when memory is low and a completely
different view is being generated from the one previous.
.TP
.BI last " [ file ]"
Restore the previous view.
If a view or picture
.I file
is specified, the parameters are taken from the last view entry
in the file.
.TP
.BI L " [ vw [ rfile ] ]"
Load parameters for view
.I vw
from the
.I rad(1)
input file,
.I rfile.
Both
.I vw
and
.I rfile
must be given the first call, but subsequent calls will use the last
.I rfile
as a default, and "1" as the default view (ie. the first view
appearing in
.I rfile).
If
.I rvu
was started by
.I rad,
then the
.I rfile
parameter will initially default to the rad input file used.
.TP
.BI move " [ mag [ x y z ] ]"
Move camera
.I mag
times closer to point
.I "x y z".
For a perspective projection (or fisheye view),
only the view point is changed;
the view direction and size remain constant.
The view size must be modified in a parallel projection since
it determines magnification.
If
.I "x y z"
is missing, the cursor is used to select the view center.
A negative magnification factor decreases the object size.
The default factor is one.
Care must be taken to avoid moving behind or inside other objects.
.TP
.BI new " [ nproc ]"
Restart the image, using the specified number of rendering processes.
Usually used after the "set" command.
.TP
.BI pivot " angle [ elev [ mag [ x y z ] ] ]"
Similar to the "move" command, but pivots the view about a selected point.
The
.I angle
is measured in degrees around the view up vector using the right hand rule.
The optional
.I elev
is the elevation in degrees from the pivot point; positive raises the view point
to look downward and negative lowers the view point to look upward.
.TP
.BR quit
Quit the program.
.TP
.BR ^R
Redraw the image.
Use when the display gets corrupted.
On some displays, occassionally forcing a redraw can improve appearance,
as more color information is available and the driver can make a better
color table selection.
.TP
.BI rotate " angle [ elev [ mag ] ]"
Rotate the camera horizontally by
.I angle
degrees.
If an elevation is specified, the camera looks upward
.I elev
degrees.
(Negative means look downward.)
.TP
.BI set " [ var [ val ] ]"
Check/change program variable.
If
.I var
is absent, the list of available variables is displayed.
If
.I val
is absent, the current value of the variable is displayed
and changed interactively.
Otherwise, the variable
.I var
assumes the value
.I val.
Variables include:
ambient value (av),
ambient value weight (aw),
ambient bounces (ab),
ambient accuracy (aa),
ambient divisions (ad),
ambient radius (ar),
ambient samples (as),
black&white (b),
back face visibility (bv),
direct jitter (dj),
direct sampling (ds),
direct threshold (dt),
direct visibility (dv),
irradiance (i),
limit weight (lw),
limit recursion (lr),
medium extinction (me),
medium albedo (ma),
medium eccentricity (mg),
medium sampling (ms),
pixel sample (ps),
pixel threshold (pt),
specular jitter (sj),
specular threshold (st), and
uncorrelated sampling (u).
Once a variable has been changed, the "new" command can be used
to recompute the image with the new parameters.
If a program variable is not available here, it may show up under
some other command or it may be impossible to change
once the program is running.
.TP
.BI trace " [ xbeg ybeg zbeg xdir ydir zdir ]"
Trace a ray.
If the ray origin and direction are absent, the cursor is used
to pick a location in the image to trace.
The object intersected and its material, location and value are displayed.
.TP
.BI view " [ file [ comments ] ]"
Check/change view parameters.
If
.I file
is present, the view parameters are appended to a file, followed by
.I comments
if any.
Alternatively, view options may be given directly on the command line
instead of an output view file.
Otherwise, view parameters are displayed and changed interactively.
.TP
.BI V " [ vw [ rfile ] ]"
Append the current view as view
.I vw
in the rad file
.I rfile.
Compliment to
.I L
command.
Note that the view is simply appended to the file, and previous
views with the same name should be removed before using the file
with
.I rad.
.TP
.BI write " [ file ]"
Write picture to
.I file.
If argument is missing, the current file name is used.
.TP
.BR ^Z
Stop the program.
The screen will be redrawn when the program resumes.
.SH ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
DISPLAY_GAMMA           the value to use for monitor gamma correction.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), lookamb(1), oconv(1), pfilt(1), rad(1), rpict(1), rtrace(1)
Revision:	1.5
Committed:	Thu Aug 21 07:05:58 2008 UTC (16 years, 9 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R1, rad4R0
Changes since 1.4:	+10 -3 lines
Log Message:	Added -n option to rvu for multiple rendering processes
#	User	Rev	Content
1	greg	1.5	.\" RCSid "$Id: rvu.1,v 1.4 2005/06/14 03:34:14 greg Exp $"
2	greg	1.1	.TH RVU 1 1/1/04 RADIANCE
3			.SH NAME
4			rvu - generate RADIANCE images interactively
5			.SH SYNOPSIS
6			.B rvu
7			[
8			.B "rpict options"
9			][
10	greg	1.5	.B "\-n nproc"
11			][
12	greg	1.1	.B "\-o dev"
13			][
14			.B \-b
15			][
16			.B "\-pe exposure"
17			]
18			[
19			.B $EVAR
20			]
21			[
22			.B @file
23			]
24			.B octree
25			.br
26			.B "rvu [ options ] \-defaults"
27			.br
28			.B "rvu \-devices"
29			.SH DESCRIPTION
30			.I Rvu
31			generates RADIANCE images using
32			.I octree.
33			(The octree may be given as the output of a command enclosed in quotes
34			and preceded by a `!'.)\0
35			Options specify the viewing parameters as well as
36			giving some control over the calculation.
37			Options may be given on the command line and/or read from the
38			environment and/or read from a file.
39			A command argument beginning with a dollar sign ('$') is immediately
40			replaced by the contents of the given environment variable.
41			A command argument beginning with an at sign ('@') is immediately
42			replaced by the contents of the given file.
43			The options are the same as for rpict(1), with a few notable exceptions.
44			The
45			.I "\-r, \-z, \-S, \-P, \-PP"
46			and
47			.I \-t
48			options are not supported, and
49			.I \-o
50			specifies which output device is being used instead of the output
51			file.
52			The
53			.I "\-x, \-y"
54			and
55			.I \-pa
56			options are unnecessary, since
57			.I rvu
58			scales the display image to the specified output device.
59			Additionally, the
60			.I \-b
61			option improves the display on greyscale monitors, and
62			.I \-pe
63			may be used to set an initial exposure value.
64			.PP
65	greg	1.5	The
66			.I \-n
67			option may be used to specify multiple processes,
68			to accelerate rendering.
69			.PP
70	greg	1.1	In the second form, the default values
71			for the options are printed with a brief explanation.
72			In the third form, the list of supported output devices
73			is displayed.
74			.PP
75			.I rvu
76			starts rendering the image from the selected viewpoint and
77			gradually improves the resolution of the display until
78			interrupted by keyboard input.
79			.I rvu
80			then issues a prompt (usually ':') and accepts a command
81			line from the user.
82			.I rvu
83			may also stop its calculation and wait for command input if
84			the resolution of the display has reached the resolution of the
85			graphics device.
86			At this point, it will give the 'done:' prompt and await further
87			instructions.
88			If
89			.I rvu
90			runs out of memory due to lack of resources to store its computed
91			image, it will give the 'out of memory:' prompt.
92			At this prompt, the user can save the image, quit, or even restart
93			a new image, although this is not generally recommended
94			on virtual memory machines for efficiency reasons.
95			.PP
96			.I rvu
97			is not meant to be a rendering program, and we strongly recommend that
98			.I rpict(1)
99			be used instead for that purpose.
100			Since
101			.I rpict(1)
102			does not store its image in memory or update any display of its output,
103			it is much faster and less wasteful of its resources than
104			.I rvu.
105			.I rvu
106			is intended as a quick interactive program for deciding viewpoints
107			and debugging scene descriptions and is not suited for producing
108			polished images.
109			.SH COMMANDS
110			Once the program starts, a number of commands can be used
111			to control it.
112			A command is given by its name, which can be abbreviated,
113			followed by its arguments.
114			.TP 10n
115			.BI aim " [ mag [ x y z ] ]"
116			Zoom in by
117			.I "mag"
118			on point
119			.I "x y z".
120			The view point is held constant;
121			only the view direction and size are changed.
122			If
123			.I "x y z"
124			is missing, the cursor is used to select the view center.
125			A negative magnification factor means zoom out.
126			The default factor is one.
127			.TP
128			.BR ^C
129			Interrupt.
130			Go to the command line.
131			.TP
132			.BI exposure " [ spec ]"
133			Adjust exposure.
134			The number
135			.I spec
136			is a multiplier used to compensate the average exposure.
137			A value of 1 renormalizes the image to the computed average, which
138			is usually done immediately after startup.
139			If
140			.I spec
141			begins with a '+' or '-',
142			the compensation is interpreted in f-stops (ie. the power of two).
143			If
144			.I spec
145			begins with an '=', an absolute setting is performed.
146			An '=' by itself permits interactive display and setting of the exposure.
147			If
148			.I spec
149			begins with an '@', the exposure is adjusted to present similar
150			visibility to what would be experienced in the real environment.
151			If
152			.I spec
153			is absent, or an '@' is followed by nothing, then
154			the cursor is used to pick a specific image
155			location for normalization.
156			.TP
157	greg	1.2	.BI focus " [distance]"
158			Set focus distance for depth-of-field sampling.
159			If a distance in world coordinates is absent, then the cursor
160			is used to choose a point in the scene on which to focus.
161			(The focus distance setting does not affect rendering in
162			.I rview,
163			but can be used in
164			.I rpict
165			with the
166			.I \-pd
167			option to simulate depth-of-field on views saved from
168			.I rview.)
169			.TP
170	greg	1.1	.BI frame " [ xmin ymin xmax ymax ]"
171			Set frame for refinement.
172			If coordinates are absent, the cursor is used to
173			pick frame boundaries.
174			If ``all'' is specified, the frame is reset to the entire image.
175			.TP
176			.BR free
177			Free cached object structures and associated data.
178			This command may be useful when memory is low and a completely
179			different view is being generated from the one previous.
180			.TP
181			.BI last " [ file ]"
182			Restore the previous view.
183			If a view or picture
184			.I file
185			is specified, the parameters are taken from the last view entry
186			in the file.
187			.TP
188			.BI L " [ vw [ rfile ] ]"
189			Load parameters for view
190			.I vw
191			from the
192			.I rad(1)
193			input file,
194			.I rfile.
195			Both
196			.I vw
197			and
198			.I rfile
199			must be given the first call, but subsequent calls will use the last
200			.I rfile
201			as a default, and "1" as the default view (ie. the first view
202			appearing in
203			.I rfile).
204			If
205			.I rvu
206			was started by
207			.I rad,
208			then the
209			.I rfile
210			parameter will initially default to the rad input file used.
211			.TP
212			.BI move " [ mag [ x y z ] ]"
213			Move camera
214			.I mag
215			times closer to point
216			.I "x y z".
217			For a perspective projection (or fisheye view),
218			only the view point is changed;
219			the view direction and size remain constant.
220			The view size must be modified in a parallel projection since
221			it determines magnification.
222			If
223			.I "x y z"
224			is missing, the cursor is used to select the view center.
225			A negative magnification factor decreases the object size.
226			The default factor is one.
227			Care must be taken to avoid moving behind or inside other objects.
228			.TP
229	greg	1.5	.BI new " [ nproc ]"
230			Restart the image, using the specified number of rendering processes.
231	greg	1.1	Usually used after the "set" command.
232			.TP
233			.BI pivot " angle [ elev [ mag [ x y z ] ] ]"
234			Similar to the "move" command, but pivots the view about a selected point.
235			The
236			.I angle
237			is measured in degrees around the view up vector using the right hand rule.
238			The optional
239			.I elev
240			is the elevation in degrees from the pivot point; positive raises the view point
241			to look downward and negative lowers the view point to look upward.
242			.TP
243			.BR quit
244			Quit the program.
245			.TP
246			.BR ^R
247			Redraw the image.
248			Use when the display gets corrupted.
249			On some displays, occassionally forcing a redraw can improve appearance,
250			as more color information is available and the driver can make a better
251			color table selection.
252			.TP
253			.BI rotate " angle [ elev [ mag ] ]"
254			Rotate the camera horizontally by
255			.I angle
256			degrees.
257			If an elevation is specified, the camera looks upward
258			.I elev
259			degrees.
260			(Negative means look downward.)
261			.TP
262			.BI set " [ var [ val ] ]"
263			Check/change program variable.
264			If
265			.I var
266			is absent, the list of available variables is displayed.
267			If
268			.I val
269			is absent, the current value of the variable is displayed
270			and changed interactively.
271			Otherwise, the variable
272			.I var
273			assumes the value
274			.I val.
275			Variables include:
276			ambient value (av),
277			ambient value weight (aw),
278			ambient bounces (ab),
279			ambient accuracy (aa),
280			ambient divisions (ad),
281			ambient radius (ar),
282			ambient samples (as),
283			black&white (b),
284	greg	1.4	back face visibility (bv),
285	greg	1.1	direct jitter (dj),
286			direct sampling (ds),
287			direct threshold (dt),
288			direct visibility (dv),
289			irradiance (i),
290			limit weight (lw),
291			limit recursion (lr),
292			medium extinction (me),
293			medium albedo (ma),
294			medium eccentricity (mg),
295			medium sampling (ms),
296			pixel sample (ps),
297			pixel threshold (pt),
298	greg	1.4	specular jitter (sj),
299			specular threshold (st), and
300			uncorrelated sampling (u).
301	greg	1.1	Once a variable has been changed, the "new" command can be used
302			to recompute the image with the new parameters.
303			If a program variable is not available here, it may show up under
304			some other command or it may be impossible to change
305			once the program is running.
306			.TP
307			.BI trace " [ xbeg ybeg zbeg xdir ydir zdir ]"
308			Trace a ray.
309			If the ray origin and direction are absent, the cursor is used
310			to pick a location in the image to trace.
311			The object intersected and its material, location and value are displayed.
312			.TP
313			.BI view " [ file [ comments ] ]"
314			Check/change view parameters.
315			If
316			.I file
317			is present, the view parameters are appended to a file, followed by
318			.I comments
319			if any.
320			Alternatively, view options may be given directly on the command line
321			instead of an output view file.
322			Otherwise, view parameters are displayed and changed interactively.
323			.TP
324			.BI V " [ vw [ rfile ] ]"
325			Append the current view as view
326			.I vw
327			in the rad file
328			.I rfile.
329			Compliment to
330			.I L
331			command.
332			Note that the view is simply appended to the file, and previous
333			views with the same name should be removed before using the file
334			with
335			.I rad.
336			.TP
337			.BI write " [ file ]"
338			Write picture to
339			.I file.
340			If argument is missing, the current file name is used.
341			.TP
342			.BR ^Z
343			Stop the program.
344			The screen will be redrawn when the program resumes.
345			.SH ENVIRONMENT
346			RAYPATH the directories to check for auxiliary files.
347			DISPLAY_GAMMA the value to use for monitor gamma correction.
348			.SH AUTHOR
349			Greg Ward
350			.SH "SEE ALSO"
351			getinfo(1), lookamb(1), oconv(1), pfilt(1), rad(1), rpict(1), rtrace(1)