man/man1/evalglare.1

.\" RCSid $Id: evalglare.1,v 1.1 2015/08/12 23:07:59 greg Exp $
.TH EVALGLARE 1 7/30/15 RADIANCE
.SH NAME
evalglare \- determines and evaluates glare sources within a 180 degree fisheye HDR image
.SH SYNOPSIS
.PP
.nh
.B evalglare 
[ 
.BI \-s 
] 
[ 
.BI \-y 
] 
[ 
.BI \-Y \ value 
] 
[ 
.BI \-B " angle"
] 
[ 
.BI \-b " factor"
] 
[ 
.BI \-c " checkfile"
]
[ 
.BI \-t " xpos ypos angle"
] 
[ 
.BI \-T " xpos ypos angle"
] 
[ \-d ] 
[ 
.BI \-r " angle"
] 
[ 
.BI \-i " Ev"
] 
[
.BI \-I " Ev yfill_max y_fill_min" 
] 
[ 
.BI \-v 
] 
[ 
.BI \-V 
] 
[ 
.BI \-g " type"
] 
[ 
.BI \-G " type"
] 
[ 
.BI \-u " r g b"
] 
[ 
.BI \-vf " viewfile"
] 
[ 
.BI \-vt t  
] 
[ 
.BI \-vv " vertangle"
] 
[ 
.BI \-vh " horzangle"
] 
.RI [ hdrfile ]
.hy
.SH DESCRIPTION
.PP
.B Evalglare
determines and evaluates glare sources within a 180 degree fisheye
image, given in the RADIANCE image format (.pic or .hdr). If
.I hdrfile
is not given as an argument, the standard input is read.  The image
should be rendered as fisheye (e.g.  using the
.BI \-vt a 
or 
.BI \-vt h 
option) using 180 degrees for the horizontal and vertical view angle
.RB ( -vv
.IR 180 ,
.B -vh
.IR 180 ).
The recommended size of images input to 
.B evalglare
is 1000x1000 pixels; the computations become very long when the image
is more than 1200x1200 pixels.
.PP
The calculation of glare proceeds in two steps:
.IP 1. 3em
In the first step, the program uses a given threshold
to determine all glare sources.  Three different threshold methods are
implemented.  The recommended method is to define a task area by
.B \-t 
or 
.B \-T 
option.  The average luminance of the task area is calculated.  Each
pixel exceeding this value multiplied by the
.B \-b 
factor, default 5, is treated as a potential glare source.  The other
two methods are described below, see
.BR \-b .
.IP 2.
In the second step, the program tries to merge glare source pixels to
one glare source, when they are placed nearby each other.  This
merging is performed between search areas, given by an opening angle
.BR \-r ,
default 0.2 radians.  If a check file is written,
.B \-c
.IR fname ,
the detected glare sources will be colored, each with a different
color, and the rest of the image will be set to gray.  The luminance values
of all pixels are kept to the initial value.  The color is chosen by
chance, no significance is given by the color.  To enable unform
coloring of all glare sources, the
.B \-u 
option can be used.  Luminance
peaks can be extracted to separate glare sources by using the 
.B \-y 
or
.BI \-Y " value"
option.  The default value 
.B \-y
is 50,000 cd/m2, which can be changed by using the 
.B \-Y 
value.  A smoothing option,
.BR \-s , 
counts initial non-glare source pixels to glare sources, when they are
surrounded by a glare source.
.PP
The program calculates the daylight glare probability (DGP) as well as
other glare indices (DGI, UGR, VCP, CGI) and writes them to the
standard output.  The DGP describes the fraction of persons disturbed
caused by glare from daylight as a number from 0 to 1, where 0 is
no-one disturbed and 1 is everyone.  Values lower than 0.2 are out of
the range of the user assessment tests which the program is based on
and should be interpreted carefully.  A low light correction is
applied to the DGP when the vertical illumiance is lower than 500 lux.
By the use of
.B \-g
or 
.B \-G
.\" Citation?
the field of view is cut according the the definition of Guth.
The option 
.B \-B 
angle (in radians) calculates the average luminance of a
horizontal band.  In the case of non-180 degree images, an external
measured illuminance value can be provided by using the 
.B \-i 
or
.B \-I 
option.  The use of the 
.B \-I 
option enables the filling up of images, which are horizontally cut.
If the
option
.B \-d 
is used, all found glare sources and their position, size, and
luminance values are printed to the standard output, too.  The last
line gives following values: (1) DGP, (2) average luminance of image,
(3) vertical eye illuminance, (4) background luminance, (5) direct
vertical eye illuminance, (6) DGI, (7) UGR, (8) VCP, (9) CGI, (10)
average luminance of all glare sources, (11) sum of solid angles of
all glare sources, (12) Veiling luminance (disability glare), (13)
x-direction of glare source, (14) y-direction of glare source, (15)
z-direction of glare source, and (16) band luminance.
.SH OPTIONS
.TP
.BI \-B \ angle
Calculate average luminance of a horizontal band. The angle is in
radians. This calculation does not affect glare source detection.
Output only when using the
.B \-d 
option.
.TP
.BI \-b \ factor
Threshold factor; if factor is over 100, it is used as constant threshold in
cd/m2, regardless if a task position is given or not if
factor is less than or equal to 100 and a task position is given, this
factor multiplied by the average task luminance will be used as
threshold for detecting the glare sources if factor is less than or
equal to 100 and no task position is given, this factor multiplied by
the average luminance in the entire picture will be used as threshold
for detecting the glare sources, default\ 5.
.TP
.BI \-c \ fname
writes a checkfile in the RADIANCE picture format
.TP
.B \-d
enables detailed output (default: disabled)
.TP
.BI \-g \ type
cut field of view according to Guth, write checkfile specified by 
.B \-c
and exit without any glare evaluation.  Type 1: total field of view.
Type 2: field of view seen by both eyes
.TP
.BI \-G \ type
Cut the field of view according to Guth, perform glare evaluation.
Type 1: total field of view. Type 2: field of view seen by both eyes
.TP
.BI \-i \ Ev
The vertical illuminance is measured externally.  This value will be
used for calculating the dgp.
.TP
.BI \-I \ Ev \  y_max \  y_min
The vertical illuminance is measured externally.
This value will be used for calculating the DGP.
Below 
.I y_min 
and above 
.IR y_max , 
the picture is filled up by the last known value.  This option should
be used, when the provided picture is cut horizontally.
.TP
.BI \-r \ angle
search radius (angle in radians) between pixels, where 
.B evalglare
tries
to merge glare source pixels to the same glare source (default value:
0.2 radians)
.TP
.B \-s
enables smoothing function (default: disabled)
.TP
.BI \-t \ xpos \  ypos \  angle
definition of task position in x and y coordinates, and its opening
angle in radians
.TP
.BI \-T \ xpos \  ypos \  angle
same as 
.BR \-t , 
except that the task area is colored bluish in the checkfile
.TP
.BI \-u \ r \  g \  b
color glare sources uniformly when writing check file (implies
.B \-c
option). Color given in r g b.
.TP
.B \-v
show version of 
.B evalglare
and exit
.TP
.B \-V
Just calculate the vertical illuminance and exit
.TP
.B \-x
disable peak extraction
.TP
.B \-y
enables peak extraction (default: enabled)
.TP
.BI \-Y \ value
enables peak extraction with 
.I value 
as threshold for extracted peaks.
.PP
.I "If the view settings in the image file"
are missing or are not valid (e.g.  after the use of
.BR pcompos "(1) or " pcomb (1)), 
the view options can be set by command line options.  If view options
are set on the command line, view options in the image file header are
ignored.  The view options are implemented according to the RADIANCE
definition; please read the
.BR rpict (1)
man page for details.
.sp
.TP
.BI \-vt t
Set view type to t (for fisheye views, please use 
.BI \-vt \ a 
or 
.BI \-vt \ h
preferably)
.TP
.BI \-vf \ viewfile
Get view parameters from file
.TP
.BI \-vv \ val
Set the view vertical size to val
.TP
.BI \-vh \ val
Set the view horizontal size to 
.I val
.SH AUTHOR
Jan Wienold.
.SH SEE ALSO
.BR rpict (1)
.SH REFERENCES
.B Evalglare
is based on the studies by J.  Christoffersen and J.
Wienold (see \*(lqEvaluation methods and development of a new glare
prediction model for daylight environments with the use of CCD cameras
and RADIANCE,\*(rq
.IR "Energy and Buildings 38" ,
2006, pp. 743\-757, doi:10.1016/j.enbuild.2006.03.017.  More
details can be also found in following dissertation: J.  Wienold,
.IR "Daylight glare in offices" ,
Fraunhofer IRB, 2010, available online at
.nh
<http://publica.fraunhofer.de/dokumente/N-141457.html>.
.hy
.SH ACKNOWLEDGEMENTS
The evalglare program was originally developed by Jan Wienold at the
Fraunhofer Institute for Solar Energy Systems in Freiburg, Germany. It
is being further developed and maintained by the same author at EPFL,
Lausanne, Switzerland.
.PP
The author would like to thank C.  Reetz for his generous help and his
support of providing libraries for the program.  The EU Commission
supported this work as part of the EU project \*(lqEnergy and Comfort
Control for Building management systems\*(rq (ECCO-Build, Contract
ENK6-CT-2002-00656).
.PP
German Research Foundation (DFG) contract WI 1304/7-2 supported the research
for the extension of evalglare for low light scenes.
Revision:	1.2
Committed:	Sun Apr 10 04:08:19 2016 UTC (9 years ago) by greg
Branch:	MAIN
Changes since 1.1:	+280 -210 lines
Log Message:	Edits and corrections contributed by Randolph Fritz
#	User	Rev	Content
1	greg	1.2	.\" RCSid $Id: evalglare.1,v 1.1 2015/08/12 23:07:59 greg Exp $
2	greg	1.1	.TH EVALGLARE 1 7/30/15 RADIANCE
3			.SH NAME
4	greg	1.2	evalglare \- determines and evaluates glare sources within a 180 degree fisheye HDR image
5	greg	1.1	.SH SYNOPSIS
6			.PP
7	greg	1.2	.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	greg	1.1	.PP
74	greg	1.2	.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 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	greg	1.1	or
125	greg	1.2	.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	greg	1.1	.PP
135			The program calculates the daylight glare probability (DGP) as well as
136	greg	1.2	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			.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			.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	greg	1.1	.TP
191	greg	1.2	.BI \-c \ fname
192	greg	1.1	writes a checkfile in the RADIANCE picture format
193			.TP
194			.B \-d
195			enables detailed output (default: disabled)
196			.TP
197	greg	1.2	.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			.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			.BI \-i \ Ev
208			The vertical illuminance is measured externally. This value will be
209			used for calculating the dgp.
210	greg	1.1	.TP
211	greg	1.2	.BI \-I \ Ev \ y_max \ y_min
212	greg	1.1	The vertical illuminance is measured externally.
213	greg	1.2	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			.BI \-r \ angle
222			search radius (angle in radians) between pixels, where
223			.B evalglare
224			tries
225	greg	1.1	to merge glare source pixels to the same glare source (default value:
226	greg	1.2	0.2 radians)
227	greg	1.1	.TP
228			.B \-s
229			enables smoothing function (default: disabled)
230			.TP
231	greg	1.2	.BI \-t \ xpos \ ypos \ angle
232	greg	1.1	definition of task position in x and y coordinates, and its opening
233	greg	1.2	angle in radians
234			.TP
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			.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	greg	1.1	.TP
245			.B \-v
246	greg	1.2	show version of
247			.B evalglare
248			and exit
249	greg	1.1	.TP
250			.B \-V
251			Just calculate the vertical illuminance and exit
252			.TP
253			.B \-x
254			disable peak extraction
255			.TP
256			.B \-y
257			enables peak extraction (default: enabled)
258			.TP
259	greg	1.2	.BI \-Y \ value
260			enables peak extraction with
261			.I value
262			as threshold for extracted peaks.
263			.PP
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			.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	greg	1.1	preferably)
281			.TP
282	greg	1.2	.BI \-vf \ viewfile
283	greg	1.1	Get view parameters from file
284			.TP
285	greg	1.2	.BI \-vv \ val
286	greg	1.1	Set the view vertical size to val
287			.TP
288	greg	1.2	.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	greg	1.1	.SH ACKNOWLEDGEMENTS
310	greg	1.2	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 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	greg	1.1	.PP
321	greg	1.2	German Research Foundation (DFG) contract WI 1304/7-2 supported the research
322			for the extension of evalglare for low light scenes.