MKILLUM(1)                                                          MKILLUM(1)



NNAAMMEE
       mkillum - compute illum sources for a RADIANCE scene

SSYYNNOOPPSSIISS
       mmkkiilllluumm [ --nn nnpprrooccss ][ rrttrraaccee ooppttiioonnss ] ooccttrreeee [[ << ffiillee .... ]]
       mmkkiilllluumm [[ rrttrraaccee ooppttiioonnss ]] --ddeeffaauullttss

DDEESSCCRRIIPPTTIIOONN
       _M_k_i_l_l_u_m  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 effi-
       ciently by _r_p_i_c_t_(_1_) and _r_v_u_(_1_)_.  This type of optimization is most use-
       ful  for  windows and skylights which represent concentrated sources of
       indirect illumination.  _M_k_i_l_l_u_m  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 _m_k_i_l_l_u_m are interpreted as rendering options for
       _r_t_r_a_c_e_(_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 _m_k_i_l_l_u_m cannot compute their dis-
       tributions.

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

VVAARRIIAABBLLEESS
       _M_k_i_l_l_u_m  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 fol-
       lowed 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 param-
       eters and their meanings are described below.

       oo_=_s_t_r_i_n_g  Set  the  output  file  to _s_t_r_i_n_g_.  All subsequent scene data
                 will be sent to this file.  If this appears in the first com-
                 ment  in the input, nothing will be sent to the standard out-
                 put.  Note that this is not recommended when running  _m_k_i_l_l_u_m
                 from  _r_a_d_(_1_)_,  which expects the output to be on the standard
                 output.

       mm_=_s_t_r_i_n_g  Set the material identifier to _s_t_r_i_n_g_.   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 _s_t_r_i_n_g plus the suffix ".dist".
                 The data file will be named _s_t_r_i_n_g plus possibly  an  integer
                 plus  a  ".dat"  suffix.   The integer is used to avoid acci-
                 dently writing over an existing  file.   If  overwriting  the
                 file is desired, use the _f variable below.

       ff_=_s_t_r_i_n_g  Set the data file name to _s_t_r_i_n_g_.  The next data file will be
                 given this name plus a ".dat" suffix.  Subsequent files  will
                 be  named  _s_t_r_i_n_g 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.)

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

       ee_=_s_t_r_i_n_g  Produce secondary sources for all surfaces except those modi-
                 fied by _s_t_r_i_n_g_.  Surfaces modified by _s_t_r_i_n_g will  be  passed
                 to the output unchanged.

       ii_=_s_t_r_i_n_g  Only  produce  secondary  sources  for  surfaces  modified by
                 _s_t_r_i_n_g_.

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

       bb_=_r_e_a_l    Do not produce a secondary source for a surface if its  aver-
                 age brightness (radiance) is less than the value _r_e_a_l_.

       cc_=_{_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.

       dd_=_i_n_t_e_g_e_r Set  the  number of direction samples per projected steradian
                 to _i_n_t_e_g_e_r_.  The number of directions stored in  the  associ-
                 ated  data  file will be approximately this number multiplied
                 by pi for polygons and rings, and by  4pi  for  spheres.   If
                 _i_n_t_e_g_e_r is zero, then a diffuse source is assumed and no dis-
                 tribution is created.

       dd_=_s_t_r_i_n_g  Set the surface Bidirectional Scattering  Distribution  Func-
                 tion  (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 spec-
                 ification 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 _u  setting,  described
                 below.   The  thickness of the surface may be controlled with
                 the _t setting.  If this variable has no setting or an integer
                 is specified, _m_k_i_l_l_u_m returns to the default behavior of com-
                 puting the output distribution directly.

       ss_=_i_n_t_e_g_e_r Set the number of ray samples per direction to _i_n_t_e_g_e_r_.  This
                 variable  affects  the accuracy of the distribution value for
                 each direction as well as the computation time for _m_k_i_l_l_u_m_.

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

       uu_=_[_+_|_-_]_{_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.

       tt_=_r_e_a_l    Set the surface thickness to _r_e_a_l 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.

EEXXAAMMPPLLEESS
       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.

EENNVVIIRROONNMMEENNTT
       RAYPATH        the directories to check for auxiliary files.

AAUUTTHHOORR
       Greg Ward

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

SSEEEE AALLSSOO
       oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)



RADIANCE                            10/6/95                         MKILLUM(1)
