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

Comparing ray/doc/man/man1/evalglare.1 (file contents):
Revision 1.1 by greg, Wed Aug 12 23:07:59 2015 UTC vs.
Revision 1.2 by greg, Sun Apr 10 04:08:19 2016 UTC

# Line 1 | Line 1
1   .\" RCSid $Id$
2   .TH EVALGLARE 1 7/30/15 RADIANCE
3   .SH NAME
4 < .PP
5 < evalglare \- determines and evaluates glare sources within a 180 degree
6 < fish\-eye\-image, given in the RADIANCE RGBE (.hdr) image format.
4 > evalglare \- determines and evaluates glare sources within a 180 degree fisheye HDR image
5   .SH SYNOPSIS
6   .PP
7 < evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c checkfile]
8 < [\-t xpos ypos angle] [\-T xpos ypos angle] [\-d] [\-r angle] [\[en]i
9 < Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] [\[en]g type] [\-G
10 < type] [\-u r g b ] [\-vf viewfile] [\-vtt ] [\-vv vertangle] [\-vh horzangle] hdrfile
11 < .PP
12 < or
13 < .PP
14 < hdr|evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c
15 < checkfile] [\-t xpos ypos angle][\-T xpos ypos angle] [\-d] [\-r angle]
16 < [\[en]i Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] ] [\[en]g
17 < type] [\-G type] [\-u r g b ] [\-vf viewfile][\-vtt ] [\-vv vertangle] [\-vh
18 < horzangle]
7 > .nh
8 > .B evalglare
9 > [
10 > .BI \-s
11 > ]
12 > [
13 > .BI \-y
14 > ]
15 > [
16 > .BI \-Y \ value
17 > ]
18 > [
19 > .BI \-B " angle"
20 > ]
21 > [
22 > .BI \-b " factor"
23 > ]
24 > [
25 > .BI \-c " checkfile"
26 > ]
27 > [
28 > .BI \-t " xpos ypos angle"
29 > ]
30 > [
31 > .BI \-T " xpos ypos angle"
32 > ]
33 > [ \-d ]
34 > [
35 > .BI \-r " angle"
36 > ]
37 > [
38 > .BI \-i " Ev"
39 > ]
40 > [
41 > .BI \-I " Ev yfill_max y_fill_min"
42 > ]
43 > [
44 > .BI \-v
45 > ]
46 > [
47 > .BI \-V
48 > ]
49 > [
50 > .BI \-g " type"
51 > ]
52 > [
53 > .BI \-G " type"
54 > ]
55 > [
56 > .BI \-u " r g b"
57 > ]
58 > [
59 > .BI \-vf " viewfile"
60 > ]
61 > [
62 > .BI \-vt t  
63 > ]
64 > [
65 > .BI \-vv " vertangle"
66 > ]
67 > [
68 > .BI \-vh " horzangle"
69 > ]
70 > .RI [ hdrfile ]
71 > .hy
72   .SH DESCRIPTION
73   .PP
74 < evalglare determines and evaluates glare sources within a 180 degree
75 < fish\-eye\-image, given in the RADIANCE image format (.pic or .hdr).
76 < The image should be rendered as fish eye (e.g.
77 < using the \-vta or \[en]vth option) using 180 degree for the horizontal and
78 < vertical view angle (\-vv =180, \-vh=180).
79 < Due to performance reasons of the evalglare code, the image should be
80 < smaller than 1200x1200 pixels. The recommended size is 800x800 pixels.
81 < In the first step, the program uses a given threshold to determine all
82 < glare sources.
83 < Three different threshold methods are implemented.
84 < The recommended method is to define a task area by \-t or \-T option.
85 < In this (task) area the average luminance is calculated Each pixel,
86 < exceeding this value multiplied by the \-b factor [default=5] is treated
87 < as a potential glare source.
88 < The other two methods are described below [see \-b].
89 < In the second step the program tries to merge glare source pixels to one
90 < glare source, when they are placed nearby each other.
91 < This merging is performed in\-between a search area, given by an opening
41 < angle (\-r, default =0.2 in radiant).
42 < If a check file is written (\-c fname), the detected glare sources will
43 < be colored to different colors where the rest of the image is set to
44 < gray.
45 < The luminance values of all pixels are kept to the initial value.
46 < The color is chosen by chance, no significance is given by the color.
47 < To enable a unform coloring for all glare sources, the \-u option can be used.
48 < Luminance peaks can be extracted to separate glare sources by using the
49 < \-y or \-Y value option (default since version v0.9c).
50 < Default value (\-y) is 50000 cd/m2, can be changed by using \-Y value.
51 < A smoothing option (\-s) counts initial non\-glare source pixels to
52 < glare sources, when they are surrounded by a glare source.
74 > .B Evalglare
75 > determines and evaluates glare sources within a 180 degree fisheye
76 > image, given in the RADIANCE image format (.pic or .hdr). If
77 > .I hdrfile
78 > is not given as an argument, the standard input is read.  The image
79 > should be rendered as fisheye (e.g.  using the
80 > .BI \-vt a
81 > or
82 > .BI \-vt h
83 > option) using 180 degrees for the horizontal and vertical view angle
84 > .RB ( -vv
85 > .IR 180 ,
86 > .B -vh
87 > .IR 180 ).
88 > The recommended size of images input to
89 > .B evalglare
90 > is 1000x1000 pixels; the computations become very long when the image
91 > is more than 1200x1200 pixels.
92   .PP
93 < The program calculates the daylight glare probability (DGP) as well as
94 < other glare indexes (dgi,ugr,vcp,cgi) to the standard output.
95 < The DGP describes the fraction of persons disturbed, caused by glare from
96 < daylight (range 0...1).
97 < Values lower than 0.2 are out of the range of the user assessment tests,
98 < where the program is based on and should be interpreted carefully.
99 < A low light correction is applied to the DGP when the vertical illumiance is lower than 500 lux.
100 < By the use of \-g or \-G the field of view is cut according the the definition of Guth.
101 < The option \-B angle (in rad) calculates the average luminance of a horizontal band.
102 < In the case of non\-180 degree images, an external measured illuminance value
103 < can be provided by using the \[en]i or \[en]I option.
104 < The use of the \[en]I option enables the filling up of images, which are
105 < horizontally cut.
106 < The age correction is not supported any more and disabled.
107 < If the option \-d is used, all found glare sources and their position,
108 < size, and luminance values are printed to the standard output, too.
109 < The last line gives following values: 1.
110 < dgp, 2.
111 < average luminance of image,3.
112 < vertical eye illuminance, 4.
113 < background luminance, 5.
114 < direct vertical eye illuminance, 6.
115 < dgi, 7.
116 < ugr, 8.
117 < vcp, 9.
118 < cgi, 10.
119 < average luminance of all glare sources, 11.
120 < sum of solid angles of all glare sources 12.
121 < Veiling luminance (disability glare) 13.
122 < x\-direction of glare source 14.
123 < y\-direction of glare source 15.
124 < z\-direction of glare source 16.
125 < band luminance
93 > The calculation of glare proceeds in two steps:
94 > .IP 1. 3em
95 > In the first step, the program uses a given threshold
96 > to determine all glare sources.  Three different threshold methods are
97 > implemented.  The recommended method is to define a task area by
98 > .B \-t
99 > or
100 > .B \-T
101 > option.  The average luminance of the task area is calculated.  Each
102 > pixel exceeding this value multiplied by the
103 > .B \-b
104 > factor, default 5, is treated as a potential glare source.  The other
105 > two methods are described below, see
106 > .BR \-b .
107 > .IP 2.
108 > In the second step, the program tries to merge glare source pixels to
109 > one glare source, when they are placed nearby each other.  This
110 > merging is performed between search areas, given by an opening angle
111 > .BR \-r ,
112 > default 0.2 radians.  If a check file is written,
113 > .B \-c
114 > .IR fname ,
115 > the detected glare sources will be colored, each with a different
116 > color, and the rest of the image will be set to gray.  The luminance values
117 > of all pixels are kept to the initial value.  The color is chosen by
118 > chance, no significance is given by the color.  To enable unform
119 > coloring of all glare sources, the
120 > .B \-u
121 > option can be used.  Luminance
122 > peaks can be extracted to separate glare sources by using the
123 > .B \-y
124 > or
125 > .BI \-Y " value"
126 > option.  The default value
127 > .B \-y
128 > is 50,000 cd/m2, which can be changed by using the
129 > .B \-Y
130 > value.  A smoothing option,
131 > .BR \-s ,
132 > counts initial non-glare source pixels to glare sources, when they are
133 > surrounded by a glare source.
134   .PP
135 < The program is based on the studies from J.
136 < Christoffersen and J.
137 < Wienold (see \“Evaluation methods and development of a new glare
138 < prediction model for daylight environments with the use of CCD cameras
139 < and RADIANCE\“ , Energy and Buildings, 2006.
140 < More details can be also found in following issertation: J.
141 < Wienold, \“Daylight glare in offices\”, Fraunhofer IRB, 2010.
142 < URL for download:
143 < http://publica.fraunhofer.de/eprints/urn:nbn:de:0011\-n\-1414579.pdf
135 > The program calculates the daylight glare probability (DGP) as well as
136 > other glare indices (DGI, UGR, VCP, CGI) and writes them to the
137 > standard output.  The DGP describes the fraction of persons disturbed
138 > caused by glare from daylight as a number from 0 to 1, where 0 is
139 > no-one disturbed and 1 is everyone.  Values lower than 0.2 are out of
140 > the range of the user assessment tests which the program is based on
141 > and should be interpreted carefully.  A low light correction is
142 > applied to the DGP when the vertical illumiance is lower than 500 lux.
143 > By the use of
144 > .B \-g
145 > or
146 > .B \-G
147 > .\" Citation?
148 > the field of view is cut according the the definition of Guth.
149 > The option
150 > .B \-B
151 > angle (in radians) calculates the average luminance of a
152 > horizontal band.  In the case of non-180 degree images, an external
153 > measured illuminance value can be provided by using the
154 > .B \-i
155 > or
156 > .B \-I
157 > option.  The use of the
158 > .B \-I
159 > option enables the filling up of images, which are horizontally cut.
160 > If the
161 > option
162 > .B \-d
163 > is used, all found glare sources and their position, size, and
164 > luminance values are printed to the standard output, too.  The last
165 > line gives following values: (1) DGP, (2) average luminance of image,
166 > (3) vertical eye illuminance, (4) background luminance, (5) direct
167 > vertical eye illuminance, (6) DGI, (7) UGR, (8) VCP, (9) CGI, (10)
168 > average luminance of all glare sources, (11) sum of solid angles of
169 > all glare sources, (12) Veiling luminance (disability glare), (13)
170 > x-direction of glare source, (14) y-direction of glare source, (15)
171 > z-direction of glare source, and (16) band luminance.
172 > .SH OPTIONS
173   .TP
174 < .B \-B \f[I]angle\f[],
175 < Calculate average luminance of a horizontal band. The angle is in rad. Output only when using the \-d option.
176 < .RS
177 < .RE
174 > .BI \-B \ angle
175 > Calculate average luminance of a horizontal band. The angle is in
176 > radians. This calculation does not affect glare source detection.
177 > Output only when using the
178 > .B \-d
179 > option.
180   .TP
181 < .B \-b \f[I]factor\f[],
182 < Threshold factor; if factor >100, it is used as constant threshold in
183 < cd/m2, regardless if a task position is given or not if factor is <= 100
184 < and a task position is given, this factor multiplied by the average task
185 < luminance will be used as threshold for detecting the glare sources if
186 < factor is <= 100 and no task position is given, this factor multiplied
187 < by the average luminance in the entire picture will be used as threshold
188 < for detecting the glare sources, default value=5.
189 < .RS
112 < .RE
181 > .BI \-b \ factor
182 > Threshold factor; if factor is over 100, it is used as constant threshold in
183 > cd/m2, regardless if a task position is given or not if
184 > factor is less than or equal to 100 and a task position is given, this
185 > factor multiplied by the average task luminance will be used as
186 > threshold for detecting the glare sources if factor is less than or
187 > equal to 100 and no task position is given, this factor multiplied by
188 > the average luminance in the entire picture will be used as threshold
189 > for detecting the glare sources, default\ 5.
190   .TP
191 < .B \-c \f[I]fname\f[]
191 > .BI \-c \ fname
192   writes a checkfile in the RADIANCE picture format
116 .RS
117 .RE
193   .TP
194   .B \-d
195   enables detailed output (default: disabled)
121 .RS
122 .RE
196   .TP
197 < .B \-g \f[I]type\f[]
198 < cut field of view according to Guth, write checkfile specified by \[en]c
199 < and exit without any glare evaluation.
200 < type=1: total field of view type=2: field of view seen by both eyes
201 < .RS
129 < .RE
197 > .BI \-g \ type
198 > cut field of view according to Guth, write checkfile specified by
199 > .B \-c
200 > and exit without any glare evaluation.  Type 1: total field of view.
201 > Type 2: field of view seen by both eyes
202   .TP
203 < .B \-G \f[I]type\f[]
204 < cut field of view according to Guth, perform glare evaluation.
205 < type=1: total field of view type=2: field of view seen by both eyes
134 < .RS
135 < .RE
203 > .BI \-G \ type
204 > Cut the field of view according to Guth, perform glare evaluation.
205 > Type 1: total field of view. Type 2: field of view seen by both eyes
206   .TP
207 < .B \-i \f[I]Ev\f[]
208 < The vertical illuminance is measured externally.
209 < This value will be used for calculating the dgp.
140 < .RS
141 < .RE
207 > .BI \-i \ Ev
208 > The vertical illuminance is measured externally.  This value will be
209 > used for calculating the dgp.
210   .TP
211 < .B \-I \f[I]Ev y_max y_min\f[]
211 > .BI \-I \ Ev \  y_max \  y_min
212   The vertical illuminance is measured externally.
213 < This value will be used for calculating the dgp.
214 < Below y_min and above y_max, the picture is filled up by the last known
215 < value.
216 < This option should be used, when the provided picture is cut
217 < horizontally.
218 < .RS
219 < .RE
213 > This value will be used for calculating the DGP.
214 > Below
215 > .I y_min
216 > and above
217 > .IR y_max ,
218 > the picture is filled up by the last known value.  This option should
219 > be used, when the provided picture is cut horizontally.
220   .TP
221 < .B \-r \f[I]angle\f[]
222 < search radius (angle in radiant) between pixels, where evalglare tries
221 > .BI \-r \ angle
222 > search radius (angle in radians) between pixels, where
223 > .B evalglare
224 > tries
225   to merge glare source pixels to the same glare source (default value:
226 < 0.2 radiant)
157 < .RS
158 < .RE
226 > 0.2 radians)
227   .TP
228   .B \-s
229   enables smoothing function (default: disabled)
162 .RS
163 .RE
230   .TP
231 < .B \-t \f[I]xpos ypos angle\f[]
231 > .BI \-t \ xpos \  ypos \  angle
232   definition of task position in x and y coordinates, and its opening
233 < angle in radiant
168 < .RS
169 < .RE
233 > angle in radians
234   .TP
235 < .B \-T \f[I]xpos ypos angle\f[]
236 < same as \-t, except that the task area is colored bluish in the
237 < checkfile
238 < .RS
175 < .RE
235 > .BI \-T \ xpos \  ypos \  angle
236 > same as
237 > .BR \-t ,
238 > except that the task area is colored bluish in the checkfile
239   .TP
240 < .B \-u \f[I]r g b\f[]
241 < color glare sources unfiformly when writing check file (implies \-c option). Color given in r g b.
242 < .RS
243 < .RE
240 > .BI \-u \ r \  g \  b
241 > color glare sources uniformly when writing check file (implies
242 > .B \-c
243 > option). Color given in r g b.
244   .TP
245   .B \-v
246 < show version of evalglare and exit
247 < .RS
248 < .RE
246 > show version of
247 > .B evalglare
248 > and exit
249   .TP
250   .B \-V
251   Just calculate the vertical illuminance and exit
189 .RS
190 .RE
252   .TP
253   .B \-x
254   disable peak extraction
194 .RS
195 .RE
255   .TP
256   .B \-y
257   enables peak extraction (default: enabled)
199 .RS
200 .RE
258   .TP
259 < .B \-Y \f[I]value\f[]
260 < enables peak extraction with value as threshold for extracted peaks
261 < .RS
262 < .RE
259 > .BI \-Y \ value
260 > enables peak extraction with
261 > .I value
262 > as threshold for extracted peaks.
263   .PP
264 < In case, the view settings within the image are missing or are not valid
265 < (e.g.
266 < after the use of pcompos or pcomb), the view options can be set by
267 < command line options.
268 < As soon as view options are set within the command line, view options
269 < within the image are ignored.
270 < The view options are implemented according to the RADIANCE definition
271 < (please read man page of rpict for details):
264 > .I "If the view settings in the image file"
265 > are missing or are not valid (e.g.  after the use of
266 > .BR pcompos "(1) or " pcomb (1)),
267 > the view options can be set by command line options.  If view options
268 > are set on the command line, view options in the image file header are
269 > ignored.  The view options are implemented according to the RADIANCE
270 > definition; please read the
271 > .BR rpict (1)
272 > man page for details.
273 > .sp
274   .TP
275 < .B \-vtt
276 < Set view type to t (for fish\-eye views, please use \[en]vta or \[en]vth
275 > .BI \-vt t
276 > Set view type to t (for fisheye views, please use
277 > .BI \-vt \ a
278 > or
279 > .BI \-vt \ h
280   preferably)
219 .RS
220 .RE
281   .TP
282 < .B \-vf \f[I]viewfile\f[]
282 > .BI \-vf \ viewfile
283   Get view parameters from file
224 .RS
225 .RE
284   .TP
285 < .B \-vv \f[I]val\f[]
285 > .BI \-vv \ val
286   Set the view vertical size to val
229 .RS
230 .RE
287   .TP
288 < .B \-vh \f[I]val\f[]
289 < Set the view horizontal size to \f[I]val\f[]
290 < .RS
291 < .RE
288 > .BI \-vh \ val
289 > Set the view horizontal size to
290 > .I val
291 > .SH AUTHOR
292 > Jan Wienold.
293 > .SH SEE ALSO
294 > .BR rpict (1)
295 > .SH REFERENCES
296 > .B Evalglare
297 > is based on the studies by J.  Christoffersen and J.
298 > Wienold (see \*(lqEvaluation methods and development of a new glare
299 > prediction model for daylight environments with the use of CCD cameras
300 > and RADIANCE,\*(rq
301 > .IR "Energy and Buildings 38" ,
302 > 2006, pp. 743\-757, doi:10.1016/j.enbuild.2006.03.017.  More
303 > details can be also found in following dissertation: J.  Wienold,
304 > .IR "Daylight glare in offices" ,
305 > Fraunhofer IRB, 2010, available online at
306 > .nh
307 > <http://publica.fraunhofer.de/dokumente/N-141457.html>.
308 > .hy
309   .SH ACKNOWLEDGEMENTS
310 + The evalglare program was originally developed by Jan Wienold at the
311 + Fraunhofer Institute for Solar Energy Systems in Freiburg, Germany. It
312 + is being further developed and maintained by the same author at EPFL,
313 + Lausanne, Switzerland.
314   .PP
315 < The evalglare program was developped by Jan Wienold originally at the Fraunhofer
316 < Institute for Solar Energy Systems in Freiburg, Germany. It is further developped
317 < and maintained by the same author at EPFL, Lausanne, Switzerland.
315 > The author would like to thank C.  Reetz for his generous help and his
316 > support of providing libraries for the program.  The EU Commission
317 > supported this work as part of the EU project \*(lqEnergy and Comfort
318 > Control for Building management systems\*(rq (ECCO-Build, Contract
319 > ENK6-CT-2002-00656).
320   .PP
321 < The author would like to thank C.
322 < Reetz for his generous help and his support of providing libraries for
244 < the program.
245 < The EU Commission supported this work as part of the EU project “Energy
246 < and Comfort Control for Building management systems” (ECCO\-Build,
247 < Contract N°: ENK6\-CT\-2002\-00656).
248 < .PP
249 < The dfg\-foundation (contract WI 1304/7\-2 ) supported the research for
250 < the extension of evalglare for low\-light scenes.
251 < .SH AUTHORS
252 < Jan Wienold.
321 > German Research Foundation (DFG) contract WI 1304/7-2 supported the research
322 > for the extension of evalglare for low light scenes.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines