man/man1/gendaymtx.1

.\" RCSid $Id: gendaymtx.1,v 1.10 2019/06/25 00:09:45 greg Exp $
.TH GENDAYMTX 1 01/19/13 RADIANCE
.SH NAME
gendaymtx - generate an annual Perez sky matrix from a weather tape
.SH SYNOPSIS
.B gendaymtx
[
.B "\-v"
][
.B "\-h"
][
.B "\-A"
][
.B "\-d|\-s|\-n"
][
.B "\-D sunfile"
][
.B "\-r deg"
][
.B "\-m N"
][
.B "\-g r g b"
][
.B "\-c r g b"
][
.B "-o{f|d}"
][
.B "-O{0|1}"
]
[
.B "tape.wea"
]
.SH DESCRIPTION
.I Gendaymtx
takes a weather tape as input and produces a matrix of sky patch
values using the Perez all-weather model.
The weather tape is assumed to be in the simple ASCII format understood
by DAYSIM, which contains a short header with the site parameters followed
by the month, day, standard time, direct normal and diffuse horizontal
irradiance values, one time step per line.
Each time step line is used to compute a column in the output matrix,
where rows correspond to sky patch positions, starting with 0 for
the ground and continuing to 145 for the zenith using the default
.I "\-m 1"
parameter setting.
.PP
Increasing the
.I \-m
parameter yields a higher resolution
sky using the Reinhart patch subdivision.
For example, setting
.I "\-m 4"
yields a sky with 2305 patches plus one patch for the ground.
Each matrix entry is in fact three values, corresponding to
red green and blue radiance channels (watts/sr/meter^2).
Thus, an hourly weather tape for an entire year would
yield 8760x3 (26280) values per output line (row).
.PP
The
.I \-A
option tells
.I gendaymtx
to generate a single column corresponding to an average sky
computed over all the input time steps, rather than one
column per time step.
.PP
The
.I \-c
option may be used to specify a color for the sky.
The gray value should equal 1 for proper energy balance.
The default sky color is
.I "\-c 0.960 1.004 1.118".
Similarly, the
.I \-g
option may be used to specify a ground color.
The default value is
.I "\-g 0.2 0.2 0.2"
corresponding to a 20% gray.
.PP
The
.I \-d
option may be used to produce a sun-only matrix, with no sky contributions,
and the ground patch also set to zero.
Alternatively, the
.I \-s
option may be used to exclude any direct solar component from the output,
with the rest of the sky and ground patch unaffected.
If there is a sun in the description,
.I gendaymtx
will include its contribution in the four nearest sky patches,
distributing energy according to centroid proximity.
.PP
The
.I \-n
option may be used if no matrix output is desired.
This may be used to merely check the input, or in combination with the
.I \-D
option, below.
.PP
The
.I \-D
option may be used to specify an output file to contain a list of
solar positions and intensities corresponding to time steps in the
weather tape where the sun is visible above the horizion.
.PP
By default,
.I gendaymtx
assumes the positive Y-axis points north such that the first sky patch
is in the Y-axis direction on the horizon, the second patch is just
west of that, and so on spiraling around to the final patch near the zenith.
The
.I \-r
(or
.I \-rz)
option rotates the sky the specified number of degrees counter-clockwise
about the zenith, i.e., west of north.
This is in keeping with the effect of passing the output of
.I gensky(1)
or
.I gendaylit(1)
through
.I xform(1)
using a similar transform.
.PP
The
.I \-of
or
.I \-od
option may be used to specify binary float or double output, respectively.
This is much faster to write and to read, and is therefore preferred on
systems that support it.
(MS Windows is not one of them.)\0
The
.I \-O1
option specifies that output should be total solar radiance rather
than visible radiance.
The
.I \-h
option prevents the output of the usual header information.
Finally, the
.I \-v
option will enable verbose reporting, which is mostly useful for
finding out how many time steps are actually in the weather tape.
.SH EXAMPLES
Produce an uncolored Tregenza sky matrix without solar direct:
.IP "" .2i
gendaymtx -m 1 -c 1 1 1 -s Detroit.wea > Detroit.mtx
.PP
Produce an hourly, annual Reinhart sky matrix
with 2306 patches including solar contributions
and send float output to
.I dctimestep(1)
to compute a sensor value matrix:
.IP "" .2i
gendaymtx -m 4 -of VancouverBC.wea | dctimestep -if -n 8760 DCoef.mtx > res.dat
.SH AUTHORS
Ian Ashdown wrote most of the code,
based on Jean-Jacques Delaunay's original gendaylit(1) implementation.
Greg Ward wrote the final parameter parsing and weather tape conversion.
.SH "SEE ALSO"
dctimestep(1), genBSDF(1), gendaylit(1), gensky(1), genskyvec(1),
rcollate(1), rcontrib(1), xform(1)
Revision:	1.11
Committed:	Tue Jan 7 01:42:30 2020 UTC (5 years, 5 months ago) by greg
Branch:	MAIN
Changes since 1.10:	+18 -3 lines
Log Message:	Added -n and -D options to gendaymtx
#	Content
1	.\" RCSid $Id: gendaymtx.1,v 1.10 2019/06/25 00:09:45 greg Exp $
2	.TH GENDAYMTX 1 01/19/13 RADIANCE
3	.SH NAME
4	gendaymtx - generate an annual Perez sky matrix from a weather tape
5	.SH SYNOPSIS
6	.B gendaymtx
7	[
8	.B "\-v"
9	][
10	.B "\-h"
11	][
12	.B "\-A"
13	][
14	.B "\-d\|\-s\|\-n"
15	][
16	.B "\-D sunfile"
17	][
18	.B "\-r deg"
19	][
20	.B "\-m N"
21	][
22	.B "\-g r g b"
23	][
24	.B "\-c r g b"
25	][
26	.B "-o{f\|d}"
27	][
28	.B "-O{0\|1}"
29	]
30	[
31	.B "tape.wea"
32	]
33	.SH DESCRIPTION
34	.I Gendaymtx
35	takes a weather tape as input and produces a matrix of sky patch
36	values using the Perez all-weather model.
37	The weather tape is assumed to be in the simple ASCII format understood
38	by DAYSIM, which contains a short header with the site parameters followed
39	by the month, day, standard time, direct normal and diffuse horizontal
40	irradiance values, one time step per line.
41	Each time step line is used to compute a column in the output matrix,
42	where rows correspond to sky patch positions, starting with 0 for
43	the ground and continuing to 145 for the zenith using the default
44	.I "\-m 1"
45	parameter setting.
46	.PP
47	Increasing the
48	.I \-m
49	parameter yields a higher resolution
50	sky using the Reinhart patch subdivision.
51	For example, setting
52	.I "\-m 4"
53	yields a sky with 2305 patches plus one patch for the ground.
54	Each matrix entry is in fact three values, corresponding to
55	red green and blue radiance channels (watts/sr/meter^2).
56	Thus, an hourly weather tape for an entire year would
57	yield 8760x3 (26280) values per output line (row).
58	.PP
59	The
60	.I \-A
61	option tells
62	.I gendaymtx
63	to generate a single column corresponding to an average sky
64	computed over all the input time steps, rather than one
65	column per time step.
66	.PP
67	The
68	.I \-c
69	option may be used to specify a color for the sky.
70	The gray value should equal 1 for proper energy balance.
71	The default sky color is
72	.I "\-c 0.960 1.004 1.118".
73	Similarly, the
74	.I \-g
75	option may be used to specify a ground color.
76	The default value is
77	.I "\-g 0.2 0.2 0.2"
78	corresponding to a 20% gray.
79	.PP
80	The
81	.I \-d
82	option may be used to produce a sun-only matrix, with no sky contributions,
83	and the ground patch also set to zero.
84	Alternatively, the
85	.I \-s
86	option may be used to exclude any direct solar component from the output,
87	with the rest of the sky and ground patch unaffected.
88	If there is a sun in the description,
89	.I gendaymtx
90	will include its contribution in the four nearest sky patches,
91	distributing energy according to centroid proximity.
92	.PP
93	The
94	.I \-n
95	option may be used if no matrix output is desired.
96	This may be used to merely check the input, or in combination with the
97	.I \-D
98	option, below.
99	.PP
100	The
101	.I \-D
102	option may be used to specify an output file to contain a list of
103	solar positions and intensities corresponding to time steps in the
104	weather tape where the sun is visible above the horizion.
105	.PP
106	By default,
107	.I gendaymtx
108	assumes the positive Y-axis points north such that the first sky patch
109	is in the Y-axis direction on the horizon, the second patch is just
110	west of that, and so on spiraling around to the final patch near the zenith.
111	The
112	.I \-r
113	(or
114	.I \-rz)
115	option rotates the sky the specified number of degrees counter-clockwise
116	about the zenith, i.e., west of north.
117	This is in keeping with the effect of passing the output of
118	.I gensky(1)
119	or
120	.I gendaylit(1)
121	through
122	.I xform(1)
123	using a similar transform.
124	.PP
125	The
126	.I \-of
127	or
128	.I \-od
129	option may be used to specify binary float or double output, respectively.
130	This is much faster to write and to read, and is therefore preferred on
131	systems that support it.
132	(MS Windows is not one of them.)\0
133	The
134	.I \-O1
135	option specifies that output should be total solar radiance rather
136	than visible radiance.
137	The
138	.I \-h
139	option prevents the output of the usual header information.
140	Finally, the
141	.I \-v
142	option will enable verbose reporting, which is mostly useful for
143	finding out how many time steps are actually in the weather tape.
144	.SH EXAMPLES
145	Produce an uncolored Tregenza sky matrix without solar direct:
146	.IP "" .2i
147	gendaymtx -m 1 -c 1 1 1 -s Detroit.wea > Detroit.mtx
148	.PP
149	Produce an hourly, annual Reinhart sky matrix
150	with 2306 patches including solar contributions
151	and send float output to
152	.I dctimestep(1)
153	to compute a sensor value matrix:
154	.IP "" .2i
155	gendaymtx -m 4 -of VancouverBC.wea \| dctimestep -if -n 8760 DCoef.mtx > res.dat
156	.SH AUTHORS
157	Ian Ashdown wrote most of the code,
158	based on Jean-Jacques Delaunay's original gendaylit(1) implementation.
159	Greg Ward wrote the final parameter parsing and weather tape conversion.
160	.SH "SEE ALSO"
161	dctimestep(1), genBSDF(1), gendaylit(1), gensky(1), genskyvec(1),
162	rcollate(1), rcontrib(1), xform(1)