man/man1/rvu.1

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