man/man1/mkillum.1

.\" RCSid "$Id: mkillum.1,v 1.4 2004/09/17 21:43:49 greg Exp $"
.TH MKILLUM 1 10/6/95 RADIANCE
.SH NAME
mkillum - compute illum sources for a RADIANCE scene
.SH SYNOPSIS
.B mkillum
[
.B "\-n nprocs"
][
.B "rtrace options"
]
.B octree
.B "[ \< file .. ]"
.br
.B "mkillum [ rtrace options ] \-defaults"
.SH DESCRIPTION
.I Mkillum
takes a prepared RADIANCE scene description and an octree and computes
light source distributions for each surface, replacing them with
secondary sources whose contributions can be computed more efficiently by
.I rpict(1)
and
.I rvu(1).
This type of optimization is most useful for windows and skylights which
represent concentrated sources of indirect illumination.
.I Mkillum
is not appropriate for very large sources or sources with highly
directional distributions.
These are best handled respectively by the ambient calculation
and the secondary source types in RADIANCE.
.PP
If the
.I \-n
option is specified with a value greater than 1, multiple
.I rtrace(1)
processes will be used to accelerate computation on a shared
memory machine.
Note that there is no benefit to using more processes
than there are local CPUs available to do the work.
.PP
Remaining arguments to
.I mkillum
are passed directly to
.I rtrace(1),
which is used to compute the light distributions for the input surfaces.
These surfaces can be any combination of polygons, spheres and rings.
Other surfaces may be included, but
.I mkillum
cannot compute their distributions.
.PP
By default,
.I mkillum
reads from its standard input and writes to its standard output.
It is possible to specify multiple input files in a somewhat
unconventional fashion by placing a lesser-than symbol ('<') before
the file names.
(Note that this character must be escaped from most shells.)
This is necessary so
.I mkillum
can tell where the arguments to
.I rtrace(1)
end and its own input files begin.
.SH VARIABLES
.I Mkillum
has a number of parameters that can be changed by
comments in the input file of the form:
.nf

        #@mkillum variable=value option switch{+|-} ..

.fi
String or integer variables are separated from their values by the
equals sign ('=').
Options appear by themselves.
Switches are followed either by a
plus sign to turn them on or a minus sign to turn them off.
.PP
Parameters are usually changed many times within the
same input file to tailor the calculation, specify different
labels and so on.
The parameters and their meanings are described below.
.TP 10n
.BI o =string
Set the output file to
.I string.
All subsequent scene data will be sent to this file.
If this appears in the first comment in the input, nothing will be
sent to the standard output.
Note that this is not recommended when running
.I mkillum
from
.I rad(1),
which expects the output to be on the standard output.
.TP
.BI m =string
Set the material identifier to
.I string.
This name will be used not only as the new surface modifier, but it
will also be used to name the distribution pattern and the data files.
The distribution name will be
.I string
plus the suffix ".dist".
The data file will be named
.I string
plus possibly an integer plus a ".dat" suffix.
The integer is used to avoid accidently writing over an existing
file.
If overwriting the file is desired, use the
.I f
variable below.
.TP
.BI f =string
Set the data file name to
.I string.
The next data file will be given this name plus a ".dat" suffix.
Subsequent files will be named
.I string
plus an integer plus the ".dat" suffix.
An existing file with the same name will be clobbered.
This variable may be unset by leaving off the value.
(See also the
.I m
variable above.)
.TP
.BR a
Produce secondary sources for all of the surfaces in the input.
This is the default.
.TP
.BI e =string
Produce secondary sources for all surfaces except those modified by
.I string.
Surfaces modified by
.I string
will be passed to the output unchanged.
.TP
.BI i =string
Only produce secondary sources for surfaces modified by
.I string.
.TP
.BR n
Do not produce any secondary sources.
All input will be passed to the output unaffected.
.TP
.BI b =real
Do not produce a secondary source for a surface if its average
brightness (radiance) is less than the value
.I real.
.TP
.BI c ={d|a|n}
Use color information according to the given character.
If the character is
.I d,
then color information will be used in three separate data files and
the distribution will be fully characterized in terms of color.
If the character is
.I a,
then only the average color is computed and the distribution will
not contain color information.
If the character is
.I n,
even the average distribution color will be thrown away,
producing secondary sources that are completely uncolored.
This may be desirable from a color-balancing point of view.
.TP
.BI d =integer
Set the number of direction samples per projected steradian to
.I integer.
The number of directions stored in the associated data file will be
approximately this number multiplied by pi for polygons and rings, and
by 4pi for spheres.
If
.I integer
is zero, then a diffuse source is assumed and no distribution is
created.
.TP
.BI s =integer
Set the number of ray samples per direction to
.I integer.
This variable affects the accuracy of the distribution value for
each direction as well as the computation time for
.I mkillum.
.TP
.BR l{+|-}
Switch between light sources and illum sources.
If this switch is enabled
.I (l+),
.I mkillum
will use the material type "light" to represent surfaces.
If disabled
.I (l-),
.I mkillum
will use the material type "illum" with the input surface modifier
as its alternate material.
The default is
.I l-.
.SH EXAMPLES
The following command generates illum's corresponding to geometry
in the files "it1.rad" and "it2.rad":
.IP "" .3i
mkillum -ab 2 -ad 1024 -av .1 .1 .1 basic.oct "<" it1.rad it2.rad > illums.rad
.PP
The output file "illums.rad" would then be combined with the original
scene geometry to create a more easily rendered composite.
.SH AUTHOR
Greg Ward
.SH ACKNOWLEDGEMENT
Work on this program was initiated and sponsored by the LESO
group at EPFL in Switzerland.
.SH "SEE ALSO"
oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)
Revision:	1.5
Committed:	Tue Feb 22 16:10:43 2005 UTC (19 years, 2 months ago) by greg
Branch:	MAIN
CVS Tags:	rad3R7P2, rad3R7P1, rad3R8
Changes since 1.4:	+9 -1 lines
Log Message:	Added example with multiple input files
#	Content
1	.\" RCSid "$Id: mkillum.1,v 1.4 2004/09/17 21:43:49 greg Exp $"
2	.TH MKILLUM 1 10/6/95 RADIANCE
3	.SH NAME
4	mkillum - compute illum sources for a RADIANCE scene
5	.SH SYNOPSIS
6	.B mkillum
7	[
8	.B "\-n nprocs"
9	][
10	.B "rtrace options"
11	]
12	.B octree
13	.B "[ \< file .. ]"
14	.br
15	.B "mkillum [ rtrace options ] \-defaults"
16	.SH DESCRIPTION
17	.I Mkillum
18	takes a prepared RADIANCE scene description and an octree and computes
19	light source distributions for each surface, replacing them with
20	secondary sources whose contributions can be computed more efficiently by
21	.I rpict(1)
22	and
23	.I rvu(1).
24	This type of optimization is most useful for windows and skylights which
25	represent concentrated sources of indirect illumination.
26	.I Mkillum
27	is not appropriate for very large sources or sources with highly
28	directional distributions.
29	These are best handled respectively by the ambient calculation
30	and the secondary source types in RADIANCE.
31	.PP
32	If the
33	.I \-n
34	option is specified with a value greater than 1, multiple
35	.I rtrace(1)
36	processes will be used to accelerate computation on a shared
37	memory machine.
38	Note that there is no benefit to using more processes
39	than there are local CPUs available to do the work.
40	.PP
41	Remaining arguments to
42	.I mkillum
43	are passed directly to
44	.I rtrace(1),
45	which is used to compute the light distributions for the input surfaces.
46	These surfaces can be any combination of polygons, spheres and rings.
47	Other surfaces may be included, but
48	.I mkillum
49	cannot compute their distributions.
50	.PP
51	By default,
52	.I mkillum
53	reads from its standard input and writes to its standard output.
54	It is possible to specify multiple input files in a somewhat
55	unconventional fashion by placing a lesser-than symbol ('<') before
56	the file names.
57	(Note that this character must be escaped from most shells.)
58	This is necessary so
59	.I mkillum
60	can tell where the arguments to
61	.I rtrace(1)
62	end and its own input files begin.
63	.SH VARIABLES
64	.I Mkillum
65	has a number of parameters that can be changed by
66	comments in the input file of the form:
67	.nf
68
69	#@mkillum variable=value option switch{+\|-} ..
70
71	.fi
72	String or integer variables are separated from their values by the
73	equals sign ('=').
74	Options appear by themselves.
75	Switches are followed either by a
76	plus sign to turn them on or a minus sign to turn them off.
77	.PP
78	Parameters are usually changed many times within the
79	same input file to tailor the calculation, specify different
80	labels and so on.
81	The parameters and their meanings are described below.
82	.TP 10n
83	.BI o =string
84	Set the output file to
85	.I string.
86	All subsequent scene data will be sent to this file.
87	If this appears in the first comment in the input, nothing will be
88	sent to the standard output.
89	Note that this is not recommended when running
90	.I mkillum
91	from
92	.I rad(1),
93	which expects the output to be on the standard output.
94	.TP
95	.BI m =string
96	Set the material identifier to
97	.I string.
98	This name will be used not only as the new surface modifier, but it
99	will also be used to name the distribution pattern and the data files.
100	The distribution name will be
101	.I string
102	plus the suffix ".dist".
103	The data file will be named
104	.I string
105	plus possibly an integer plus a ".dat" suffix.
106	The integer is used to avoid accidently writing over an existing
107	file.
108	If overwriting the file is desired, use the
109	.I f
110	variable below.
111	.TP
112	.BI f =string
113	Set the data file name to
114	.I string.
115	The next data file will be given this name plus a ".dat" suffix.
116	Subsequent files will be named
117	.I string
118	plus an integer plus the ".dat" suffix.
119	An existing file with the same name will be clobbered.
120	This variable may be unset by leaving off the value.
121	(See also the
122	.I m
123	variable above.)
124	.TP
125	.BR a
126	Produce secondary sources for all of the surfaces in the input.
127	This is the default.
128	.TP
129	.BI e =string
130	Produce secondary sources for all surfaces except those modified by
131	.I string.
132	Surfaces modified by
133	.I string
134	will be passed to the output unchanged.
135	.TP
136	.BI i =string
137	Only produce secondary sources for surfaces modified by
138	.I string.
139	.TP
140	.BR n
141	Do not produce any secondary sources.
142	All input will be passed to the output unaffected.
143	.TP
144	.BI b =real
145	Do not produce a secondary source for a surface if its average
146	brightness (radiance) is less than the value
147	.I real.
148	.TP
149	.BI c ={d\|a\|n}
150	Use color information according to the given character.
151	If the character is
152	.I d,
153	then color information will be used in three separate data files and
154	the distribution will be fully characterized in terms of color.
155	If the character is
156	.I a,
157	then only the average color is computed and the distribution will
158	not contain color information.
159	If the character is
160	.I n,
161	even the average distribution color will be thrown away,
162	producing secondary sources that are completely uncolored.
163	This may be desirable from a color-balancing point of view.
164	.TP
165	.BI d =integer
166	Set the number of direction samples per projected steradian to
167	.I integer.
168	The number of directions stored in the associated data file will be
169	approximately this number multiplied by pi for polygons and rings, and
170	by 4pi for spheres.
171	If
172	.I integer
173	is zero, then a diffuse source is assumed and no distribution is
174	created.
175	.TP
176	.BI s =integer
177	Set the number of ray samples per direction to
178	.I integer.
179	This variable affects the accuracy of the distribution value for
180	each direction as well as the computation time for
181	.I mkillum.
182	.TP
183	.BR l{+\|-}
184	Switch between light sources and illum sources.
185	If this switch is enabled
186	.I (l+),
187	.I mkillum
188	will use the material type "light" to represent surfaces.
189	If disabled
190	.I (l-),
191	.I mkillum
192	will use the material type "illum" with the input surface modifier
193	as its alternate material.
194	The default is
195	.I l-.
196	.SH EXAMPLES
197	The following command generates illum's corresponding to geometry
198	in the files "it1.rad" and "it2.rad":
199	.IP "" .3i
200	mkillum -ab 2 -ad 1024 -av .1 .1 .1 basic.oct "<" it1.rad it2.rad > illums.rad
201	.PP
202	The output file "illums.rad" would then be combined with the original
203	scene geometry to create a more easily rendered composite.
204	.SH AUTHOR
205	Greg Ward
206	.SH ACKNOWLEDGEMENT
207	Work on this program was initiated and sponsored by the LESO
208	group at EPFL in Switzerland.
209	.SH "SEE ALSO"
210	oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)