man/man1/ies2rad.1

.\" RCSid "$Id: ies2rad.1,v 1.3 2007/09/04 17:36:40 greg Exp $"
.TH IES2RAD 1 6/14/96 RADIANCE
.SH NAME
ies2rad - convert IES luminaire data to RADIANCE description
.SH SYNOPSIS
.B ies2rad
[
.B options
]
[
.B input ..
]
.SH DESCRIPTION
.I Ies2rad
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.
(Note, this means that the IES "width" is actually along the Y axis,
while "length" corresponds to the X axis.)\0
Usually, two output files will be created 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" suffix).
If the
.I \-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 ies2rad,
this is a convenient way to specify different lamp colors and
multipliers inline in a scene description.
If the
.I \-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
.I \-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
.I \-l
or
.I \-p
options are used.
.PP
.I Ies2rad
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 pfilt(1) to a specific white value
later.
.TP 10n
.BI -l \ libdir
Set the library directory path to
.I libdir.
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
.I prefdir.
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
.I outname.
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
.BR -s
Send the scene information to the standard output rather than a
separate file.
This is appropriate when calling
.I ies2rad
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
.I ies2rad
using the same input file and different output options.
The
.I \-s
option may be used for only one input file.
.TP
.BI -d units
Output dimensions are in
.I units,
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,
.I \-dm/1000
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
.I rad.
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
.I \-g
option below.)\0
.TP
.BR -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
.I lampdat
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,
.I ies2rad
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
.I lamp
specification is also looked up in the lamp table unless it is
set to "default", 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 \-t option is set to "default".
If unspecified, the default color will be white.
.TP
.BI \-u \ lamp
Set the default lamp color according to the entry for
.I lamp
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.
.TP
.BI \-m \ factor
Multiply all output quantities by
.I factor.
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 EXAMPLE
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:
.IP "" .2i
ies2rad \-di \-t default \-m .85 fluor01.ies
.PP
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":
.IP "" .2i
ies2rad \-df/10 \-l /usr/local/lib/ray \-p source/ies ies01 ies02 ies03
.PP
To convert a single file and give the output a different name:
.IP "" .2i
ies2rad \-o fluorescent ies03
.SH ENVIRONMENT
RAYPATH         directories to search for lamp lookup table
.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
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 rectangular, 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
luminaire geometry as MGF data, though nothing in the standard
requires manufacturers to provide this information.
.SH "SEE ALSO"
mgf2rad(1), oconv(1), pfilt(1), rad2mgf(1), rpict(1), xform(1)
Revision:	1.4
Committed:	Thu Jan 24 23:15:46 2008 UTC (17 years, 9 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R2, rad5R3, rad5R0, rad5R1, rad4R2, rad4R1, rad4R0, rad3R9, rad4R2P1, rad4R2P2
Changes since 1.3:	+4 -2 lines
Log Message:	Fixed reversed orientation for anisotropic distrubutions
#	User	Rev	Content
1	greg	1.4	.\" RCSid "$Id: ies2rad.1,v 1.3 2007/09/04 17:36:40 greg Exp $"
2	greg	1.1	.TH IES2RAD 1 6/14/96 RADIANCE
3			.SH NAME
4			ies2rad - convert IES luminaire data to RADIANCE description
5			.SH SYNOPSIS
6			.B ies2rad
7			[
8			.B options
9			]
10			[
11			.B input ..
12			]
13			.SH DESCRIPTION
14			.I Ies2rad
15			converts one or more IES luminaire data files to the equivalent RADIANCE
16			scene description.
17			The light source geometry will always be centered at the origin aimed
18	greg	1.4	in the negative Z direction, with the 0 degree plane along the X axis.
19			(Note, this means that the IES "width" is actually along the Y axis,
20			while "length" corresponds to the X axis.)\0
21	greg	1.1	Usually, two output files will be created for every input file, one
22			scene file (with a ".rad" suffix) and one data file (with a ".dat"
23			suffix).
24			If the IES input file includes tilt data, then another data file
25			will be created (with a "+.dat" suffix).
26			If the
27			.I \-s
28			option is used, the scene data will be sent to the standard output
29			instead of being written to a file.
30			Since the data file does not change with other options to
31			.I ies2rad,
32			this is a convenient way to specify different lamp colors and
33			multipliers inline in a scene description.
34			If the
35			.I \-g
36			option is used, then an octree file will be created (with the ".oct"
37			suffix).
38			The root portion of the output file names will be the same as the
39			corresponding input file, unless the
40			.I \-o
41			option is used.
42			The output files will be created in the current directory (no matter
43			which directory the input files came from) unless the
44			.I \-l
45			or
46			.I \-p
47			options are used.
48			.PP
49			.I Ies2rad
50			assigns light source colors based on information in a lamp lookup table.
51			Since most lamps are distinctly colored,
52			it is often desirable to override this lookup procedure and use
53			a neutral value that will produced color-balanced renderings.
54			In general, it is important to consider lamp color when an odd assortment
55			of fixture types is being used to illuminate the same scene, and
56			the rendering can always be balanced by pfilt(1) to a specific white value
57			later.
58			.TP 10n
59			.BI -l \ libdir
60			Set the library directory path to
61			.I libdir.
62			This is where all relative pathnames will begin for output file names.
63			For light sources that will be used by many people, this should be
64			set to some central location included in the RAYPATH environment variable.
65			The default is the current working directory.
66			.TP
67			.BI -p \ prefdir
68			Set the library subdirectory path to
69			.I prefdir.
70			This is the subdirectory from the library where all output files will
71			be placed.
72			It is often most convenient to use a subdirectory for the storage of
73			light sources, since there tend to be many files and placing them all
74			in one directory is very messy.
75			The default value is the empty string.
76			.TP
77			.BI -o \ outname
78			Set the output file name root to
79			.I outname.
80			This overrides the default output file name root which is the same as the
81			input file.
82			This option may be used for only one input file, and is required when
83			reading data from the standard input.
84			.TP
85			.BR -s
86			Send the scene information to the standard output rather than a
87			separate file.
88			This is appropriate when calling
89			.I ies2rad
90			from within a scene description via an inline command.
91			The data file(s) will still be written based on the output file name
92			root, but since this information is unaffected by command line options,
93			it is safe to have multiple invocations of
94			.I ies2rad
95			using the same input file and different output options.
96			The
97			.I \-s
98			option may be used for only one input file.
99			.TP
100			.BI -d units
101			Output dimensions are in
102			.I units,
103			which is one of the letters 'm', 'c', 'f', or 'i' for meters,
104			centimeters, feet or inches, respectively.
105			The letter specification may be followed by a slash ('/') and an
106			optional divisor.
107			For example,
108			.I \-dm/1000
109			would be millimeters.
110			The default output is in meters, regardless of the original units in
111			the IES input file.
112			Note that there is no space in this option.
113			.TP
114			.BI -i \ rad
115			Ignore the crude geometry given by the IES input file and use instead an illum
116			sphere with radius
117			.I rad.
118			This option may be useful when the user wishes to add a more accurate
119			geometric description to the light source model, though this need
120			is obviated by the recent LM-63-1995 specification, which uses MGF
121			detail geometry.
122			(See
123			.I \-g
124			option below.)\0
125			.TP
126			.BR -g
127			If the IES file contains MGF detail geometry, compile this geometry into
128			a separate octree and create a single instance referencing it
129			instead of including the converted geometry directly in the Radiance
130			output file.
131			This can result in a considerable memory savings for luminaires
132			which are later duplicated many times in a scene, though the
133			appearance may suffer for certain luminaires since the enclosed glow
134			sources will not light the local geometry as they would otherwise.
135			.TP
136			.BI -f \ lampdat
137			Use
138			.I lampdat
139			instead of the default lamp lookup table (lamp.tab) to map lamp
140			names to xy chromaticity and lumen depreciation data.
141			It is often helpful to have customized lookup tables for specific
142			manufacturers and applications.
143			.TP
144			.BI -t \ lamp
145			Use the given lamp type for all input files.
146			Normally,
147			.I ies2rad
148			looks at the header lines of the IES file to try and determine
149			what lamp is being used in the fixture.
150			If any of the lines is matched by a pattern in the lamp lookup
151	greg	1.3	table (see the \-f option above), that color and depreciation factor will
152			be used instead of the default (see the \-c and \-u options).
153	greg	1.1	The
154			.I lamp
155			specification is also looked up in the lamp table unless it is
156			set to "default", in which case the default color is used instead.
157			.TP
158	greg	1.3	.BI \-c " red grn blu"
159	greg	1.1	Use the given color if the type of the lamp is unknown or
160	greg	1.3	the \-t option is set to "default".
161	greg	1.1	If unspecified, the default color will be white.
162			.TP
163	greg	1.3	.BI \-u \ lamp
164	greg	1.1	Set the default lamp color according to the entry for
165			.I lamp
166	greg	1.3	in the lookup table (see the \-f option).
167	greg	1.1	This is the color that will be used if the input specification
168			does not match any lamp type patterns.
169	greg	1.3	This option is used instead of the \-c option.
170	greg	1.1	.TP
171	greg	1.3	.BI \-m \ factor
172	greg	1.1	Multiply all output quantities by
173			.I factor.
174			This is the best way to scale fixture brightness for different lamps, but care
175			should be taken when this option is applied to multiple files.
176			.SH EXAMPLE
177			To convert a single IES data file in inches with color balanced output
178			and 15% lumen depreciation,
179			creating the files "fluor01.rad" and "fluor01.dat" in the current directory:
180			.IP "" .2i
181	greg	1.3	ies2rad \-di \-t default \-m .85 fluor01.ies
182	greg	1.1	.PP
183			To convert three IES files of various types to tenths of a foot and put
184			them in the library "/usr/local/lib/ray" subdirectory "source/ies":
185			.IP "" .2i
186	greg	1.3	ies2rad \-df/10 \-l /usr/local/lib/ray \-p source/ies ies01 ies02 ies03
187	greg	1.1	.PP
188			To convert a single file and give the output a different name:
189			.IP "" .2i
190	greg	1.3	ies2rad \-o fluorescent ies03
191	greg	1.1	.SH ENVIRONMENT
192			RAYPATH directories to search for lamp lookup table
193			.SH AUTHOR
194			Greg Ward
195			.SH BUGS
196	greg	1.3	In pre\-1991 standard IES files, all header lines will be examined
197	greg	1.1	for a lamp table string match.
198	greg	1.3	In post\-1991 standard files, only those lamps with the [LAMP] or
199	greg	1.1	[LAMPCAT] keywords will be searched.
200			The first match found in the file is always the one used.
201			This method of assigning colors to fixtures is less than perfect,
202			and the IES would do well to include explicit spectral information
203			somehow in their specification.
204			.PP
205	greg	1.3	The IESNA LM\-63 specification prior to 1995 provided three basic source
206	greg	1.1	shapes, rectangular, round, and elliptical.
207			The details of these shapes is vague at best.
208			Rectangular sources will always be rectangular, but ies2rad will
209			approximate round sources as spherical if the height is close to
210			or greater than the width and length, and as a ring otherwise.
211			Elliptical sources are treated the same as round sources.
212			The 1995 standard rectifies this problem by including detailed
213			luminaire geometry as MGF data, though nothing in the standard
214			requires manufacturers to provide this information.
215			.SH "SEE ALSO"
216			mgf2rad(1), oconv(1), pfilt(1), rad2mgf(1), rpict(1), xform(1)