ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/radiance/ray/doc/man/man1/ies2rad.1
(Generate patch)

Comparing ray/doc/man/man1/ies2rad.1 (file contents):
Revision 1.4 by greg, Thu Jan 24 23:15:46 2008 UTC vs.
Revision 1.5 by greg, Mon Nov 29 16:07:36 2021 UTC

# Line 1 | Line 1
1   .\" RCSid "$Id$"
2 < .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 < 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 < 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.
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 < .I Ies2rad
16 < assigns light source colors based on information in a lamp lookup table.
17 < Since most lamps are distinctly colored,
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 assortment
35 < of fixture types is being used to illuminate the same scene, and
36 < the rendering can always be balanced by pfilt(1) to a specific white value
37 < later.
38 < .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.
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 -p \ prefdir
41 < Set the library subdirectory path to
42 < .I prefdir.
43 < This is the subdirectory from the library where all output files will
44 < be placed.
45 < 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.
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 -o \ outname
48 < Set the output file name root to
49 < .I outname.
50 < This overrides the default output file name root which is the same as the
51 < input file.
52 < This option may be used for only one input file, and is required when
53 < reading data from the standard input.
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 < .BR -s
56 < Send the scene information to the standard output rather than a
57 < separate file.
58 < This is appropriate when calling
59 < .I ies2rad
60 < from within a scene description via an inline command.
61 < The data file(s) will still be written based on the output file name
62 < root, but since this information is unaffected by command line options,
63 < it is safe to have multiple invocations of
64 < .I ies2rad
65 < using the same input file and different output options.
66 < The
67 < .I \-s
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
73 < .I units,
74 < which is one of the letters 'm', 'c', 'f', or 'i' for meters,
75 < centimeters, feet or inches, respectively.
76 < The letter specification may be followed by a slash ('/') and an
77 < optional divisor.
78 < 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.
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 instead an illum
82 < sphere with radius
83 < .I rad.
84 < This option may be useful when the user wishes to add a more accurate
85 < geometric description to the light source model, though this need
86 < is obviated by the recent LM-63-1995 specification, which uses MGF
121 < detail geometry.
122 < (See
123 < .I \-g
124 < option below.)\0
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 < .BR -g
89 < If the IES file contains MGF detail geometry, compile this geometry into
90 < a separate octree and create a single instance referencing it
91 < instead of including the converted geometry directly in the Radiance
92 < output file.
93 < This can result in a considerable memory savings for luminaires
94 < which are later duplicated many times in a scene, though the
95 < appearance may suffer for certain luminaires since the enclosed glow
96 < sources will not light the local geometry as they would otherwise.
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
100 < .I lampdat
139 < instead of the default lamp lookup table (lamp.tab) to map lamp
140 < names to xy chromaticity and lumen depreciation data.
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.
146 < Normally,
147 < .I ies2rad
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.
108 < If any of the lines is matched by a pattern in the lamp lookup
109 < table (see the \-f option above), that color and depreciation factor will
110 < be used instead of the default (see the \-c and \-u options).
111 < The
112 < .I lamp
113 < 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.
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
117 < the \-t option is set to "default".
118 < If unspecified, the default color will be white.
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
122 < .I lamp
123 < in the lookup table (see the \-f option).
124 < This is the color that will be used if the input specification
125 < does not match any lamp type patterns.
169 < This option is used instead of the \-c option.
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
129 < .I factor.
174 < This is the best way to scale fixture brightness for different lamps, but care
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 EXAMPLE
132 < To convert a single IES data file in inches with color balanced output
133 < and 15% lumen depreciation,
134 < creating the files "fluor01.rad" and "fluor01.dat" in the current directory:
135 < .IP "" .2i
136 < ies2rad \-di \-t default \-m .85 fluor01.ies
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 and put
177 < them in the library "/usr/local/lib/ray" subdirectory "source/ies":
178 < .IP "" .2i
179 < ies2rad \-df/10 \-l /usr/local/lib/ray \-p source/ies ies01 ies02 ies03
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 < .IP "" .2i
187 < ies2rad \-o fluorescent ies03
188 < .SH ENVIRONMENT
189 < RAYPATH         directories to search for lamp lookup table
190 < .SH AUTHOR
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.
211 < In post\-1991 standard files, only those lamps with the [LAMP] or
212 < [LAMPCAT] keywords will be searched.
213 < The first match found in the file is always the one used.
201 < This method of assigning colors to fixtures is less than perfect,
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 < The IESNA LM\-63 specification prior to 1995 provided three basic source
218 < shapes, rectangular, round, and elliptical.
219 < 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.
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 < mgf2rad(1), oconv(1), pfilt(1), rad2mgf(1), rpict(1), xform(1)
221 > \fBlamp.tab\fP(5), \fBmgf2rad\fP(1), \fBoconv\fP(1), \fBpfilt\fP(1),
222 > \fBrad2mgf\fP(1), \fBrpict\fP(1), \fBxform\fP(1)

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines