1 |
.\" RCSid "$Id: rtcontrib.1,v 1.15 2006/02/05 22:22:20 greg Exp $" |
2 |
.TH RTCONTRIB 1 5/25/05 RADIANCE |
3 |
.SH NAME |
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 ospec" |
21 |
][ |
22 |
.B "\-b binv" |
23 |
][ |
24 |
.B "\-bn nbins" |
25 |
] |
26 |
{ |
27 |
.B "\-m mod | \-M file" |
28 |
} |
29 |
.. |
30 |
[ |
31 |
.B $EVAR |
32 |
] |
33 |
[ |
34 |
.B @file |
35 |
] |
36 |
[ |
37 |
rtrace options |
38 |
] |
39 |
.B octree |
40 |
.br |
41 |
.B "rtcontrib [ options ] \-defaults" |
42 |
.SH DESCRIPTION |
43 |
.I Rtcontrib |
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 |
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 |
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 |
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 |
118 |
.I \-b |
119 |
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. |
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, |
134 |
.I \-bn |
135 |
and |
136 |
.I \-o |
137 |
options to the left of each |
138 |
.I \-m |
139 |
setting affect only that modifier. |
140 |
(The ordering of other options is unimportant.)\0 |
141 |
.PP |
142 |
If a |
143 |
.I \-b |
144 |
expression is defined for a particular modifier, |
145 |
the bin number will be evaluated at run time for each |
146 |
ray contribution from |
147 |
.I rtrace. |
148 |
Specifically, each ray's world intersection point will be assigned to |
149 |
the variables Px, Py, and Pz, and the normalized ray direction |
150 |
will be assigned to Dx, Dy, and Dz. |
151 |
These parameters may be combined with definitions given in |
152 |
.I \-e |
153 |
arguments and files read using the |
154 |
.I \-f |
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 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 |
181 |
.I \-o |
182 |
specification, then each modifier will have its own output file, with |
183 |
multiple values per record in the case of a non-zero |
184 |
.I \-b |
185 |
definition. |
186 |
If a "%d" format appears but no "%s", then each bin will get its own |
187 |
output file, with modifiers output in order in each record. |
188 |
For text output, each RGB coefficient triple is separated by a tab, |
189 |
with a newline at the end of each ray record. |
190 |
For binary output formats, there is no such delimiter to mark |
191 |
the end of each record. |
192 |
.PP |
193 |
Input and output format defaults to plain text, where each ray's |
194 |
origin and direction (6 real values) are given on input, |
195 |
and one line is produced per output file per ray. |
196 |
Alternative data representations may be specified by the |
197 |
.I \-f[io] |
198 |
option, which is described in the |
199 |
.I rtrace |
200 |
man page along with the associated |
201 |
.I \-x |
202 |
and |
203 |
.I \-y |
204 |
resolution settings. |
205 |
In particular, the color ('c') output data representation |
206 |
together with positive dimensions for |
207 |
.I \-x |
208 |
and |
209 |
.I \-y |
210 |
will produce an uncompressed RADIANCE picture, |
211 |
suitable for manipulation with |
212 |
.I pcomb(1) |
213 |
and related tools. |
214 |
.PP |
215 |
If the |
216 |
.I \-n |
217 |
option is specified with a value greater than 1, multiple |
218 |
.I rtrace |
219 |
processes will be used to accelerate computation on a shared |
220 |
memory machine. |
221 |
Note that there is no benefit to using more processes |
222 |
than there are local CPUs available to do the work, and the |
223 |
.I rtcontrib |
224 |
process itself may use a considerable amount of CPU time. |
225 |
.PP |
226 |
Options may be given on the command line and/or read from the |
227 |
environment and/or read from a file. |
228 |
A command argument beginning with a dollar sign ('$') is immediately |
229 |
replaced by the contents of the given environment variable. |
230 |
A command argument beginning with an at sign ('@') is immediately |
231 |
replaced by the contents of the given file. |
232 |
.SH EXAMPLES |
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 |
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 |
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 |
249 |
.PP |
250 |
To compute an array of illuminance contributions according to a Tregenza sky: |
251 |
.IP "" .2i |
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" |
259 |
cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1), |
260 |
rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1) |