Ubuntu Manpage: mkillum - compute illum sources for a RADIANCE scene

Provided by: radiance_4R1+20120125-1.1_amd64

NAME

       mkillum - compute illum sources for a RADIANCE scene

SYNOPSIS

       mkillum [ -n nprocs ][ rtrace options ] octree [ < file .. ]
       mkillum [ rtrace options ] -defaults

DESCRIPTION

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 rpict(1) and rvu(1). This type of
optimization is most useful for windows and skylights which represent concentrated sources
of indirect illumination. 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.

If the -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.

Remaining arguments to mkillum are interpreted as rendering options for 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 mkillum
cannot compute their distributions.

By default, 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 mkillum can tell where the rendering
arguments end and its own input files begin.

VARIABLES

Mkillum has a number of parameters that can be changed by comments in the input file of
the form:

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

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.

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.

o=string Set the output file to 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 mkillum
from rad(1), which expects the output to be on the standard output.

m=string Set the material identifier to 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 string plus the suffix
".dist". The data file will be named 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 f variable below.

f=string Set the data file name to string. The next data file will be given this name
plus a ".dat" suffix. Subsequent files will be named 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 m variable
above.)

a Produce secondary sources for all of the surfaces in the input. This is the
default.

e=string Produce secondary sources for all surfaces except those modified by string.
Surfaces modified by string will be passed to the output unchanged.

i=string Only produce secondary sources for surfaces modified by string.

n Do not produce any secondary sources. All input will be passed to the output
unaffected, except any void surfaces will be removed.

b=real Do not produce a secondary source for a surface if its average brightness
(radiance) is less than the value real.

c={d|a|n} Use color information according to the given character. If the character is 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
a, then only the average color is computed and the distribution will not contain
color information. If the character is 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.

d=integer Set the number of direction samples per projected steradian to 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
integer is zero, then a diffuse source is assumed and no distribution is
created.

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, which may be produced by the Radiance
genBSDF(1) program. The orientation of the BSDF may be controlled with the u
setting, described below. If this variable has no setting or an integer is
specified, mkillum returns to the default behavior of computing the output
distribution directly.

s=integer Set the number of ray samples per direction to integer. This variable affects
the accuracy of the distribution value for each direction as well as the
computation time for mkillum.

l{+|-} Switch between light sources and illum sources. If this switch is enabled (l+),
mkillum will use the material type "light" to represent surfaces. If disabled
(l-), mkillum will use the material type "illum" with the input surface modifier
as its alternate material. The default is l-.

u=[+|-]{X|Y|Z}
The given axis will be considered "up" for the purposes of interpreting BSDF
data specified with the 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.

t=real Set the surface thickness to real in world coordinates. This value is used for
determining where to start rays that need to begin on the opposite side of a
fenestration system, specifically to compute the incoming distribution for a
BSDF computation. If the thickness is set to 0 and a BSDF contains detailed
geometry, it will be translated and output as part of the new description,
provided the l- option is also in effect. (This currently works only for
rectangular polygons.) The default thickness is 0.

EXAMPLES

       The following command generates illum's corresponding to geometry in the  files  "it1.rad"
       and "it2.rad":

          mkillum -ab 2 -ad 1024 -av .1 .1 .1 basic.oct "<" it1.rad it2.rad > illums.rad

       The  output  file  "illums.rad" would then be combined with the original scene geometry to
       create a more easily rendered composite.

ENVIRONMENT

       RAYPATH        the directories to check for auxiliary files.

AUTHOR

       Greg Ward

ACKNOWLEDGEMENT

       Work on this program was initiated and sponsored by the LESO group at EPFL in Switzerland.