1 |
greg |
1.11 |
.\" RCSid "$Id: rtcontrib.1,v 1.10 2005/06/10 20:53:55 greg Exp $" |
2 |
greg |
1.3 |
.TH RTCONTRIB 1 5/25/05 RADIANCE |
3 |
greg |
1.1 |
.SH NAME |
4 |
greg |
1.5 |
rtcontrib - compute contribution coefficients in a RADIANCE scene |
5 |
greg |
1.1 |
.SH SYNOPSIS |
6 |
|
|
.B rtcontrib |
7 |
|
|
[ |
8 |
|
|
.B "\-n nprocs" |
9 |
|
|
][ |
10 |
greg |
1.8 |
.B \-r |
11 |
|
|
][ |
12 |
greg |
1.1 |
.B "\-e expr" |
13 |
|
|
][ |
14 |
|
|
.B "\-f source" |
15 |
|
|
][ |
16 |
greg |
1.7 |
.B "\-o ospec" |
17 |
greg |
1.1 |
][ |
18 |
|
|
.B "\-b binv" |
19 |
|
|
] |
20 |
greg |
1.9 |
{ |
21 |
|
|
.B "\-m mod | \-M file" |
22 |
|
|
} |
23 |
|
|
.. |
24 |
greg |
1.1 |
[ |
25 |
|
|
.B $EVAR |
26 |
|
|
] |
27 |
|
|
[ |
28 |
|
|
.B @file |
29 |
|
|
] |
30 |
|
|
[ |
31 |
|
|
rtrace options |
32 |
|
|
] |
33 |
|
|
.B octree |
34 |
greg |
1.4 |
.br |
35 |
|
|
.B "rtcontrib [ options ] \-defaults" |
36 |
greg |
1.1 |
.SH DESCRIPTION |
37 |
|
|
.I Rtcontrib |
38 |
|
|
computes ray contributions (i.e., color coefficients) |
39 |
|
|
for objects whose modifiers are named in one or more |
40 |
|
|
.I \-m |
41 |
|
|
settings. |
42 |
greg |
1.2 |
These modifiers are usually materials associated with |
43 |
|
|
light sources or sky domes, and must directly modify some geometric |
44 |
|
|
primitives to be considered in the output. |
45 |
greg |
1.9 |
A modifier list may also be read from a file using the |
46 |
|
|
.I \-M |
47 |
|
|
option. |
48 |
greg |
1.10 |
The RAYPATH environment variable determines directories to search for |
49 |
|
|
this file. |
50 |
|
|
(No search takes place if a file name begins with a '.', '/' or '~' |
51 |
|
|
character.)\0 |
52 |
greg |
1.9 |
.PP |
53 |
greg |
1.3 |
The output of |
54 |
|
|
.I rtcontrib |
55 |
|
|
has many potential uses. |
56 |
|
|
Source contributions can be used as components in linear combination to |
57 |
greg |
1.1 |
reproduce any desired variation, e.g., simulating lighting controls or |
58 |
|
|
changing sky conditions via daylight coefficients. |
59 |
|
|
More generally, |
60 |
|
|
.I rtcontrib |
61 |
greg |
1.3 |
can be used to compute arbitrary input-output relationships in optical |
62 |
|
|
systems, such as luminaires, light pipes, and shading devices. |
63 |
greg |
1.1 |
.PP |
64 |
greg |
1.2 |
.I Rtcontrib |
65 |
|
|
calls |
66 |
|
|
.I rtrace(1) |
67 |
greg |
1.5 |
with the -oTW option to calculate the daughter ray |
68 |
|
|
contributions for each input ray, and the output tallies |
69 |
greg |
1.7 |
are sent to one or more destinations according to the given |
70 |
greg |
1.1 |
.I \-o |
71 |
|
|
specification. |
72 |
greg |
1.7 |
If a destination begins with an exclamation mark ('!'), then |
73 |
|
|
a pipe is opened to a command and data is sent to its standard input. |
74 |
|
|
Otherwise, the destination is treated as a file. |
75 |
greg |
1.8 |
An existing file of the same name is clobbered, unless the |
76 |
|
|
.I \-r |
77 |
|
|
option is specified, in which case data recovery is attempted. |
78 |
greg |
1.2 |
If an output specification contains a "%s" format, this will be |
79 |
greg |
1.1 |
replaced by the modifier name. |
80 |
|
|
The |
81 |
|
|
.I \-b |
82 |
|
|
option may be used to further define |
83 |
greg |
1.2 |
a "bin number" within each object if finer resolution is needed, and |
84 |
|
|
this will be applied to a "%d" format in the output file |
85 |
greg |
1.1 |
specification if present. |
86 |
greg |
1.3 |
The actual bin number is computed at run time based on ray direction |
87 |
|
|
and surface intersection, as described below. |
88 |
greg |
1.1 |
The most recent |
89 |
|
|
.I \-b |
90 |
|
|
and |
91 |
|
|
.I \-o |
92 |
greg |
1.2 |
options to the left of each |
93 |
greg |
1.1 |
.I \-m |
94 |
greg |
1.2 |
setting affect only that modifier. |
95 |
|
|
(The ordering of other options is unimportant.)\0 |
96 |
greg |
1.1 |
.PP |
97 |
greg |
1.2 |
If a |
98 |
|
|
.I \-b |
99 |
|
|
expression is defined for a particular modifier, |
100 |
|
|
the bin number will be evaluated at run time for each |
101 |
|
|
ray contribution from |
102 |
|
|
.I rtrace. |
103 |
|
|
Specifically, each ray's world intersection point will be assigned to |
104 |
|
|
the variables Px, Py, and Pz, and the normalized ray direction |
105 |
|
|
will be assigned to Dx, Dy, and Dz. |
106 |
|
|
These parameters may be combined with definitions given in |
107 |
|
|
.I \-e |
108 |
greg |
1.3 |
arguments and files read using the |
109 |
greg |
1.2 |
.I \-f |
110 |
greg |
1.3 |
option. |
111 |
|
|
The computed bin value will be |
112 |
greg |
1.2 |
rounded to the nearest whole number. |
113 |
|
|
This mechanism allows the user to define precise regions or directions |
114 |
|
|
they wish to accumulate, such as the Tregenza sky discretization, |
115 |
|
|
which would be otherwise impossible to specify |
116 |
|
|
as a set of RADIANCE primitives. |
117 |
greg |
1.3 |
The rules and predefined functions available for these expressions are |
118 |
|
|
described in the |
119 |
|
|
.I rcalc(1) |
120 |
|
|
man page. |
121 |
greg |
1.6 |
Unlike |
122 |
|
|
.I rcalc, |
123 |
|
|
.I rtcontrib |
124 |
|
|
will search the RADIANCE library directories for each file given in a |
125 |
|
|
.I \-f |
126 |
|
|
option. |
127 |
greg |
1.1 |
.PP |
128 |
|
|
If no |
129 |
|
|
.I \-o |
130 |
|
|
specification is given, results are written on the standard output in order |
131 |
|
|
of modifier (as given on the command line) then bin number. |
132 |
greg |
1.7 |
Concatenated data is also sent to a single destination (i.e., an initial |
133 |
greg |
1.2 |
.I \-o |
134 |
|
|
specification without formatting strings). |
135 |
greg |
1.1 |
If a "%s" format appears but no "%d" in the |
136 |
|
|
.I \-o |
137 |
|
|
specification, then each modifier will have its own output file, with |
138 |
|
|
multiple values per record in the case of a non-zero |
139 |
|
|
.I \-b |
140 |
|
|
definition. |
141 |
|
|
If a "%d" format appears but no "%s", then each bin will get its own |
142 |
|
|
output file, with modifiers output in order in each record. |
143 |
|
|
For text output, each RGB coefficient triple is separated by a tab, |
144 |
|
|
with a newline at the end of each ray record. |
145 |
|
|
For binary output formats, there is no such delimiter to mark |
146 |
|
|
the end of each record. |
147 |
|
|
.PP |
148 |
greg |
1.2 |
Input and output format defaults to plain text, where each ray's |
149 |
|
|
origin and direction (6 real values) are given on input, |
150 |
|
|
and one line is produced per output file per ray. |
151 |
|
|
Alternative data representations may be specified by the |
152 |
|
|
.I \-f[io] |
153 |
|
|
option, which is described in the |
154 |
|
|
.I rtrace |
155 |
|
|
man page along with the associated |
156 |
|
|
.I \-x |
157 |
|
|
and |
158 |
|
|
.I \-y |
159 |
|
|
resolution settings. |
160 |
|
|
In particular, the color ('c') output data representation |
161 |
|
|
together with positive dimensions for |
162 |
|
|
.I \-x |
163 |
|
|
and |
164 |
|
|
.I \-y |
165 |
|
|
will produce an uncompressed RADIANCE picture, |
166 |
|
|
suitable for manipulation with |
167 |
|
|
.I pcomb(1) |
168 |
|
|
and related tools. |
169 |
greg |
1.1 |
.PP |
170 |
|
|
If the |
171 |
|
|
.I \-n |
172 |
|
|
option is specified with a value greater than 1, multiple |
173 |
greg |
1.2 |
.I rtrace |
174 |
greg |
1.1 |
processes will be used to accelerate computation on a shared |
175 |
|
|
memory machine. |
176 |
|
|
Note that there is no benefit to using more processes |
177 |
greg |
1.2 |
than there are local CPUs available to do the work, and the |
178 |
|
|
.I rtcontrib |
179 |
|
|
process itself may use a considerable amount of CPU time. |
180 |
greg |
1.1 |
.PP |
181 |
|
|
Options may be given on the command line and/or read from the |
182 |
|
|
environment and/or read from a file. |
183 |
|
|
A command argument beginning with a dollar sign ('$') is immediately |
184 |
|
|
replaced by the contents of the given environment variable. |
185 |
|
|
A command argument beginning with an at sign ('@') is immediately |
186 |
|
|
replaced by the contents of the given file. |
187 |
greg |
1.2 |
.SH EXAMPLES |
188 |
|
|
To compute the proportional contributions from sources modified |
189 |
|
|
by "light1" vs. "light2" on a set of illuminance values: |
190 |
greg |
1.1 |
.IP "" .2i |
191 |
greg |
1.2 |
rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat |
192 |
|
|
.PP |
193 |
|
|
To generate a pair of images corresponding to these two lights' |
194 |
|
|
contributions: |
195 |
greg |
1.1 |
.IP "" .2i |
196 |
greg |
1.2 |
vwrays -ff -x 1024 -y 1024 -vf best.vf | |
197 |
|
|
rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf` |
198 |
|
|
@render.opt -o c_%s.pic -m light1 -m light2 scene.oct |
199 |
|
|
.PP |
200 |
|
|
These images may then be recombined using the desired outputs |
201 |
|
|
of light1 and light2: |
202 |
greg |
1.1 |
.IP "" .2i |
203 |
greg |
1.2 |
pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic |
204 |
greg |
1.1 |
.PP |
205 |
greg |
1.2 |
To compute an array of illuminance contributions according to a Tregenza sky: |
206 |
|
|
.IP "" .2i |
207 |
greg |
1.11 |
rtcontrib -I+ -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow |
208 |
greg |
1.2 |
@render.opt -f tregenza.cal scene.oct < test.dat |
209 |
greg |
1.6 |
.SH ENVIRONMENT |
210 |
greg |
1.10 |
RAYPATH path to search for -f and -M files |
211 |
greg |
1.1 |
.SH AUTHOR |
212 |
|
|
Greg Ward |
213 |
|
|
.SH "SEE ALSO" |
214 |
|
|
cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1), |
215 |
|
|
rcalc(1), rpict(1), rtrace(1), vwrays(1), ximage(1) |