.\" RCSid "$Id: ies2rad.1,v 1.5 2021/11/29 16:07:36 greg Exp $"
.TH IES2RAD "1" "2021-10-26" "Radiance" "Radiance Manual Pages"
.SH "NAME"
ies2rad \- convert IES luminaire data to RADIANCE description
.SH "SYNOPSIS"
\fBies2rad\fP [ \fIoptions\fP ] [ \fIfile file .\|.\|.\&\fP ]
.SH "DESCRIPTION"
\fIIes2rad\fP converts one or more IES luminaire data files to
an 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\(emthe IES
photometric horizontal or length. The IES width is oriented along
the y axis, and the IES up becomes the RADIANCE z-axis.
.PP
The IES(NA) LM-63 standard provides a limited range of light
source shapes (\(lqluminous openings\(rq), different in each
version of the standard. Of these shapes, \fIies2rad\fP supports
rectangles, boxes, points (as 1mm spheres), disks (as 1mm high
vertical cylinders), vertical cylinders, and spheres. Some versions
of the standard also define ellipses, ellipsoids, and horizontal
cylinders. \fIIes2rad\fP will approximate near-circular ellipses
as disks, near-spherical ellipsoids as spheres, and horizontal
cylinders as boxes.
.PP
The 1995 IES standard once included the materials and geometry
format (MGF) which can describe detailed luminaire and light
source geometry, but it was never used. \fIIes2rad\fP still supports
MGF.
.PP
\fIIes2rad\fP 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 important 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 \fBpfilt\fP(1)
to a specific white value later.
.SH "OPTIONS"
.TP
.BI "\-l" " libdir"
Set the library directory path to \fIlibdir\fP. 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 environment
variable. The default is the current working directory.
.TP
.BI "\-p" " prefdir"
Set the library subdirectory path to \fIprefdir\fP. 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.
.TP
.BI "\-o" " outname"
Set the output file name root to \fIoutname\fP. 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.
.TP
.B "\-s"
Send the scene information to the standard output rather than
a separate file. This is appropriate when calling \fIies2rad\fP
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 command line options,
it is safe to have multiple invocations of \fIies2rad\fP using
the same input file and different output options. The \fI\-s\fP
option may be used for only one input file.
.TP
.BI "\-d" " units"
Output dimensions are in \fIunits\fP, which is one of the letters
'm', 'c', 'f', or 'i' for meters, centimeters, feet or inches,
respectively. The letter specification may be followed by a slash
('/') and an optional divisor. For example, \fI\-dm/1000\fP 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.
.TP
.BI "\-i" " rad"
Ignore the crude geometry given by the IES input file and use
instead an illum sphere with radius \fIrad\fP. 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 \fI\-g\fP option below.)
.TP
.B "\-g"
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.
.TP
.BI "\-f" " lampdat"
Use \fIlampdat\fP 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.
.TP
.BI "\-t" " lamp"
Use the given lamp type for all input files. Normally, \fIies2rad\fP
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 \fB\-f\fP
option above), that color and depreciation factor will be used
instead of the default (see the \fB\-c\fP and \fB\-u\fP options).
The \fIlamp\fP specification is also looked up in the lamp table
unless it is set to \(lqdefault\(rq, in which case the default
color is used instead.
.TP
.BI "\-c" " red grn blu"
Use the given color if the type of the lamp is unknown or the
\fB\-t\fP option is set to \(lqdefault\(rq. If unspecified, the
default color will be white.
.TP
.BI "\-u" " lamp"
Set the default lamp color according to the entry for \fIlamp\fP
in the lookup table (see the \fB\-f\fP 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 \fB\-c\fP
option.
.TP
.BI "\-m" " factor"
Multiply all output quantities by \fIfactor\fP. 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.
.SH "EXIT STATUS"
0 if successful, 1 if not.
.SH "ENVIRONMENT"
.TP
RAYPATH
Colon-separated list of directories to search for lamp lookup
table
.SH "FILES"
The output files will be created in the current directory (no
matter which directory the input files came from) unless the
\fI\-l\fP or \fI\-p\fP options are used.
.TP
.RI "<" "luminaire" ">.ies"
The IES LM-63 input file. May also be from the standard input.
If the standard input is the source, the \fB-o\fP option must
be specified, to provide a filename.
.TP
.RI "<" "luminaire" ">.rad"
The RADIANCE scene description. May also be sent to the standard
output.
.TP
.RI "<" "luminaire" ">.dat"
The IES candela values.
.TP
.RI "<" "luminaire" ">+.dat"
The IES tilt data. If tilt data is not provided (it is mostly
needed for luminaires which use metal halide lamps), this file
is not generated.
.TP
.RI "<" "luminaire" ">.oct"
If the \fB-g\fP option is given, the compiled MGF geometry is
placed in this octree file.
.TP
.RI "<" "RAYPATH" ">/lamp.tab"
lamp table
.SH "EXAMPLES"
To convert a single IES data file in inches with color balanced
output and 15% lumen depreciation, creating the files \(lqfluor01.rad\(rq
and \(lqfluor01.dat\(rq in the current directory:
.RS 2n
.sp 0.25
ies2rad -di -t default -m .85 fluor01.ies
.sp 0.25
.RE
.PP
To convert three IES files of various types to tenths of a foot
and put them in the library \(lq/usr/local/lib/ray\(rq subdirectory
\(lqsource/ies\(rq:
.RS 2n
.sp 0.25
ies2rad -df/10 -l /usr/local/lib/ray -p source/ies ies01 ies02 ies03
.sp 0.25
.RE
.PP
To convert a single file and give the output a different name:
.RS 2n
.sp 0.25
ies2rad -o fluorescent ies03
.sp 0.25
.RE
.SH "REFERENCES"
.TP
LM-63-86, LM-63-91, LM-63-95, LM-63-02, LM-63-19
\fIIES Standard File Format for the Electronic Transfer of Photometric
Data and Related Information\fP. IESNA - Lighting Measurement
and Testing. Illuminating Engineering Society, 1986, 1991, 1995,
2002, 2019.
.TP
LM-75-01
\fIGoniophotometer Types and Photometric Coordinates\fP. New
York: Illuminating Engineering Society of North America, 2001.
.TP
The Materials and Geometry Format
Greg Ward. \fIThe Materials and Geometry Format\fP <https://floyd.lbl.gov/mgf/mgfdoc.pdf>.
Lawrence Berkeley Laboratory, 1996.
.SH "AUTHOR"
Greg Ward
.SH "BUGS"
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 assigning colors to fixtures is less than perfect,
and the IES would do well to include explicit spectral information
somehow in their specification.
.PP
Not all luminous openings defined in the IES standard are supported.
So far, however, we have yet to find IES files which use the
unsupported shapes.
.SH "SEE ALSO"
\fBlamp.tab\fP(5), \fBmgf2rad\fP(1), \fBoconv\fP(1), \fBpfilt\fP(1),
\fBrad2mgf\fP(1), \fBrpict\fP(1), \fBxform\fP(1)