IES2RAD(1)                                                          IES2RAD(1)



NNAAMMEE
       ies2rad - convert IES luminaire data to RADIANCE description

SSYYNNOOPPSSIISS
       iieess22rraadd [ ooppttiioonnss ] [ iinnppuutt ....  ]

DDEESSCCRRIIPPTTIIOONN
       _I_e_s_2_r_a_d converts one or more IES luminaire data files to the equivalent
       RADIANCE scene description.  The light source geometry will  always  be
       centered  at  the  origin aimed in the negative z direction, with the 0
       degree plane along the x axis.  Usually, two output files will be  cre-
       ated  for  every  input file, one scene file (with a ".rad" suffix) and
       one data file (with a ".dat" suffix).  If the IES input  file  includes
       tilt  data, then another data file will be created (with a "+.dat" suf-
       fix).  If the _-_s option is used, the scene data will  be  sent  to  the
       standard  output  instead  of  being written to a file.  Since the data
       file does not change with other options to _i_e_s_2_r_a_d_, this  is  a  conve-
       nient  way to specify different lamp colors and multipliers inline in a
       scene description.  If the _-_g option is used, then an octree file  will
       be  created  (with  the ".oct" suffix).  The root portion of the output
       file names will be the same as the corresponding input file, unless the
       _-_o  option  is  used.   The output files will be created in the current
       directory (no matter which directory the input files came from)  unless
       the _-_l or _-_p options are used.

       _I_e_s_2_r_a_d  assigns  light  source  colors  based on information in a lamp
       lookup table.  Since most lamps are distinctly  colored,  it  is  often
       desirable  to  override  this  lookup procedure and use a neutral value
       that will produced color-balanced renderings.  In general, it is impor-
       tant  to consider lamp color when an odd assortment of fixture types is
       being used to illuminate the same scene, and the rendering  can  always
       be balanced by pfilt(1) to a specific white value later.

       --ll _l_i_b_d_i_r Set  the library directory path to _l_i_b_d_i_r_.  This is where all
                 relative pathnames will begin for  output  file  names.   For
                 light  sources  that will be used by many people, this should
                 be set to some central location included in the RAYPATH envi-
                 ronment  variable.  The default is the current working direc-
                 tory.

       --pp _p_r_e_f_d_i_r
                 Set the library subdirectory path to _p_r_e_f_d_i_r_.   This  is  the
                 subdirectory  from the library where all output files will be
                 placed.  It is often most convenient to  use  a  subdirectory
                 for the storage of light sources, since there tend to be many
                 files and placing them all in one directory  is  very  messy.
                 The default value is the empty string.

       --oo _o_u_t_n_a_m_e
                 Set the output file name root to _o_u_t_n_a_m_e_.  This overrides the
                 default output file name root which is the same as the  input
                 file.   This  option may be used for only one input file, and
                 is required when reading data from the standard input.

       --ss        Send the scene information to the standard output rather than
                 a  separate  file.   This is appropriate when calling _i_e_s_2_r_a_d
                 from within a scene description via an inline  command.   The
                 data  file(s)  will still be written based on the output file
                 name root, but since this information is unaffected  by  com-
                 mand line options, it is safe to have multiple invocations of
                 _i_e_s_2_r_a_d using  the  same  input  file  and  different  output
                 options.   The _-_s option may be used for only one input file.

       --dd_u_n_i_t_s   Output dimensions are in _u_n_i_t_s_, which is one of  the  letters
                 'm',  'c',  'f',  or  'i'  for  meters,  centimeters, feet or
                 inches, respectively.  The letter specification may  be  fol-
                 lowed by a slash ('/') and an optional divisor.  For example,
                 _-_d_m_/_1_0_0_0 would be millimeters.   The  default  output  is  in
                 meters,  regardless  of  the  original units in the IES input
                 file.  Note that there is no space in this option.

       --ii _r_a_d    Ignore the crude geometry given by the IES input file and use
                 instead  an illum sphere with radius _r_a_d_.  This option may be
                 useful when the user wishes to add a more accurate  geometric
                 description  to  the  light source model, though this need is
                 obviated by the recent LM-63-1995 specification,  which  uses
                 MGF detail geometry.  (See _-_g option below.)

       --gg        If  the  IES  file contains MGF detail geometry, compile this
                 geometry into a separate octree and create a single  instance
                 referencing  it  instead  of including the converted geometry
                 directly in the Radiance output file.  This can result  in  a
                 considerable  memory  savings  for luminaires which are later
                 duplicated many times in a scene, though the  appearance  may
                 suffer for certain luminaires since the enclosed glow sources
                 will not light the local geometry as they would otherwise.

       --ff _l_a_m_p_d_a_t
                 Use  _l_a_m_p_d_a_t  instead  of  the  default  lamp  lookup   table
                 (lamp.tab)  to  map  lamp  names to xy chromaticity and lumen
                 depreciation data.  It is often helpful  to  have  customized
                 lookup tables for specific manufacturers and applications.

       --tt _l_a_m_p   Use  the  given  lamp  type  for  all input files.  Normally,
                 _i_e_s_2_r_a_d looks at the header lines of the IES file to try  and
                 determine  what lamp is being used in the fixture.  If any of
                 the lines is matched by a pattern in the  lamp  lookup  table
                 (see the -f option above), that color and depreciation factor
                 will be used instead of  the  default  (see  the  -c  and  -u
                 options).   The  _l_a_m_p  specification is also looked up in the
                 lamp table unless it is set to "default", in which  case  the
                 default color is used instead.

       --cc _r_e_d _g_r_n _b_l_u
                 Use the given color if the type of the lamp is unknown or the
                 -t option is set to "default".  If unspecified,  the  default
                 color will be white.

       --uu _l_a_m_p   Set the default lamp color according to the entry for _l_a_m_p in
                 the lookup table (see the -f option).  This is the color that
                 will  be  used  if the input specification does not match any
                 lamp type patterns.  This option is used instead  of  the  -c
                 option.

       --mm _f_a_c_t_o_r Multiply  all  output quantities by _f_a_c_t_o_r_.  This is the best
                 way to scale fixture brightness for different lamps, but care
                 should  be  taken  when  this  option  is applied to multiple
                 files.

EEXXAAMMPPLLEE
       To convert a single IES data file in inches with color balanced  output
       and  15%  lumen  depreciation,  creating  the  files  "fluor01.rad" and
       "fluor01.dat" in the current directory:

         ies2rad -di -t default -m .85 fluor01.ies

       To convert three IES files of various types to tenths of a foot and put
       them in the library "/usr/local/lib/ray" subdirectory "source/ies":

         ies2rad -df/10 -l /usr/local/lib/ray -p source/ies ies01 ies02 ies03

       To convert a single file and give the output a different name:

         ies2rad -o fluorescent ies03

EENNVVIIRROONNMMEENNTT
       RAYPATH        directories to search for lamp lookup table

AAUUTTHHOORR
       Greg Ward

BBUUGGSS
       In pre-1991 standard IES files, all header lines will be examined for a
       lamp table string match.  In post-1991 standard files, only those lamps
       with  the  [LAMP]  or  [LAMPCAT]  keywords will be searched.  The first
       match found in the file is always the one used.  This method of assign-
       ing  colors to fixtures is less than perfect, and the IES would do well
       to include explicit spectral information somehow  in  their  specifica-
       tion.

       The IESNA LM-63 specification prior to 1995 provided three basic source
       shapes, rectangular, round,  and  elliptical.   The  details  of  these
       shapes  is vague at best.  Rectangular sources will always be rectangu-
       lar, but ies2rad will approximate round sources  as  spherical  if  the
       height  is close to or greater than the width and length, and as a ring
       otherwise.  Elliptical sources are treated the same as  round  sources.
       The  1995  standard  rectifies this problem by including detailed lumi-
       naire geometry as MGF data, though nothing  in  the  standard  requires
       manufacturers to provide this information.

SSEEEE AALLSSOO
       mgf2rad(1), oconv(1), pfilt(1), rad2mgf(1), rpict(1), xform(1)



RADIANCE                            6/14/96                         IES2RAD(1)
