ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/Development/ray/doc/man/man1/rtcontrib.1

Comparing ray/doc/man/man1/rtcontrib.1 (file contents):
Revision 1.2 by greg, Thu May 26 18:53:04 2005 UTC vs.
Revision 1.16 by greg, Tue Sep 4 17:36:41 2007 UTC

#	Line 1 | Line 1
1		.\" RCSid "$Id$"
2	<	.TH RPIECE 1 5/25/05 RADIANCE
2	>	.TH RTCONTRIB 1 5/25/05 RADIANCE
3		.SH NAME
4	<	rtcontrib - compute contributions in a RADIANCE scene
4	>	rtcontrib - compute contribution coefficients in a RADIANCE scene
5		.SH SYNOPSIS
6		.B rtcontrib
7		[
8		.B "\-n nprocs"
9		][
10	+	.B \-V
11	+	][
12	+	.B \-fo
13	+	|
14	+	.B \-r
15	+	][
16		.B "\-e expr"
17		][
18		.B "\-f source"
19		][
20	<	.B "\-o fspec"
20	>	.B "\-o ospec"
21		][
22		.B "\-b binv"
23	+	][
24	+	.B "\-bn nbins"
25		]
26	<	.B "\-m mod .."
26	>	{
27	>	.B "\-m mod | \-M file"
28	>	}
29	>	..
30		[
31		.B $EVAR
32		]
#	Line 26 | Line 37 | rtcontrib - compute contributions in a RADIANCE scene
37		rtrace options
38		]
39		.B octree
40	+	.br
41	+	.B "rtcontrib [ options ] \-defaults"
42		.SH DESCRIPTION
43		.I Rtcontrib
44	<	computes ray contributions (i.e., color coefficients)
44	>	computes ray coefficients
45		for objects whose modifiers are named in one or more
46		.I \-m
47		settings.
48		These modifiers are usually materials associated with
49		light sources or sky domes, and must directly modify some geometric
50		primitives to be considered in the output.
51	<	The computed contributions can then be used in linear combination to
51	>	A modifier list may also be read from a file using the
52	>	.I \-M
53	>	option.
54	>	The RAYPATH environment variable determines directories to search for
55	>	this file.
56	>	(No search takes place if a file name begins with a '.', '/' or '~'
57	>	character.)\0
58	>	.PP
59	>	By setting the boolean
60	>	.I \-V
61	>	option, you may instruct
62	>	.I rtcontrib
63	>	to report the contribution from each material rather than the ray
64	>	coefficient.
65	>	This is particularly useful for light sources with directional output
66	>	distributions, whose value would otherwise be lost in the shuffle.
67	>	With the default
68	>	.I -V-
69	>	setting, the output of rtcontrib is a coefficient that must be multiplied
70	>	by the radiance of each material to arrive at a final contribution.
71	>	This is more convenient for computing daylight coefficeints, or cases
72	>	where the actual radiance is not desired.
73	>	Use the
74	>	.I -V+
75	>	setting when you wish to simply sum together contributions
76	>	(with possible adjustment factors) to obtain a final radiance value.
77	>	Combined with the
78	>	.I \-i
79	>	or
80	>	.I \-I
81	>	option, irradiance contributions are reported by
82	>	.I \-V+
83	>	rather than radiance, and
84	>	.I \-V-
85	>	coefficients contain an additonal factor of PI.
86	>	.PP
87	>	The output of
88	>	.I rtcontrib
89	>	has many potential uses.
90	>	Source contributions can be used as components in linear combination to
91		reproduce any desired variation, e.g., simulating lighting controls or
92		changing sky conditions via daylight coefficients.
93		More generally,
94		.I rtcontrib
95	<	may be used to compute input-output relationships in optical
96	<	systems, such as light pipes and shading devices.
95	>	can be used to compute arbitrary input-output relationships in optical
96	>	systems, such as luminaires, light pipes, and shading devices.
97		.PP
98		.I Rtcontrib
99		calls
100		.I rtrace(1)
101	<	to calculate the contributions for each input ray,
102	<	and the output tallies are sent to one or more files according to the
101	>	with the \-oTW (or \-oTV) option to calculate the daughter ray
102	>	contributions for each input ray, and the output tallies
103	>	are sent to one or more destinations according to the given
104		.I \-o
105		specification.
106	+	If a destination begins with an exclamation mark ('!'), then
107	+	a pipe is opened to a command and data is sent to its standard input.
108	+	Otherwise, the destination is treated as a file.
109	+	An existing file of the same name will not be clobbered, unless the
110	+	.I \-fo
111	+	option is given.
112	+	If instead the
113	+	.I \-r
114	+	option is specified, data recovery is attempted on existing files.
115		If an output specification contains a "%s" format, this will be
116		replaced by the modifier name.
117		The
#	Line 58 | Line 120 | option may be used to further define
120		a "bin number" within each object if finer resolution is needed, and
121		this will be applied to a "%d" format in the output file
122		specification if present.
123	<	(The actual bin number is computed at run time based on ray direction
124	<	and surface intersection, as described below.)\0
123	>	The actual bin number is computed at run time based on ray direction
124	>	and surface intersection, as described below.
125	>	If the number of bins is known in advance, it should be specified with the
126	>	.I \-bn
127	>	option, and this is critical for output files containing multiple values
128	>	per record.
129	>	Since bin numbers start from 0, the bin count is always equal to
130	>	the last bin plus 1.
131	>	Set the this value to 0 if the bin count is unknown (the default).
132		The most recent
133	<	.I \-b
133	>	.I \-b,
134	>	.I \-bn
135		and
136		.I \-o
137		options to the left of each
#	Line 80 | Line 150 | the variables Px, Py, and Pz, and the normalized ray d
150		will be assigned to Dx, Dy, and Dz.
151		These parameters may be combined with definitions given in
152		.I \-e
153	<	options and files read in
153	>	arguments and files read using the
154		.I \-f
155	<	options, to compute the bin, which will be
155	>	option.
156	>	The computed bin value will be
157		rounded to the nearest whole number.
158		This mechanism allows the user to define precise regions or directions
159		they wish to accumulate, such as the Tregenza sky discretization,
160		which would be otherwise impossible to specify
161		as a set of RADIANCE primitives.
162	+	The rules and predefined functions available for these expressions are
163	+	described in the
164	+	.I rcalc(1)
165	+	man page.
166	+	Unlike
167	+	.I rcalc,
168	+	.I rtcontrib
169	+	will search the RADIANCE library directories for each file given in a
170	+	.I \-f
171	+	option.
172		.PP
173		If no
174		.I \-o
175		specification is given, results are written on the standard output in order
176		of modifier (as given on the command line) then bin number.
177	<	Concatenated data is also sent to a lone output file (i.e., an initial
177	>	Concatenated data is also sent to a single destination (i.e., an initial
178		.I \-o
179		specification without formatting strings).
180		If a "%s" format appears but no "%d" in the
#	Line 152 | Line 233 | replaced by the contents of the given file.
233		To compute the proportional contributions from sources modified
234		by "light1" vs. "light2" on a set of illuminance values:
235		.IP "" .2i
236	<	rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
236	>	rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
237		.PP
238		To generate a pair of images corresponding to these two lights'
239		contributions:
240		.IP "" .2i
241	<	vwrays -ff -x 1024 -y 1024 -vf best.vf |
242	<	rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
243	<	@render.opt -o c_%s.pic -m light1 -m light2 scene.oct
241	>	vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
242	>	rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
243	>	@render.opt \-o c_%s.pic \-m light1 \-m light2 scene.oct
244		.PP
245		These images may then be recombined using the desired outputs
246		of light1 and light2:
247		.IP "" .2i
248	<	pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
248	>	pcomb \-c 100 90 75 c_light1.pic \-c 50 55 57 c_light2.pic > combined.pic
249		.PP
250		To compute an array of illuminance contributions according to a Tregenza sky:
251		.IP "" .2i
252	<	rtcontrib -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
253	<	@render.opt -f tregenza.cal scene.oct < test.dat
252	>	rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
253	>	@render.opt \-f tregenza.cal scene.oct < test.dat
254	>	.SH ENVIRONMENT
255	>	RAYPATH         path to search for \-f and \-M files
256		.SH AUTHOR
257		Greg Ward
258		.SH "SEE ALSO"

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines (old)
>	Changed lines (new)