man/man1/mkillum.1

.\" RCSid "$Id: mkillum.1,v 1.8 2008/04/18 00:39:24 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
ray tracing 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 interpreted as rendering options for
.I rtrace(1),
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 rendering arguments
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, except any
void surfaces will be removed.
.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 d =string
Set the surface Bidirectional Scattering Distribution Function (BSDF)
to the given file.
The RADIANCE library path will be searched if the file does not begin
with a '.' or '~' character.
This file must contain an LBNL Window 6 XML specification of a valid
BSDF for the given surface, and all rays will be interpreted through
this function.
The orientation of the BSDF may be controlled with the
.I u
setting, described below.
The thickness of the surface may be controlled with the
.I t
setting.
If this variable has no setting or an integer is specified,
.I mkillum
returns to the default behavior of computing the output distribution
directly.
.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-.
.TP
.BI u =[+|-]{X|Y|Z}
The given axis will be considered "up" for the purposes of interpreting
BSDF data specified with the
.I d
variable.
The BSDF will be reoriented relative to the surface as necessary to keep
the up vector in the vertical plane that contains this axis and the
surface normal, corresponding to an azimuth of 90 degrees.
The default up vector is +Z.
.TP
.BI t =real
Set the surface thickness to
.I real
in world coordinates.
This value is used for determining where to start rays that need to begin
on the opposite side of the surface, specifically to compute the incoming
distribution for a BSDF computation.
The default value is 0.
.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 ENVIRONMENT
RAYPATH         the directories to check for auxiliary files.
.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.9
Committed:	Mon Nov 10 19:08:17 2008 UTC (16 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R0
Changes since 1.8:	+5 -7 lines
Log Message:	Changed ".pic" extension to ".hdr" throughout
#	User	Rev	Content
1	greg	1.9	.\" RCSid "$Id: mkillum.1,v 1.8 2008/04/18 00:39:24 greg Exp $"
2	greg	1.1	.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	greg	1.4	.B "\-n nprocs"
9			][
10	greg	1.1	.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	greg	1.3	.I rvu(1).
24	greg	1.1	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	greg	1.4	If the
33			.I \-n
34			option is specified with a value greater than 1, multiple
35	greg	1.9	ray tracing processes will be used to accelerate computation on a shared
36	greg	1.4	memory machine.
37			Note that there is no benefit to using more processes
38			than there are local CPUs available to do the work.
39			.PP
40			Remaining arguments to
41	greg	1.1	.I mkillum
42	greg	1.9	are interpreted as rendering options for
43	greg	1.1	.I rtrace(1),
44	greg	1.9	to compute the light distributions for the input surfaces.
45	greg	1.1	These surfaces can be any combination of polygons, spheres and rings.
46			Other surfaces may be included, but
47			.I mkillum
48			cannot compute their distributions.
49			.PP
50			By default,
51			.I mkillum
52			reads from its standard input and writes to its standard output.
53			It is possible to specify multiple input files in a somewhat
54			unconventional fashion by placing a lesser-than symbol ('<') before
55			the file names.
56			(Note that this character must be escaped from most shells.)
57			This is necessary so
58			.I mkillum
59	greg	1.9	can tell where the rendering arguments
60	greg	1.1	end and its own input files begin.
61			.SH VARIABLES
62			.I Mkillum
63			has a number of parameters that can be changed by
64			comments in the input file of the form:
65			.nf
66
67			#@mkillum variable=value option switch{+\|-} ..
68
69			.fi
70			String or integer variables are separated from their values by the
71			equals sign ('=').
72			Options appear by themselves.
73			Switches are followed either by a
74			plus sign to turn them on or a minus sign to turn them off.
75			.PP
76			Parameters are usually changed many times within the
77			same input file to tailor the calculation, specify different
78			labels and so on.
79			The parameters and their meanings are described below.
80			.TP 10n
81			.BI o =string
82			Set the output file to
83			.I string.
84			All subsequent scene data will be sent to this file.
85			If this appears in the first comment in the input, nothing will be
86			sent to the standard output.
87			Note that this is not recommended when running
88			.I mkillum
89			from
90			.I rad(1),
91			which expects the output to be on the standard output.
92			.TP
93			.BI m =string
94			Set the material identifier to
95			.I string.
96			This name will be used not only as the new surface modifier, but it
97			will also be used to name the distribution pattern and the data files.
98			The distribution name will be
99			.I string
100			plus the suffix ".dist".
101			The data file will be named
102			.I string
103			plus possibly an integer plus a ".dat" suffix.
104			The integer is used to avoid accidently writing over an existing
105			file.
106			If overwriting the file is desired, use the
107			.I f
108			variable below.
109			.TP
110			.BI f =string
111			Set the data file name to
112			.I string.
113			The next data file will be given this name plus a ".dat" suffix.
114			Subsequent files will be named
115			.I string
116			plus an integer plus the ".dat" suffix.
117			An existing file with the same name will be clobbered.
118			This variable may be unset by leaving off the value.
119			(See also the
120			.I m
121			variable above.)
122			.TP
123			.BR a
124			Produce secondary sources for all of the surfaces in the input.
125			This is the default.
126			.TP
127			.BI e =string
128			Produce secondary sources for all surfaces except those modified by
129			.I string.
130			Surfaces modified by
131			.I string
132			will be passed to the output unchanged.
133			.TP
134			.BI i =string
135			Only produce secondary sources for surfaces modified by
136			.I string.
137			.TP
138			.BR n
139			Do not produce any secondary sources.
140	greg	1.7	All input will be passed to the output unaffected, except any
141			void surfaces will be removed.
142	greg	1.1	.TP
143			.BI b =real
144			Do not produce a secondary source for a surface if its average
145			brightness (radiance) is less than the value
146			.I real.
147			.TP
148			.BI c ={d\|a\|n}
149			Use color information according to the given character.
150			If the character is
151			.I d,
152			then color information will be used in three separate data files and
153			the distribution will be fully characterized in terms of color.
154			If the character is
155			.I a,
156			then only the average color is computed and the distribution will
157			not contain color information.
158			If the character is
159			.I n,
160			even the average distribution color will be thrown away,
161			producing secondary sources that are completely uncolored.
162			This may be desirable from a color-balancing point of view.
163			.TP
164			.BI d =integer
165			Set the number of direction samples per projected steradian to
166			.I integer.
167			The number of directions stored in the associated data file will be
168			approximately this number multiplied by pi for polygons and rings, and
169			by 4pi for spheres.
170			If
171			.I integer
172			is zero, then a diffuse source is assumed and no distribution is
173			created.
174			.TP
175	greg	1.7	.BI d =string
176			Set the surface Bidirectional Scattering Distribution Function (BSDF)
177			to the given file.
178			The RADIANCE library path will be searched if the file does not begin
179			with a '.' or '~' character.
180			This file must contain an LBNL Window 6 XML specification of a valid
181			BSDF for the given surface, and all rays will be interpreted through
182			this function.
183			The orientation of the BSDF may be controlled with the
184			.I u
185			setting, described below.
186			The thickness of the surface may be controlled with the
187			.I t
188			setting.
189			If this variable has no setting or an integer is specified,
190			.I mkillum
191			returns to the default behavior of computing the output distribution
192			directly.
193			.TP
194	greg	1.1	.BI s =integer
195			Set the number of ray samples per direction to
196			.I integer.
197			This variable affects the accuracy of the distribution value for
198			each direction as well as the computation time for
199			.I mkillum.
200			.TP
201			.BR l{+\|-}
202			Switch between light sources and illum sources.
203			If this switch is enabled
204			.I (l+),
205			.I mkillum
206			will use the material type "light" to represent surfaces.
207			If disabled
208			.I (l-),
209			.I mkillum
210			will use the material type "illum" with the input surface modifier
211			as its alternate material.
212			The default is
213			.I l-.
214	greg	1.7	.TP
215			.BI u =[+\|-]{X\|Y\|Z}
216			The given axis will be considered "up" for the purposes of interpreting
217			BSDF data specified with the
218			.I d
219			variable.
220			The BSDF will be reoriented relative to the surface as necessary to keep
221			the up vector in the vertical plane that contains this axis and the
222	greg	1.8	surface normal, corresponding to an azimuth of 90 degrees.
223			The default up vector is +Z.
224	greg	1.7	.TP
225			.BI t =real
226			Set the surface thickness to
227			.I real
228			in world coordinates.
229			This value is used for determining where to start rays that need to begin
230			on the opposite side of the surface, specifically to compute the incoming
231			distribution for a BSDF computation.
232			The default value is 0.
233	greg	1.5	.SH EXAMPLES
234			The following command generates illum's corresponding to geometry
235			in the files "it1.rad" and "it2.rad":
236			.IP "" .3i
237	greg	1.6	mkillum \-ab 2 \-ad 1024 \-av .1 .1 .1 basic.oct "<" it1.rad it2.rad > illums.rad
238	greg	1.5	.PP
239			The output file "illums.rad" would then be combined with the original
240			scene geometry to create a more easily rendered composite.
241	greg	1.7	.SH ENVIRONMENT
242			RAYPATH the directories to check for auxiliary files.
243	greg	1.1	.SH AUTHOR
244			Greg Ward
245			.SH ACKNOWLEDGEMENT
246			Work on this program was initiated and sponsored by the LESO
247			group at EPFL in Switzerland.
248			.SH "SEE ALSO"
249	greg	1.3	oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)