man/man1/dctimestep.1

.\" RCSid $Id: dctimestep.1,v 1.9 2014/05/30 00:00:54 greg Exp $"
.TH DCTIMESTEP 1 12/09/09 RADIANCE
.SH NAME
dctimestep - compute annual simulation time-step(s) via matrix multiplication
.SH SYNOPSIS
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-o ospec"
][
.B "\-i{f|d}
][
.B "\-o{f|d}
]
.B DCspec
[
.B skyf
]
.br
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-o ospec"
][
.B "\-i{f|d}
][
.B "\-o{f|d}
]
.B Vspec
.B Tbsdf.xml
.B Dmat.dat
[
.B skyf
]
.SH DESCRIPTION
.I Dctimestep
has two invocation forms.
In the first form,
.I dctimestep
is given a daylight coefficient specification and an optional sky
vector or matrix, which may be read from the standard input if unspecified.
The daylight coefficients are multiplied against these sky values
and the results are written to the standard output.
This may be a list of color values or a combined Radiance image,
as explained below.
.PP
In the second form,
.I dctimestep
takes four input files, forming a matrix expression.
The first argument is the View matrix file that specifies how window output
directions are related to some set of measured values, such as an array of
illuminance points or images.
This matrix is usually computed by
.I rcontrib(1)
for a particular set of windows or skylight openings.
The second argument is the window transmission matrix, or BSDF, given as
a standard XML description.
The third argument is the Daylight matrix file that defines how sky patches
relate to input directions on the same opening.
This is usually computed using
.I genklemsamp(1)
with
.I rcontrib
in a separate run for each window or skylight orientation.
The last file is the sky contribution vector or matrix,
typically computed by
.I genskyvec(1)
or
.I gendaymtx(1),
and may be passed on the standard input.
This data is assumed by default to be in ASCII format, whereas the
formats of the View and Daylight matrices
are detected automatically if given as binary data.
.PP
If the input sky data lacks a header, the
.I \-n
option may be used to indicate the number of time steps, which
will be 1 for a sky vector.
The sky input file must contain the number of
columns specified in each sky patch row, whether it is read
from the standard input or from a file.
Input starts from the first patch at the first time step, then the
first patch at the second time step, and so on.
The
.I \-if
or
.I \-id
option may be used to specify that sky data is in float or double
format, respectively, which is more efficient for large matrices.
These options are unnecessary in the when the sky
input has a header.
.PP
The standard output of
.I dctimestep
is either a color vector with as many RGB triplets
as there are rows in the View matrix, or a combined
.I Radiance
picture.
Which output is produced depends on the first argument.
A regular file name will be loaded and interpreted as a matrix to
generate a color results vector.
A file specification containing a '%d' format string will be
interpreted as a list of
.I Radiance
component pictures, which will be summed according to the computed
vector.
.PP
The
.I \-o
option may be used to specify a file or a set of output files
to use rather than the standard output.
If the given specification contains a '%d' format string, this
will be replaced by the time step index, starting from 1.
In this way, multiple output pictures may be produced,
or separate result vectors (one per time step).
.PP
A header will normally be produced on the output, unless the
.I \-h
option is specified.
The
.I \-of
or
.I \-od
option may be used to specify IEEE float or double binary output
data, respectively.
.SH EXAMPLES
To compute workplane illuminances at 3:30pm on Feb 10th:
.IP "" .2i
gensky 2 10 15:30 | genskyvec | dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
.PP
To compute an image at 10am on the equinox from a set of component images:
.IP "" .2i
gensky 3 21 10 | genskyvec | dctimestep dcomp%03d.hdr > view_03-21-10.hdr
.PP
To compute a set of illuminance contributions for Window 1 on
the Winter solstice at 2pm:
.IP "" .2i
gensky 12 21 14 | genskyvec | dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
.PP
To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
.IP "" .2i
gensky 6 21 12 | genskyvec | dctimestep view%03d.hdr Blinds30.xml
Window2.dmx > view_6-21-12.hdr
.PP
To generate an hourly matrix of sensor value contributions from Skylight3
using a 3-phase calculation, where output columns are time steps:
.IP "" .2i
gendaymtx -of Tampa.wea | dctimestep WPpts.vmx
shade3.xml Skylight3.dmx > wp_win3.dat
.IP "" .2i
.PP
Generate a series of pictures corresponding to timesteps
in an annual simulation:
.IP "" .2i
gendaymtx NYCity.wea | dctimestep -o tstep%04d.hdr dcomp%03d.hdr
.PP
To multiply two matrices into a IEEE-float result with header:
.IP "" .2i
dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
gendaymtx(1), genklemsamp(1), genskyvec(1), getinfo(1),
mkillum(1), rcollate(1), rcontrib(1), rmtxop(1), rtrace(1), vwrays(1)
Revision:	1.10
Committed:	Wed Sep 17 22:40:49 2014 UTC (10 years, 7 months ago) by greg
Branch:	MAIN
CVS Tags:	rad4R2P2
Changes since 1.9:	+27 -39 lines
Log Message:	Made header handling more logical in dctimestep and genskyvec
#	Content
1	.\" RCSid $Id: dctimestep.1,v 1.9 2014/05/30 00:00:54 greg Exp $"
2	.TH DCTIMESTEP 1 12/09/09 RADIANCE
3	.SH NAME
4	dctimestep - compute annual simulation time-step(s) via matrix multiplication
5	.SH SYNOPSIS
6	.B dctimestep
7	[
8	.B "\-n nsteps"
9	][
10	.B "\-h"
11	][
12	.B "\-o ospec"
13	][
14	.B "\-i{f\|d}
15	][
16	.B "\-o{f\|d}
17	]
18	.B DCspec
19	[
20	.B skyf
21	]
22	.br
23	.B dctimestep
24	[
25	.B "\-n nsteps"
26	][
27	.B "\-h"
28	][
29	.B "\-o ospec"
30	][
31	.B "\-i{f\|d}
32	][
33	.B "\-o{f\|d}
34	]
35	.B Vspec
36	.B Tbsdf.xml
37	.B Dmat.dat
38	[
39	.B skyf
40	]
41	.SH DESCRIPTION
42	.I Dctimestep
43	has two invocation forms.
44	In the first form,
45	.I dctimestep
46	is given a daylight coefficient specification and an optional sky
47	vector or matrix, which may be read from the standard input if unspecified.
48	The daylight coefficients are multiplied against these sky values
49	and the results are written to the standard output.
50	This may be a list of color values or a combined Radiance image,
51	as explained below.
52	.PP
53	In the second form,
54	.I dctimestep
55	takes four input files, forming a matrix expression.
56	The first argument is the View matrix file that specifies how window output
57	directions are related to some set of measured values, such as an array of
58	illuminance points or images.
59	This matrix is usually computed by
60	.I rcontrib(1)
61	for a particular set of windows or skylight openings.
62	The second argument is the window transmission matrix, or BSDF, given as
63	a standard XML description.
64	The third argument is the Daylight matrix file that defines how sky patches
65	relate to input directions on the same opening.
66	This is usually computed using
67	.I genklemsamp(1)
68	with
69	.I rcontrib
70	in a separate run for each window or skylight orientation.
71	The last file is the sky contribution vector or matrix,
72	typically computed by
73	.I genskyvec(1)
74	or
75	.I gendaymtx(1),
76	and may be passed on the standard input.
77	This data is assumed by default to be in ASCII format, whereas the
78	formats of the View and Daylight matrices
79	are detected automatically if given as binary data.
80	.PP
81	If the input sky data lacks a header, the
82	.I \-n
83	option may be used to indicate the number of time steps, which
84	will be 1 for a sky vector.
85	The sky input file must contain the number of
86	columns specified in each sky patch row, whether it is read
87	from the standard input or from a file.
88	Input starts from the first patch at the first time step, then the
89	first patch at the second time step, and so on.
90	The
91	.I \-if
92	or
93	.I \-id
94	option may be used to specify that sky data is in float or double
95	format, respectively, which is more efficient for large matrices.
96	These options are unnecessary in the when the sky
97	input has a header.
98	.PP
99	The standard output of
100	.I dctimestep
101	is either a color vector with as many RGB triplets
102	as there are rows in the View matrix, or a combined
103	.I Radiance
104	picture.
105	Which output is produced depends on the first argument.
106	A regular file name will be loaded and interpreted as a matrix to
107	generate a color results vector.
108	A file specification containing a '%d' format string will be
109	interpreted as a list of
110	.I Radiance
111	component pictures, which will be summed according to the computed
112	vector.
113	.PP
114	The
115	.I \-o
116	option may be used to specify a file or a set of output files
117	to use rather than the standard output.
118	If the given specification contains a '%d' format string, this
119	will be replaced by the time step index, starting from 1.
120	In this way, multiple output pictures may be produced,
121	or separate result vectors (one per time step).
122	.PP
123	A header will normally be produced on the output, unless the
124	.I \-h
125	option is specified.
126	The
127	.I \-of
128	or
129	.I \-od
130	option may be used to specify IEEE float or double binary output
131	data, respectively.
132	.SH EXAMPLES
133	To compute workplane illuminances at 3:30pm on Feb 10th:
134	.IP "" .2i
135	gensky 2 10 15:30 \| genskyvec \| dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
136	.PP
137	To compute an image at 10am on the equinox from a set of component images:
138	.IP "" .2i
139	gensky 3 21 10 \| genskyvec \| dctimestep dcomp%03d.hdr > view_03-21-10.hdr
140	.PP
141	To compute a set of illuminance contributions for Window 1 on
142	the Winter solstice at 2pm:
143	.IP "" .2i
144	gensky 12 21 14 \| genskyvec \| dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
145	.PP
146	To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
147	.IP "" .2i
148	gensky 6 21 12 \| genskyvec \| dctimestep view%03d.hdr Blinds30.xml
149	Window2.dmx > view_6-21-12.hdr
150	.PP
151	To generate an hourly matrix of sensor value contributions from Skylight3
152	using a 3-phase calculation, where output columns are time steps:
153	.IP "" .2i
154	gendaymtx -of Tampa.wea \| dctimestep WPpts.vmx
155	shade3.xml Skylight3.dmx > wp_win3.dat
156	.IP "" .2i
157	.PP
158	Generate a series of pictures corresponding to timesteps
159	in an annual simulation:
160	.IP "" .2i
161	gendaymtx NYCity.wea \| dctimestep -o tstep%04d.hdr dcomp%03d.hdr
162	.PP
163	To multiply two matrices into a IEEE-float result with header:
164	.IP "" .2i
165	dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
166	.SH AUTHOR
167	Greg Ward
168	.SH "SEE ALSO"
169	gendaymtx(1), genklemsamp(1), genskyvec(1), getinfo(1),
170	mkillum(1), rcollate(1), rcontrib(1), rmtxop(1), rtrace(1), vwrays(1)