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, 9 months ago) by greg
Branch:	MAIN
Log Message:	Added Nathaniel Jones' dcglare utility
#	Content
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)