man/man1/rvu.1

.\" RCSid "$Id$"
.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 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),
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),
back face visibility (bv),
specular jitter (sj), and
specular threshold (st).
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.1
Committed:	Thu Jan 1 19:31:45 2004 UTC (20 years, 4 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R6, rad3R6P1
Log Message:	Renamed rview, lam, calc, and neat to rvu, rlam, icalc, and neaten
#	Content
1	.\" RCSid "$Id$"
2	.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	.BI frame " [ xmin ymin xmax ymax ]"
151	Set frame for refinement.
152	If coordinates are absent, the cursor is used to
153	pick frame boundaries.
154	If ``all'' is specified, the frame is reset to the entire image.
155	.TP
156	.BR free
157	Free cached object structures and associated data.
158	This command may be useful when memory is low and a completely
159	different view is being generated from the one previous.
160	.TP
161	.BI last " [ file ]"
162	Restore the previous view.
163	If a view or picture
164	.I file
165	is specified, the parameters are taken from the last view entry
166	in the file.
167	.TP
168	.BI L " [ vw [ rfile ] ]"
169	Load parameters for view
170	.I vw
171	from the
172	.I rad(1)
173	input file,
174	.I rfile.
175	Both
176	.I vw
177	and
178	.I rfile
179	must be given the first call, but subsequent calls will use the last
180	.I rfile
181	as a default, and "1" as the default view (ie. the first view
182	appearing in
183	.I rfile).
184	If
185	.I rvu
186	was started by
187	.I rad,
188	then the
189	.I rfile
190	parameter will initially default to the rad input file used.
191	.TP
192	.BI move " [ mag [ x y z ] ]"
193	Move camera
194	.I mag
195	times closer to point
196	.I "x y z".
197	For a perspective projection (or fisheye view),
198	only the view point is changed;
199	the view direction and size remain constant.
200	The view size must be modified in a parallel projection since
201	it determines magnification.
202	If
203	.I "x y z"
204	is missing, the cursor is used to select the view center.
205	A negative magnification factor decreases the object size.
206	The default factor is one.
207	Care must be taken to avoid moving behind or inside other objects.
208	.TP
209	.BR new
210	Restart the image.
211	Usually used after the "set" command.
212	.TP
213	.BI pivot " angle [ elev [ mag [ x y z ] ] ]"
214	Similar to the "move" command, but pivots the view about a selected point.
215	The
216	.I angle
217	is measured in degrees around the view up vector using the right hand rule.
218	The optional
219	.I elev
220	is the elevation in degrees from the pivot point; positive raises the view point
221	to look downward and negative lowers the view point to look upward.
222	.TP
223	.BR quit
224	Quit the program.
225	.TP
226	.BR ^R
227	Redraw the image.
228	Use when the display gets corrupted.
229	On some displays, occassionally forcing a redraw can improve appearance,
230	as more color information is available and the driver can make a better
231	color table selection.
232	.TP
233	.BI rotate " angle [ elev [ mag ] ]"
234	Rotate the camera horizontally by
235	.I angle
236	degrees.
237	If an elevation is specified, the camera looks upward
238	.I elev
239	degrees.
240	(Negative means look downward.)
241	.TP
242	.BI set " [ var [ val ] ]"
243	Check/change program variable.
244	If
245	.I var
246	is absent, the list of available variables is displayed.
247	If
248	.I val
249	is absent, the current value of the variable is displayed
250	and changed interactively.
251	Otherwise, the variable
252	.I var
253	assumes the value
254	.I val.
255	Variables include:
256	ambient value (av),
257	ambient value weight (aw),
258	ambient bounces (ab),
259	ambient accuracy (aa),
260	ambient divisions (ad),
261	ambient radius (ar),
262	ambient samples (as),
263	black&white (b),
264	direct jitter (dj),
265	direct sampling (ds),
266	direct threshold (dt),
267	direct visibility (dv),
268	irradiance (i),
269	limit weight (lw),
270	limit recursion (lr),
271	medium extinction (me),
272	medium albedo (ma),
273	medium eccentricity (mg),
274	medium sampling (ms),
275	pixel sample (ps),
276	pixel threshold (pt),
277	back face visibility (bv),
278	specular jitter (sj), and
279	specular threshold (st).
280	Once a variable has been changed, the "new" command can be used
281	to recompute the image with the new parameters.
282	If a program variable is not available here, it may show up under
283	some other command or it may be impossible to change
284	once the program is running.
285	.TP
286	.BI trace " [ xbeg ybeg zbeg xdir ydir zdir ]"
287	Trace a ray.
288	If the ray origin and direction are absent, the cursor is used
289	to pick a location in the image to trace.
290	The object intersected and its material, location and value are displayed.
291	.TP
292	.BI view " [ file [ comments ] ]"
293	Check/change view parameters.
294	If
295	.I file
296	is present, the view parameters are appended to a file, followed by
297	.I comments
298	if any.
299	Alternatively, view options may be given directly on the command line
300	instead of an output view file.
301	Otherwise, view parameters are displayed and changed interactively.
302	.TP
303	.BI V " [ vw [ rfile ] ]"
304	Append the current view as view
305	.I vw
306	in the rad file
307	.I rfile.
308	Compliment to
309	.I L
310	command.
311	Note that the view is simply appended to the file, and previous
312	views with the same name should be removed before using the file
313	with
314	.I rad.
315	.TP
316	.BI write " [ file ]"
317	Write picture to
318	.I file.
319	If argument is missing, the current file name is used.
320	.TP
321	.BR ^Z
322	Stop the program.
323	The screen will be redrawn when the program resumes.
324	.SH ENVIRONMENT
325	RAYPATH the directories to check for auxiliary files.
326	DISPLAY_GAMMA the value to use for monitor gamma correction.
327	.SH AUTHOR
328	Greg Ward
329	.SH "SEE ALSO"
330	getinfo(1), lookamb(1), oconv(1), pfilt(1), rad(1), rpict(1), rtrace(1)