man/man1/mkillum.1

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