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 (2 years, 6 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, HEAD
Changes since 1.4:	+206 -200 lines
Log Message:	feat(ies2rad): changes and enhancements to ies2rad by Randolph Fritz
#	Content
1	.\" 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	it is often desirable to override this lookup procedure and use
33	a neutral value that will produced color-balanced renderings.
34	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	option may be used for only one input file.
70	.TP
71	.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	It is often helpful to have customized lookup tables for specific
102	manufacturers and applications.
103	.TP
104	.BI "\-t" " lamp"
105	Use the given lamp type for all input files. Normally, \fIies2rad\fP
106	looks at the header lines of the IES file to try and determine
107	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	should be taken when this option is applied to multiple files.
131	.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	.PP
185	To convert a single file and give the output a different name:
186	.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 Ward
208	.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	and the IES would do well to include explicit spectral information
215	somehow in their specification.
216	.PP
217	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	.SH "SEE ALSO"
221	\fBlamp.tab\fP(5), \fBmgf2rad\fP(1), \fBoconv\fP(1), \fBpfilt\fP(1),
222	\fBrad2mgf\fP(1), \fBrpict\fP(1), \fBxform\fP(1)