man/man1/dcglare.1

.TH DCGLARE
.SH NAME
dcglare - compute glare in annual simulation time-step(s) via matrix
multiplication
.SH SYNOPSIS
.B dcglare
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-i{f|d}
][
.B "\-o{f|d}
][
.B "\-l
.I val
][
.B "\-b
.I val
][{
.B "\-sf
.I file
|
.B "\-ss
.I h
.B "\-so
.I h
}][
.B "\-vu
.I dx dy dz
]{
.B "\-vd
.I dx dy dz
|
.B "\-vf
.I file
[
.B "\-vi{f|d}
]}
.B DCdirect
.B DCtotal
[
.B skyf
]
.br
.B dcglare
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-i{f|d}
][
.B "\-o{f|d}
][
.B "\-l
.I val
][
.B "\-b
.I val
][{
.B "\-sf
.I file
|
.B "\-ss
.I h
.B "\-so
.I h
}][
.B "\-vu
.I dx dy dz
]{
.B "\-vd
.I dx dy dz
|
.B "\-vf
.I file
[
.B "\-vi{f|d}
]}
.B DCdirect
.B Vspec
.B Tbsdf
.B Dmat.dat
[
.B skyf
]
.SH DESCRIPTION
.I Dcglare
generates daylight glare probability (DGP) predictions for multiple points in a
space under a variety of daylit conditions. Usually, it is used to produce
hourly DGP values for an entire year, or if the
.I \-l
option is provided, it calculates glare autonomy based on an annual occupancy
schedule.
.PP
As input,
.I dcglare
requires daylight coefficient matrices relating the illuminance at each view
point to the brightness of each sky patch. Two such matrices are required.
The first,
.I DCdirect
, consists of direct views to the sky only and is calculated by
.I rcontrib(1)
using a single ambient bounce. The second,
.I DCtotal
, includes the total direct and diffuse contribution of each sky patch.
The latter can be calculated directly by
.I rcontrib(1)
as in the two-phase method, or internally as in the three-phase method if given
view, BSDF, and daylight matrices. In this respect,
.I dcglare
is similar to
.I dctimestep(1)
except that it calculates DGP instead of irradiance. 
The final input is the sky contribution matrix, usually computed by
.I gendaymtx(1)
, which may be passed on the standard input.
For efficiency, matrices stored in files can be represented as binary float data
if machine byte-order is not an issue.
.PP
In the imageless method for calculating DGP, each visible sky patch acts
as a glare source if it's brightness is above a threshold set by the
.I \-b
option. This option behaves similarly to the option in
.I evalglare(1)
as described below. 
Imageless DGP calculation also requires that the view direction must be
specified for each view to orient it relative to the given sky patches.
If all views are oriented in the same direction,
.I \-vd
can be used to specify the view direction vector.
Alternatively, a view file can be specified by the
.I \-vf
option. The format for this file is the same as the input format expected by
.I rcontrib(1)
, and for simplicity, the same file can be provided as input to both programs.
The
.I \-vif
or
.I \-vid
option may be used to specify that view data is in float or double format,
respectively.
The up vector
.I \-vu
is used together with the direction vector to calculate the Guth index for each
sky patch relative to each view.
While each entry in the view file may have a unique view direction, a single up
vector is used for all views. The default up vector is in the positive
.I z
direction.
.PP
Glare autonomy refers to the fraction of occupied hours in which a view is free
of glare. When a glare limit is specified with the
.I \-l
option,
.I dcglare
will calculate the fraction of sky conditions from the sky matrix in which DGP
is less than this limit. In this case, individual DGP values are not recorded.
By default, all entries in the sky matrix are included in the glare autonomy
calculation, unless limitted by the
.I \-n
option.
However, you may exclude certain entries by creating an occupancy schedule.
This is useful if the sky matrix built with
.I gendaymtx(1)
contains all hours of a year, but the space will only be occupied at certain
times. You may specify an occupancy schedule file with the
.I \-sf
option. This file should be in comma-separated value format with the same number
of rows as in the sky matrix. The last entry of each line is read as a numeric
value that should be greater than zero for occupied times. Lines may be
commented with a '#' character.
This format is compatible with DIVA schedule files.
Alternatively, if the sky matrix contains 24 entries per day corresponding to
one per hour, uniform daily start and end hours for occupancy can be specified
with the
.I \-ss
and
.I \-se
options. No adjustment is made for daylight savings time.
.PP
In addition to these, you may specify options from
.I dctimestep(1)
with the exception of
.I \-o
because image rendering is not supported.
.TP 12n
.BI -l \ val
Set the limit for glare occurrence to
.I val
\&. When this option is provided, the program calculates glare autonomy,
where any DGP value at or above the limit
.I val
indicates the presence of glare. If the option is not provided, the program
calculates DGP under each sky condition in the sky matrix instead.
.TP
.BI -b \ val
Set the threshold factor to
.I val
\&. If
.I val
is larger than 100, it is used as constant threshold in cd/m2. If
.I val
is less or equal than 100, this factor multiplied by the average luminance in
each view will be used as threshold for detecting the glare sources (not
recommended). The default value is 2000 (fixed threshold method).
.TP
.BI -vf \ file
Get the list of views for DGP calculation from
.I file
\&. Each line in
.I file
contains six numeric values corresponding to the position and direction
of a view. Generally, this is the same file that is used as input to
.I rcontrib(1)
to create the daylight coefficient matrices
.TP
.BI -vd " xd yd zd"
Set the view forward vector (vertical direction) for DGP calculation to
.I xd yd zd
\&. This option is ignored when the
.I \-vf
option is provided.
.TP
.BI -vu " xd yd zd"
Set the view up vector (vertical direction) for DGP calculation to
.I xd yd zd
\&. The default up vector is the positive
.I z
direction.
.TP
.BI -vi t
Set the format of the view file to
.I t
\&. Available options are 'f' for single and 'd' for double precison IEEE float.
The default when no value is provided is to use ASCII.
.TP
.BI -sf \ file
Set the occupancy schedule file to
.I file
\&. In the event that the sky matrix includes unoccupied hours that should not
contribute to the glare autonomy calculation,
.I file
will be read to determine which entries from the sky file matrix will be
included in this calculation. Each line of
.I file
is expected to contain a numeric value at the end of a comma-delimited list,
with zero corresponding to unoccupied.
This argument is used only if
.I -l
is specified.
.TP
.BI -ss \ h
Set the occupancy start hour to
.I h
\&. This option is provided for expediency when no occupancy schedule file is
available. It is assumed that the sky matrix includes 24 entries per day,
corresponding to one per hour. This argument is used only if
.I -l
is specified.
.TP
.BI -se \ h
Set the occupancy end hour to
.I h
\&. This option is provided for expediency when no occupancy schedule file is
available. It is assumed that the sky matrix includes 24 entries per day,
corresponding to one per hour. This argument is used only if
.I -l
is specified.
.SH EXAMPLES
To generate an hourly matrix of DGP where output columns are time steps and rows
correspond to views in the file views.vf:
.IP "" .2i
gendaymtx -of Tampa.wea > sky.smx
.IP "" .2i
rcontrib -e MF:1 -f reinhartb.cal -b rbin -bn Nrbins -m sky_mat -I+ -ab 1
-ad 50000 -lw .00002 -lr -10 -faf scene.oct < views.vf > dc1.mtx
.IP "" .2i
rcontrib -e MF:1 -f reinhartb.cal -b rbin -bn Nrbins -m sky_mat -I+ -ab 8
-ad 50000 -lw .00002 -lr -10 -faf scene.oct < views.vf > dc8.mtx
.IP "" .2i
dcglare -vf views.vf dc1.mtx dc8.mtx sky.smx > dgp.txt
.PP
To calculate glare autonomy based on a 40% DGP limit using the same matrices:
.IP "" .2i
dcglare -vf views.vf -sf 8to6withDST.60min.occ.csv -l .4 dc1.mtx dc8.mtx
sky.smx > ga.txt
.PP
To generate an hourly matrix of DGP values from Skylight3 using a 3-phase
calculation, where output columns are time steps:
.IP "" .2i
gendaymtx NYCity.wea | dcglare dc1.mtx WPpts.vmx shade3.xml Skylight3.dmx
> wp_win3.dat
.SH AUTHOR
Nathaniel Jones
.SH SEE ALSO
dctimestep(1), gendaymtx(1), rcontrib(1), evalglare(1)
Revision:	1.1
Committed:	Mon Sep 9 17:19:51 2019 UTC (5 years, 8 months ago) by greg
Branch:	MAIN
Log Message:	Added Nathaniel Jones' dcglare utility
#	User	Rev	Content
1	greg	1.1	.TH DCGLARE
2			.SH NAME
3			dcglare - compute glare in annual simulation time-step(s) via matrix
4			multiplication
5			.SH SYNOPSIS
6			.B dcglare
7			[
8			.B "\-n nsteps"
9			][
10			.B "\-h"
11			][
12			.B "\-i{f\|d}
13			][
14			.B "\-o{f\|d}
15			][
16			.B "\-l
17			.I val
18			][
19			.B "\-b
20			.I val
21			][{
22			.B "\-sf
23			.I file
24			\|
25			.B "\-ss
26			.I h
27			.B "\-so
28			.I h
29			}][
30			.B "\-vu
31			.I dx dy dz
32			]{
33			.B "\-vd
34			.I dx dy dz
35			\|
36			.B "\-vf
37			.I file
38			[
39			.B "\-vi{f\|d}
40			]}
41			.B DCdirect
42			.B DCtotal
43			[
44			.B skyf
45			]
46			.br
47			.B dcglare
48			[
49			.B "\-n nsteps"
50			][
51			.B "\-h"
52			][
53			.B "\-i{f\|d}
54			][
55			.B "\-o{f\|d}
56			][
57			.B "\-l
58			.I val
59			][
60			.B "\-b
61			.I val
62			][{
63			.B "\-sf
64			.I file
65			\|
66			.B "\-ss
67			.I h
68			.B "\-so
69			.I h
70			}][
71			.B "\-vu
72			.I dx dy dz
73			]{
74			.B "\-vd
75			.I dx dy dz
76			\|
77			.B "\-vf
78			.I file
79			[
80			.B "\-vi{f\|d}
81			]}
82			.B DCdirect
83			.B Vspec
84			.B Tbsdf
85			.B Dmat.dat
86			[
87			.B skyf
88			]
89			.SH DESCRIPTION
90			.I Dcglare
91			generates daylight glare probability (DGP) predictions for multiple points in a
92			space under a variety of daylit conditions. Usually, it is used to produce
93			hourly DGP values for an entire year, or if the
94			.I \-l
95			option is provided, it calculates glare autonomy based on an annual occupancy
96			schedule.
97			.PP
98			As input,
99			.I dcglare
100			requires daylight coefficient matrices relating the illuminance at each view
101			point to the brightness of each sky patch. Two such matrices are required.
102			The first,
103			.I DCdirect
104			, consists of direct views to the sky only and is calculated by
105			.I rcontrib(1)
106			using a single ambient bounce. The second,
107			.I DCtotal
108			, includes the total direct and diffuse contribution of each sky patch.
109			The latter can be calculated directly by
110			.I rcontrib(1)
111			as in the two-phase method, or internally as in the three-phase method if given
112			view, BSDF, and daylight matrices. In this respect,
113			.I dcglare
114			is similar to
115			.I dctimestep(1)
116			except that it calculates DGP instead of irradiance.
117			The final input is the sky contribution matrix, usually computed by
118			.I gendaymtx(1)
119			, which may be passed on the standard input.
120			For efficiency, matrices stored in files can be represented as binary float data
121			if machine byte-order is not an issue.
122			.PP
123			In the imageless method for calculating DGP, each visible sky patch acts
124			as a glare source if it's brightness is above a threshold set by the
125			.I \-b
126			option. This option behaves similarly to the option in
127			.I evalglare(1)
128			as described below.
129			Imageless DGP calculation also requires that the view direction must be
130			specified for each view to orient it relative to the given sky patches.
131			If all views are oriented in the same direction,
132			.I \-vd
133			can be used to specify the view direction vector.
134			Alternatively, a view file can be specified by the
135			.I \-vf
136			option. The format for this file is the same as the input format expected by
137			.I rcontrib(1)
138			, and for simplicity, the same file can be provided as input to both programs.
139			The
140			.I \-vif
141			or
142			.I \-vid
143			option may be used to specify that view data is in float or double format,
144			respectively.
145			The up vector
146			.I \-vu
147			is used together with the direction vector to calculate the Guth index for each
148			sky patch relative to each view.
149			While each entry in the view file may have a unique view direction, a single up
150			vector is used for all views. The default up vector is in the positive
151			.I z
152			direction.
153			.PP
154			Glare autonomy refers to the fraction of occupied hours in which a view is free
155			of glare. When a glare limit is specified with the
156			.I \-l
157			option,
158			.I dcglare
159			will calculate the fraction of sky conditions from the sky matrix in which DGP
160			is less than this limit. In this case, individual DGP values are not recorded.
161			By default, all entries in the sky matrix are included in the glare autonomy
162			calculation, unless limitted by the
163			.I \-n
164			option.
165			However, you may exclude certain entries by creating an occupancy schedule.
166			This is useful if the sky matrix built with
167			.I gendaymtx(1)
168			contains all hours of a year, but the space will only be occupied at certain
169			times. You may specify an occupancy schedule file with the
170			.I \-sf
171			option. This file should be in comma-separated value format with the same number
172			of rows as in the sky matrix. The last entry of each line is read as a numeric
173			value that should be greater than zero for occupied times. Lines may be
174			commented with a '#' character.
175			This format is compatible with DIVA schedule files.
176			Alternatively, if the sky matrix contains 24 entries per day corresponding to
177			one per hour, uniform daily start and end hours for occupancy can be specified
178			with the
179			.I \-ss
180			and
181			.I \-se
182			options. No adjustment is made for daylight savings time.
183			.PP
184			In addition to these, you may specify options from
185			.I dctimestep(1)
186			with the exception of
187			.I \-o
188			because image rendering is not supported.
189			.TP 12n
190			.BI -l \ val
191			Set the limit for glare occurrence to
192			.I val
193			\&. When this option is provided, the program calculates glare autonomy,
194			where any DGP value at or above the limit
195			.I val
196			indicates the presence of glare. If the option is not provided, the program
197			calculates DGP under each sky condition in the sky matrix instead.
198			.TP
199			.BI -b \ val
200			Set the threshold factor to
201			.I val
202			\&. If
203			.I val
204			is larger than 100, it is used as constant threshold in cd/m2. If
205			.I val
206			is less or equal than 100, this factor multiplied by the average luminance in
207			each view will be used as threshold for detecting the glare sources (not
208			recommended). The default value is 2000 (fixed threshold method).
209			.TP
210			.BI -vf \ file
211			Get the list of views for DGP calculation from
212			.I file
213			\&. Each line in
214			.I file
215			contains six numeric values corresponding to the position and direction
216			of a view. Generally, this is the same file that is used as input to
217			.I rcontrib(1)
218			to create the daylight coefficient matrices
219			.TP
220			.BI -vd " xd yd zd"
221			Set the view forward vector (vertical direction) for DGP calculation to
222			.I xd yd zd
223			\&. This option is ignored when the
224			.I \-vf
225			option is provided.
226			.TP
227			.BI -vu " xd yd zd"
228			Set the view up vector (vertical direction) for DGP calculation to
229			.I xd yd zd
230			\&. The default up vector is the positive
231			.I z
232			direction.
233			.TP
234			.BI -vi t
235			Set the format of the view file to
236			.I t
237			\&. Available options are 'f' for single and 'd' for double precison IEEE float.
238			The default when no value is provided is to use ASCII.
239			.TP
240			.BI -sf \ file
241			Set the occupancy schedule file to
242			.I file
243			\&. In the event that the sky matrix includes unoccupied hours that should not
244			contribute to the glare autonomy calculation,
245			.I file
246			will be read to determine which entries from the sky file matrix will be
247			included in this calculation. Each line of
248			.I file
249			is expected to contain a numeric value at the end of a comma-delimited list,
250			with zero corresponding to unoccupied.
251			This argument is used only if
252			.I -l
253			is specified.
254			.TP
255			.BI -ss \ h
256			Set the occupancy start hour to
257			.I h
258			\&. This option is provided for expediency when no occupancy schedule file is
259			available. It is assumed that the sky matrix includes 24 entries per day,
260			corresponding to one per hour. This argument is used only if
261			.I -l
262			is specified.
263			.TP
264			.BI -se \ h
265			Set the occupancy end hour to
266			.I h
267			\&. This option is provided for expediency when no occupancy schedule file is
268			available. It is assumed that the sky matrix includes 24 entries per day,
269			corresponding to one per hour. This argument is used only if
270			.I -l
271			is specified.
272			.SH EXAMPLES
273			To generate an hourly matrix of DGP where output columns are time steps and rows
274			correspond to views in the file views.vf:
275			.IP "" .2i
276			gendaymtx -of Tampa.wea > sky.smx
277			.IP "" .2i
278			rcontrib -e MF:1 -f reinhartb.cal -b rbin -bn Nrbins -m sky_mat -I+ -ab 1
279			-ad 50000 -lw .00002 -lr -10 -faf scene.oct < views.vf > dc1.mtx
280			.IP "" .2i
281			rcontrib -e MF:1 -f reinhartb.cal -b rbin -bn Nrbins -m sky_mat -I+ -ab 8
282			-ad 50000 -lw .00002 -lr -10 -faf scene.oct < views.vf > dc8.mtx
283			.IP "" .2i
284			dcglare -vf views.vf dc1.mtx dc8.mtx sky.smx > dgp.txt
285			.PP
286			To calculate glare autonomy based on a 40% DGP limit using the same matrices:
287			.IP "" .2i
288			dcglare -vf views.vf -sf 8to6withDST.60min.occ.csv -l .4 dc1.mtx dc8.mtx
289			sky.smx > ga.txt
290			.PP
291			To generate an hourly matrix of DGP values from Skylight3 using a 3-phase
292			calculation, where output columns are time steps:
293			.IP "" .2i
294			gendaymtx NYCity.wea \| dcglare dc1.mtx WPpts.vmx shade3.xml Skylight3.dmx
295			> wp_win3.dat
296			.SH AUTHOR
297			Nathaniel Jones
298			.SH SEE ALSO
299			dctimestep(1), gendaymtx(1), rcontrib(1), evalglare(1)