man/man1/rvu.1

.\" RCSid "$Id: rvu.1,v 1.13 2018/03/30 23:14:07 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 "\-pd, \-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 rvu,
but can be used in
.I rpict
with the
.I \-pd
option to simulate depth-of-field on views saved from
.I rvu.)
.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
.I 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 origin " [ forward [ right [up] ] ]"
Move the view origin forward or backwards the distance specified by the
.I forward
argument, along the view direction vector.
If at least two arguments are given, the second distance will be a
.I right
shift, or left if negative relative to the current view direction.
If three arguments are given, the third distance will be a distance of
.I up
along the view up vector, or down if negative.
The view direction and size are unchanged in any of the above cases.
With no arguments, the cursor is used to select the
view origin, and the direction will be determined by the
(reoriented) surface normal.
The view type and size will not be altered, but the up vector
may be changed if the new direction coincides.
.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,
so a positive value pivots the viewer to the right of the selected point.
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 using the right-hand rule.
A positive value rotates the view towards the left, and a negative value
looks to the right.
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.
.br
DISPLAY_GAMMA           the value to use for monitor gamma correction.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
getinfo(1), lookamb(1), mkpmap(1),
oconv(1), pfilt(1), rad(1), rpict(1), rtpict(1), rtrace(1)
Revision:	1.14
Committed:	Fri May 2 23:56:18 2025 UTC (39 hours, 20 minutes ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.13:	+13 -12 lines
Error occurred while calculating annotation data.
Log Message:	feat(rvu): Altered the "origin" command to take shift distances
#	Content
1	.\" RCSid "$Id: rvu.1,v 1.13 2018/03/30 23:14:07 greg Exp $"
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 "\-n nproc"
11	][
12	.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 "\-pd, \-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	The
66	.I \-n
67	option may be used to specify multiple processes,
68	to accelerate rendering.
69	.PP
70	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	.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 rvu,
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 rvu.)
169	.TP
170	.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
211	.I rad
212	input file used.
213	.TP
214	.BI move " [ mag [ x y z ] ]"
215	Move camera
216	.I mag
217	times closer to point
218	.I "x y z".
219	For a perspective projection (or fisheye view),
220	only the view point is changed;
221	the view direction and size remain constant.
222	The view size must be modified in a parallel projection since
223	it determines magnification.
224	If
225	.I "x y z"
226	is missing, the cursor is used to select the view center.
227	A negative magnification factor decreases the object size.
228	The default factor is one.
229	Care must be taken to avoid moving behind or inside other objects.
230	.TP
231	.BI new " [ nproc ]"
232	Restart the image, using the specified number of rendering processes.
233	Usually used after the "set" command.
234	.TP
235	.BI origin " [ forward [ right [up] ] ]"
236	Move the view origin forward or backwards the distance specified by the
237	.I forward
238	argument, along the view direction vector.
239	If at least two arguments are given, the second distance will be a
240	.I right
241	shift, or left if negative relative to the current view direction.
242	If three arguments are given, the third distance will be a distance of
243	.I up
244	along the view up vector, or down if negative.
245	The view direction and size are unchanged in any of the above cases.
246	With no arguments, the cursor is used to select the
247	view origin, and the direction will be determined by the
248	(reoriented) surface normal.
249	The view type and size will not be altered, but the up vector
250	may be changed if the new direction coincides.
251	.TP
252	.BI pivot " angle [ elev [ mag [ x y z ] ] ]"
253	Similar to the "move" command, but pivots the view about a selected point.
254	The
255	.I angle
256	is measured in degrees around the view up vector using the right hand rule,
257	so a positive value pivots the viewer to the right of the selected point.
258	The optional
259	.I elev
260	is the elevation in degrees from the pivot point; positive raises the view point
261	to look downward and negative lowers the view point to look upward.
262	.TP
263	.BR quit
264	Quit the program.
265	.TP
266	.BR ^R
267	Redraw the image.
268	Use when the display gets corrupted.
269	On some displays, occassionally forcing a redraw can improve appearance,
270	as more color information is available and the driver can make a better
271	color table selection.
272	.TP
273	.BI rotate " angle [ elev [ mag ] ]"
274	Rotate the camera horizontally by
275	.I angle
276	degrees using the right-hand rule.
277	A positive value rotates the view towards the left, and a negative value
278	looks to the right.
279	If an elevation is specified, the camera looks upward
280	.I elev
281	degrees.
282	(Negative means look downward.)
283	.TP
284	.BI set " [ var [ val ] ]"
285	Check/change program variable.
286	If
287	.I var
288	is absent, the list of available variables is displayed.
289	If
290	.I val
291	is absent, the current value of the variable is displayed
292	and changed interactively.
293	Otherwise, the variable
294	.I var
295	assumes the value
296	.I val.
297	Variables include:
298	ambient value (av),
299	ambient value weight (aw),
300	ambient bounces (ab),
301	ambient accuracy (aa),
302	ambient divisions (ad),
303	ambient radius (ar),
304	ambient samples (as),
305	black&white (b),
306	back face visibility (bv),
307	direct jitter (dj),
308	direct sampling (ds),
309	direct threshold (dt),
310	direct visibility (dv),
311	irradiance (i),
312	limit weight (lw),
313	limit recursion (lr),
314	medium extinction (me),
315	medium albedo (ma),
316	medium eccentricity (mg),
317	medium sampling (ms),
318	pixel sample (ps),
319	pixel threshold (pt),
320	specular jitter (sj),
321	specular threshold (st), and
322	uncorrelated sampling (u).
323	Once a variable has been changed, the "new" command can be used
324	to recompute the image with the new parameters.
325	If a program variable is not available here, it may show up under
326	some other command or it may be impossible to change
327	once the program is running.
328	.TP
329	.BI trace " [ xbeg ybeg zbeg xdir ydir zdir ]"
330	Trace a ray.
331	If the ray origin and direction are absent, the cursor is used
332	to pick a location in the image to trace.
333	The object intersected and its material, location and value are displayed.
334	.TP
335	.BI view " [ file [ comments ] ]"
336	Check/change view parameters.
337	If
338	.I file
339	is present, the view parameters are appended to a file, followed by
340	.I comments
341	if any.
342	Alternatively, view options may be given directly on the command line
343	instead of an output view file.
344	Otherwise, view parameters are displayed and changed interactively.
345	.TP
346	.BI V " [ vw [ rfile ] ]"
347	Append the current view as view
348	.I vw
349	in the rad file
350	.I rfile.
351	Compliment to
352	.I L
353	command.
354	Note that the view is simply appended to the file, and previous
355	views with the same name should be removed before using the file
356	with
357	.I rad.
358	.TP
359	.BI write " [ file ]"
360	Write picture to
361	.I file.
362	If argument is missing, the current file name is used.
363	.TP
364	.BR ^Z
365	Stop the program.
366	The screen will be redrawn when the program resumes.
367	.SH ENVIRONMENT
368	RAYPATH the directories to check for auxiliary files.
369	.br
370	DISPLAY_GAMMA the value to use for monitor gamma correction.
371	.SH AUTHOR
372	Greg Ward
373	.SH "SEE ALSO"
374	getinfo(1), lookamb(1), mkpmap(1),
375	oconv(1), pfilt(1), rad(1), rpict(1), rtpict(1), rtrace(1)