man/man1/ies2rad.1

.\" RCSid "$Id$"
.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)
Revision:	1.5
Committed:	Mon Nov 29 16:07:36 2021 UTC (3 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad6R0, rad5R4, HEAD
Changes since 1.4:	+206 -200 lines
Log Message:	feat(ies2rad): changes and enhancements to ies2rad by Randolph Fritz
#	User	Rev	Content
1	greg	1.5	.\" RCSid "$Id$"
2			.TH IES2RAD "1" "2021-10-26" "Radiance" "Radiance Manual Pages"
3			.SH "NAME"
4			ies2rad \- convert IES luminaire data to RADIANCE description
5			.SH "SYNOPSIS"
6			\fBies2rad\fP [ \fIoptions\fP ] [ \fIfile file .\\|.\\|.\&\fP ]
7			.SH "DESCRIPTION"
8			\fIIes2rad\fP converts one or more IES luminaire data files to
9			an equivalent RADIANCE scene description. The light source geometry
10			will always be centered at the origin aimed in the negative Z
11			direction, with the 0 degree plane along the x-axis\(emthe IES
12			photometric horizontal or length. The IES width is oriented along
13			the y axis, and the IES up becomes the RADIANCE z-axis.
14			.PP
15			The IES(NA) LM-63 standard provides a limited range of light
16			source shapes (\(lqluminous openings\(rq), different in each
17			version of the standard. Of these shapes, \fIies2rad\fP supports
18			rectangles, boxes, points (as 1mm spheres), disks (as 1mm high
19			vertical cylinders), vertical cylinders, and spheres. Some versions
20			of the standard also define ellipses, ellipsoids, and horizontal
21			cylinders. \fIIes2rad\fP will approximate near-circular ellipses
22			as disks, near-spherical ellipsoids as spheres, and horizontal
23			cylinders as boxes.
24			.PP
25			The 1995 IES standard once included the materials and geometry
26			format (MGF) which can describe detailed luminaire and light
27			source geometry, but it was never used. \fIIes2rad\fP still supports
28			MGF.
29			.PP
30			\fIIes2rad\fP assigns light source colors based on information
31			in a lamp lookup table. Since most lamps are distinctly colored,
32	greg	1.1	it is often desirable to override this lookup procedure and use
33			a neutral value that will produced color-balanced renderings.
34	greg	1.5	In general, it is important to consider lamp color when an odd
35			assortment of fixture types is being used to illuminate the same
36			scene, and the rendering can always be balanced by \fBpfilt\fP(1)
37			to a specific white value later.
38			.SH "OPTIONS"
39			.TP
40			.BI "\-l" " libdir"
41			Set the library directory path to \fIlibdir\fP. This is where
42			all relative pathnames will begin for output file names. For
43			light sources that will be used by many people, this should be
44			set to some central location included in the RAYPATH environment
45			variable. The default is the current working directory.
46			.TP
47			.BI "\-p" " prefdir"
48			Set the library subdirectory path to \fIprefdir\fP. This is the
49			subdirectory from the library where all output files will be
50			placed. It is often most convenient to use a subdirectory for
51			the storage of light sources, since there tend to be many files
52			and placing them all in one directory is very messy. The default
53			value is the empty string.
54			.TP
55			.BI "\-o" " outname"
56			Set the output file name root to \fIoutname\fP. This overrides
57			the default output file name root which is the same as the input
58			file. This option may be used for only one input file, and is
59			required when reading data from the standard input.
60			.TP
61			.B "\-s"
62			Send the scene information to the standard output rather than
63			a separate file. This is appropriate when calling \fIies2rad\fP
64			from within a scene description via an inline command. The data
65			file(s) will still be written based on the output file name root,
66			but, since this information is unaffected by command line options,
67			it is safe to have multiple invocations of \fIies2rad\fP using
68			the same input file and different output options. The \fI\-s\fP
69	greg	1.1	option may be used for only one input file.
70			.TP
71	greg	1.5	.BI "\-d" " units"
72			Output dimensions are in \fIunits\fP, which is one of the letters
73			'm', 'c', 'f', or 'i' for meters, centimeters, feet or inches,
74			respectively. The letter specification may be followed by a slash
75			('/') and an optional divisor. For example, \fI\-dm/1000\fP would
76			be millimeters. The default output is in meters, regardless of
77			the original units in the IES input file. Note that there is
78			no space in this option.
79			.TP
80			.BI "\-i" " rad"
81			Ignore the crude geometry given by the IES input file and use
82			instead an illum sphere with radius \fIrad\fP. This option may
83			be useful when the user wishes to add a more accurate geometric
84			description to the light source model, though this need is obviated
85			by the recent LM-63-1995 specification, which uses MGF detail
86			geometry. (See \fI\-g\fP option below.)
87			.TP
88			.B "\-g"
89			If the IES file contains MGF detail geometry, compile this geometry
90			into a separate octree and create a single instance referencing
91			it instead of including the converted geometry directly in the
92			Radiance output file. This can result in a considerable memory
93			savings for luminaires which are later duplicated many times
94			in a scene, though the appearance may suffer for certain luminaires
95			since the enclosed glow sources will not light the local geometry
96			as they would otherwise.
97			.TP
98			.BI "\-f" " lampdat"
99			Use \fIlampdat\fP instead of the default lamp lookup table (lamp.tab)
100			to map lamp names to xy chromaticity and lumen depreciation data.
101	greg	1.1	It is often helpful to have customized lookup tables for specific
102			manufacturers and applications.
103			.TP
104	greg	1.5	.BI "\-t" " lamp"
105			Use the given lamp type for all input files. Normally, \fIies2rad\fP
106	greg	1.1	looks at the header lines of the IES file to try and determine
107	greg	1.5	what lamp is being used in the fixture. If any of the lines is
108			matched by a pattern in the lamp lookup table (see the \fB\-f\fP
109			option above), that color and depreciation factor will be used
110			instead of the default (see the \fB\-c\fP and \fB\-u\fP options).
111			The \fIlamp\fP specification is also looked up in the lamp table
112			unless it is set to \(lqdefault\(rq, in which case the default
113			color is used instead.
114			.TP
115			.BI "\-c" " red grn blu"
116			Use the given color if the type of the lamp is unknown or the
117			\fB\-t\fP option is set to \(lqdefault\(rq. If unspecified, the
118			default color will be white.
119			.TP
120			.BI "\-u" " lamp"
121			Set the default lamp color according to the entry for \fIlamp\fP
122			in the lookup table (see the \fB\-f\fP option). This is the color
123			that will be used if the input specification does not match any
124			lamp type patterns. This option is used instead of the \fB\-c\fP
125			option.
126			.TP
127			.BI "\-m" " factor"
128			Multiply all output quantities by \fIfactor\fP. This is the best
129			way to scale fixture brightness for different lamps, but care
130	greg	1.1	should be taken when this option is applied to multiple files.
131	greg	1.5	.SH "EXIT STATUS"
132			0 if successful, 1 if not.
133			.SH "ENVIRONMENT"
134			.TP
135			RAYPATH
136			Colon-separated list of directories to search for lamp lookup
137			table
138			.SH "FILES"
139			The output files will be created in the current directory (no
140			matter which directory the input files came from) unless the
141			\fI\-l\fP or \fI\-p\fP options are used.
142			.TP
143			.RI "<" "luminaire" ">.ies"
144			The IES LM-63 input file. May also be from the standard input.
145			If the standard input is the source, the \fB-o\fP option must
146			be specified, to provide a filename.
147			.TP
148			.RI "<" "luminaire" ">.rad"
149			The RADIANCE scene description. May also be sent to the standard
150			output.
151			.TP
152			.RI "<" "luminaire" ">.dat"
153			The IES candela values.
154			.TP
155			.RI "<" "luminaire" ">+.dat"
156			The IES tilt data. If tilt data is not provided (it is mostly
157			needed for luminaires which use metal halide lamps), this file
158			is not generated.
159			.TP
160			.RI "<" "luminaire" ">.oct"
161			If the \fB-g\fP option is given, the compiled MGF geometry is
162			placed in this octree file.
163			.TP
164			.RI "<" "RAYPATH" ">/lamp.tab"
165			lamp table
166			.SH "EXAMPLES"
167			To convert a single IES data file in inches with color balanced
168			output and 15% lumen depreciation, creating the files \(lqfluor01.rad\(rq
169			and \(lqfluor01.dat\(rq in the current directory:
170			.RS 2n
171			.sp 0.25
172			ies2rad -di -t default -m .85 fluor01.ies
173			.sp 0.25
174			.RE
175			.PP
176			To convert three IES files of various types to tenths of a foot
177			and put them in the library \(lq/usr/local/lib/ray\(rq subdirectory
178			\(lqsource/ies\(rq:
179			.RS 2n
180			.sp 0.25
181			ies2rad -df/10 -l /usr/local/lib/ray -p source/ies ies01 ies02 ies03
182			.sp 0.25
183			.RE
184	greg	1.1	.PP
185			To convert a single file and give the output a different name:
186	greg	1.5	.RS 2n
187			.sp 0.25
188			ies2rad -o fluorescent ies03
189			.sp 0.25
190			.RE
191			.SH "REFERENCES"
192			.TP
193			LM-63-86, LM-63-91, LM-63-95, LM-63-02, LM-63-19
194			\fIIES Standard File Format for the Electronic Transfer of Photometric
195			Data and Related Information\fP. IESNA - Lighting Measurement
196			and Testing. Illuminating Engineering Society, 1986, 1991, 1995,
197			2002, 2019.
198			.TP
199			LM-75-01
200			\fIGoniophotometer Types and Photometric Coordinates\fP. New
201			York: Illuminating Engineering Society of North America, 2001.
202			.TP
203			The Materials and Geometry Format
204			Greg Ward. \fIThe Materials and Geometry Format\fP <https://floyd.lbl.gov/mgf/mgfdoc.pdf>.
205			Lawrence Berkeley Laboratory, 1996.
206			.SH "AUTHOR"
207	greg	1.1	Greg Ward
208	greg	1.5	.SH "BUGS"
209			In pre-1991 standard IES files, all header lines will be examined
210			for a lamp table string match. In post-1991 standard files, only
211			those lamps with the [LAMP] or [LAMPCAT] keywords will be searched.
212			The first match found in the file is always the one used. This
213			method of assigning colors to fixtures is less than perfect,
214	greg	1.1	and the IES would do well to include explicit spectral information
215			somehow in their specification.
216			.PP
217	greg	1.5	Not all luminous openings defined in the IES standard are supported.
218			So far, however, we have yet to find IES files which use the
219			unsupported shapes.
220	greg	1.1	.SH "SEE ALSO"
221	greg	1.5	\fBlamp.tab\fP(5), \fBmgf2rad\fP(1), \fBoconv\fP(1), \fBpfilt\fP(1),
222			\fBrad2mgf\fP(1), \fBrpict\fP(1), \fBxform\fP(1)