man/man1/evalglare.1

.\" RCSid $Id$
.TH EVALGLARE 1 7/30/15 RADIANCE
.SH NAME
.PP
evalglare \- determines and evaluates glare sources within a 180 degree
fish\-eye\-image, given in the RADIANCE RGBE (.hdr) image format.
.SH SYNOPSIS
.PP
evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c checkfile]
[\-t xpos ypos angle] [\-T xpos ypos angle] [\-d] [\-r angle] [\[en]i
Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] [\[en]g type] [\-G
type] [\-u r g b ] [\-vf viewfile] [\-vtt ] [\-vv vertangle] [\-vh horzangle] hdrfile
.PP
or
.PP
hdr|evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c
checkfile] [\-t xpos ypos angle][\-T xpos ypos angle] [\-d] [\-r angle]
[\[en]i Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] ] [\[en]g
type] [\-G type] [\-u r g b ] [\-vf viewfile][\-vtt ] [\-vv vertangle] [\-vh
horzangle]
.SH DESCRIPTION
.PP
evalglare determines and evaluates glare sources within a 180 degree
fish\-eye\-image, given in the RADIANCE image format (.pic or .hdr).
The image should be rendered as fish eye (e.g.
using the \-vta or \[en]vth option) using 180 degree for the horizontal and
vertical view angle (\-vv =180, \-vh=180).
Due to performance reasons of the evalglare code, the image should be
smaller than 1200x1200 pixels. The recommended size is 800x800 pixels.
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 \-t or \-T option.
In this (task) area the average luminance is calculated Each pixel,
exceeding this value multiplied by the \-b factor [default=5] is treated
as a potential glare source.
The other two methods are described below [see \-b].
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 in\-between a search area, given by an opening
angle (\-r, default =0.2 in radiant).
If a check file is written (\-c fname), the detected glare sources will
be colored to different colors where the rest of the image is 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 a unform coloring for all glare sources, the \-u option can be used.
Luminance peaks can be extracted to separate glare sources by using the
\-y or \-Y value option (default since version v0.9c).
Default value (\-y) is 50000 cd/m2, can be changed by using \-Y value.
A smoothing option (\-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 indexes (dgi,ugr,vcp,cgi) to the standard output.
The DGP describes the fraction of persons disturbed, caused by glare from
daylight (range 0...1).
Values lower than 0.2 are out of the range of the user assessment tests,
where 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 \-g or \-G the field of view is cut according the the definition of Guth.
The option \-B angle (in rad) 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 \[en]i or \[en]I option.
The use of the \[en]I option enables the filling up of images, which are
horizontally cut.
The age correction is not supported any more and disabled.
If the option \-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 16.
band luminance
.PP
The program is based on the studies from J.
Christoffersen and J.
Wienold (see \“Evaluation methods and development of a new glare
prediction model for daylight environments with the use of CCD cameras
and RADIANCE\“ , Energy and Buildings, 2006.
More details can be also found in following issertation: J.
Wienold, \“Daylight glare in offices\”, Fraunhofer IRB, 2010.
URL for download:
http://publica.fraunhofer.de/eprints/urn:nbn:de:0011\-n\-1414579.pdf
.TP
.B \-B \f[I]angle\f[],
Calculate average luminance of a horizontal band. The angle is in rad. Output only when using the \-d option.
.RS
.RE
.TP
.B \-b \f[I]factor\f[],
Threshold factor; if factor >100, it is used as constant threshold in
cd/m2, regardless if a task position is given or not if factor is <= 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 <= 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 value=5.
.RS
.RE
.TP
.B \-c \f[I]fname\f[]
writes a checkfile in the RADIANCE picture format
.RS
.RE
.TP
.B \-d
enables detailed output (default: disabled)
.RS
.RE
.TP
.B \-g \f[I]type\f[]
cut field of view according to Guth, write checkfile specified by \[en]c
and exit without any glare evaluation.
type=1: total field of view type=2: field of view seen by both eyes
.RS
.RE
.TP
.B \-G \f[I]type\f[]
cut field of view according to Guth, perform glare evaluation.
type=1: total field of view type=2: field of view seen by both eyes
.RS
.RE
.TP
.B \-i \f[I]Ev\f[]
The vertical illuminance is measured externally.
This value will be used for calculating the dgp.
.RS
.RE
.TP
.B \-I \f[I]Ev y_max y_min\f[]
The vertical illuminance is measured externally.
This value will be used for calculating the dgp.
Below y_min and above y_max, the picture is filled up by the last known
value.
This option should be used, when the provided picture is cut
horizontally.
.RS
.RE
.TP
.B \-r \f[I]angle\f[]
search radius (angle in radiant) between pixels, where evalglare tries
to merge glare source pixels to the same glare source (default value:
0.2 radiant)
.RS
.RE
.TP
.B \-s
enables smoothing function (default: disabled)
.RS
.RE
.TP
.B \-t \f[I]xpos ypos angle\f[]
definition of task position in x and y coordinates, and its opening
angle in radiant
.RS
.RE
.TP
.B \-T \f[I]xpos ypos angle\f[]
same as \-t, except that the task area is colored bluish in the
checkfile
.RS
.RE
.TP
.B \-u \f[I]r g b\f[]
color glare sources unfiformly when writing check file (implies \-c option). Color given in r g b.
.RS
.RE
.TP
.B \-v
show version of evalglare and exit
.RS
.RE
.TP
.B \-V
Just calculate the vertical illuminance and exit
.RS
.RE
.TP
.B \-x
disable peak extraction
.RS
.RE
.TP
.B \-y
enables peak extraction (default: enabled)
.RS
.RE
.TP
.B \-Y \f[I]value\f[]
enables peak extraction with value as threshold for extracted peaks
.RS
.RE
.PP
In case, the view settings within the image are missing or are not valid
(e.g.
after the use of pcompos or pcomb), the view options can be set by
command line options.
As soon as view options are set within the command line, view options
within the image are ignored.
The view options are implemented according to the RADIANCE definition
(please read man page of rpict for details):
.TP
.B \-vtt
Set view type to t (for fish\-eye views, please use \[en]vta or \[en]vth
preferably)
.RS
.RE
.TP
.B \-vf \f[I]viewfile\f[]
Get view parameters from file
.RS
.RE
.TP
.B \-vv \f[I]val\f[]
Set the view vertical size to val
.RS
.RE
.TP
.B \-vh \f[I]val\f[]
Set the view horizontal size to \f[I]val\f[]
.RS
.RE
.SH ACKNOWLEDGEMENTS
.PP
The evalglare program was developped by Jan Wienold originally at the Fraunhofer
Institute for Solar Energy Systems in Freiburg, Germany. It is further developped
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 “Energy
and Comfort Control for Building management systems” (ECCO\-Build,
Contract N°: ENK6\-CT\-2002\-00656).
.PP
The dfg\-foundation (contract WI 1304/7\-2 ) supported the research for
the extension of evalglare for low\-light scenes.
.SH AUTHORS
Jan Wienold.
Revision:	1.1
Committed:	Wed Aug 12 23:07:59 2015 UTC (9 years, 9 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R0
Log Message:	Added Jan Wienold's evalglare to distribution
#	User	Rev	Content
1	greg	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.
7			.SH SYNOPSIS
8			.PP
9			evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c checkfile]
10			[\-t xpos ypos angle] [\-T xpos ypos angle] [\-d] [\-r angle] [\[en]i
11			Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] [\[en]g type] [\-G
12			type] [\-u r g b ] [\-vf viewfile] [\-vtt ] [\-vv vertangle] [\-vh horzangle] hdrfile
13			.PP
14			or
15			.PP
16			hdr\|evalglare [\-s] [\-y] [\-Y value] [\-B angle] [\-b factor] [\-c
17			checkfile] [\-t xpos ypos angle][\-T xpos ypos angle] [\-d] [\-r angle]
18			[\[en]i Ev] [\[en]I Ev yfill_max y_fill_min ] [\-v] [\-V] ] [\[en]g
19			type] [\-G type] [\-u r g b ] [\-vf viewfile][\-vtt ] [\-vv vertangle] [\-vh
20			horzangle]
21			.SH DESCRIPTION
22			.PP
23			evalglare determines and evaluates glare sources within a 180 degree
24			fish\-eye\-image, given in the RADIANCE image format (.pic or .hdr).
25			The image should be rendered as fish eye (e.g.
26			using the \-vta or \[en]vth option) using 180 degree for the horizontal and
27			vertical view angle (\-vv =180, \-vh=180).
28			Due to performance reasons of the evalglare code, the image should be
29			smaller than 1200x1200 pixels. The recommended size is 800x800 pixels.
30			In the first step, the program uses a given threshold to determine all
31			glare sources.
32			Three different threshold methods are implemented.
33			The recommended method is to define a task area by \-t or \-T option.
34			In this (task) area the average luminance is calculated Each pixel,
35			exceeding this value multiplied by the \-b factor [default=5] is treated
36			as a potential glare source.
37			The other two methods are described below [see \-b].
38			In the second step the program tries to merge glare source pixels to one
39			glare source, when they are placed nearby each other.
40			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.
53			.PP
54			The program calculates the daylight glare probability (DGP) as well as
55			other glare indexes (dgi,ugr,vcp,cgi) to the standard output.
56			The DGP describes the fraction of persons disturbed, caused by glare from
57			daylight (range 0...1).
58			Values lower than 0.2 are out of the range of the user assessment tests,
59			where the program is based on and should be interpreted carefully.
60			A low light correction is applied to the DGP when the vertical illumiance is lower than 500 lux.
61			By the use of \-g or \-G the field of view is cut according the the definition of Guth.
62			The option \-B angle (in rad) calculates the average luminance of a horizontal band.
63			In the case of non\-180 degree images, an external measured illuminance value
64			can be provided by using the \[en]i or \[en]I option.
65			The use of the \[en]I option enables the filling up of images, which are
66			horizontally cut.
67			The age correction is not supported any more and disabled.
68			If the option \-d is used, all found glare sources and their position,
69			size, and luminance values are printed to the standard output, too.
70			The last line gives following values: 1.
71			dgp, 2.
72			average luminance of image,3.
73			vertical eye illuminance, 4.
74			background luminance, 5.
75			direct vertical eye illuminance, 6.
76			dgi, 7.
77			ugr, 8.
78			vcp, 9.
79			cgi, 10.
80			average luminance of all glare sources, 11.
81			sum of solid angles of all glare sources 12.
82			Veiling luminance (disability glare) 13.
83			x\-direction of glare source 14.
84			y\-direction of glare source 15.
85			z\-direction of glare source 16.
86			band luminance
87			.PP
88			The program is based on the studies from J.
89			Christoffersen and J.
90			Wienold (see \“Evaluation methods and development of a new glare
91			prediction model for daylight environments with the use of CCD cameras
92			and RADIANCE\“ , Energy and Buildings, 2006.
93			More details can be also found in following issertation: J.
94			Wienold, \“Daylight glare in offices\”, Fraunhofer IRB, 2010.
95			URL for download:
96			http://publica.fraunhofer.de/eprints/urn:nbn:de:0011\-n\-1414579.pdf
97			.TP
98			.B \-B \f[I]angle\f[],
99			Calculate average luminance of a horizontal band. The angle is in rad. Output only when using the \-d option.
100			.RS
101			.RE
102			.TP
103			.B \-b \f[I]factor\f[],
104			Threshold factor; if factor >100, it is used as constant threshold in
105			cd/m2, regardless if a task position is given or not if factor is <= 100
106			and a task position is given, this factor multiplied by the average task
107			luminance will be used as threshold for detecting the glare sources if
108			factor is <= 100 and no task position is given, this factor multiplied
109			by the average luminance in the entire picture will be used as threshold
110			for detecting the glare sources, default value=5.
111			.RS
112			.RE
113			.TP
114			.B \-c \f[I]fname\f[]
115			writes a checkfile in the RADIANCE picture format
116			.RS
117			.RE
118			.TP
119			.B \-d
120			enables detailed output (default: disabled)
121			.RS
122			.RE
123			.TP
124			.B \-g \f[I]type\f[]
125			cut field of view according to Guth, write checkfile specified by \[en]c
126			and exit without any glare evaluation.
127			type=1: total field of view type=2: field of view seen by both eyes
128			.RS
129			.RE
130			.TP
131			.B \-G \f[I]type\f[]
132			cut field of view according to Guth, perform glare evaluation.
133			type=1: total field of view type=2: field of view seen by both eyes
134			.RS
135			.RE
136			.TP
137			.B \-i \f[I]Ev\f[]
138			The vertical illuminance is measured externally.
139			This value will be used for calculating the dgp.
140			.RS
141			.RE
142			.TP
143			.B \-I \f[I]Ev y_max y_min\f[]
144			The vertical illuminance is measured externally.
145			This value will be used for calculating the dgp.
146			Below y_min and above y_max, the picture is filled up by the last known
147			value.
148			This option should be used, when the provided picture is cut
149			horizontally.
150			.RS
151			.RE
152			.TP
153			.B \-r \f[I]angle\f[]
154			search radius (angle in radiant) between pixels, where evalglare tries
155			to merge glare source pixels to the same glare source (default value:
156			0.2 radiant)
157			.RS
158			.RE
159			.TP
160			.B \-s
161			enables smoothing function (default: disabled)
162			.RS
163			.RE
164			.TP
165			.B \-t \f[I]xpos ypos angle\f[]
166			definition of task position in x and y coordinates, and its opening
167			angle in radiant
168			.RS
169			.RE
170			.TP
171			.B \-T \f[I]xpos ypos angle\f[]
172			same as \-t, except that the task area is colored bluish in the
173			checkfile
174			.RS
175			.RE
176			.TP
177			.B \-u \f[I]r g b\f[]
178			color glare sources unfiformly when writing check file (implies \-c option). Color given in r g b.
179			.RS
180			.RE
181			.TP
182			.B \-v
183			show version of evalglare and exit
184			.RS
185			.RE
186			.TP
187			.B \-V
188			Just calculate the vertical illuminance and exit
189			.RS
190			.RE
191			.TP
192			.B \-x
193			disable peak extraction
194			.RS
195			.RE
196			.TP
197			.B \-y
198			enables peak extraction (default: enabled)
199			.RS
200			.RE
201			.TP
202			.B \-Y \f[I]value\f[]
203			enables peak extraction with value as threshold for extracted peaks
204			.RS
205			.RE
206			.PP
207			In case, the view settings within the image are missing or are not valid
208			(e.g.
209			after the use of pcompos or pcomb), the view options can be set by
210			command line options.
211			As soon as view options are set within the command line, view options
212			within the image are ignored.
213			The view options are implemented according to the RADIANCE definition
214			(please read man page of rpict for details):
215			.TP
216			.B \-vtt
217			Set view type to t (for fish\-eye views, please use \[en]vta or \[en]vth
218			preferably)
219			.RS
220			.RE
221			.TP
222			.B \-vf \f[I]viewfile\f[]
223			Get view parameters from file
224			.RS
225			.RE
226			.TP
227			.B \-vv \f[I]val\f[]
228			Set the view vertical size to val
229			.RS
230			.RE
231			.TP
232			.B \-vh \f[I]val\f[]
233			Set the view horizontal size to \f[I]val\f[]
234			.RS
235			.RE
236			.SH ACKNOWLEDGEMENTS
237			.PP
238			The evalglare program was developped by Jan Wienold originally at the Fraunhofer
239			Institute for Solar Energy Systems in Freiburg, Germany. It is further developped
240			and maintained by the same author at EPFL, Lausanne, Switzerland.
241			.PP
242			The author would like to thank C.
243			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.