man/man1/dctimestep.1

.\" RCSid $Id: dctimestep.1,v 1.14 2016/08/30 14:47:20 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
.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 rfluxmtx(1)
or
.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 matrix or 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 rfluxmtx
with separate runs 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.
.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 otherwise contain the number of
columns (time steps) 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.
Note that all matrix elements are RGB triplets, so the actual size
of the sky vector or matrix is three times the number of steps times
the number of sky patches.
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 when the sky input includes a header.
.PP
Any of the matrix or vector files may be read from a command
instead of a file by
using quotes and a beginning exclamation point ('!').
.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 0.
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
.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 an irradiance view matrix through a pair of XML window layers using
a given exterior daylight matrix and sky vector:
.IP "" .2i
dctimestep Illum.vmx "!rmtxop -ff Blinds1.xml Windo1.xml" Exter.dmx Jan20.sky
.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), genskyvec(1), getinfo(1),
mkillum(1), rcollate(1), rcontrib(1),
rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)
Revision:	1.15
Committed:	Fri Mar 1 01:00:03 2019 UTC (6 years, 2 months ago) by greg
Branch:	MAIN
Changes since 1.14:	+2 -2 lines
Log Message:	Changed output numbering to start from 0 for consistency with input
#	User	Rev	Content
1	greg	1.15	.\" RCSid $Id: dctimestep.1,v 1.14 2016/08/30 14:47:20 greg Exp $"
2	greg	1.1	.TH DCTIMESTEP 1 12/09/09 RADIANCE
3			.SH NAME
4	greg	1.4	dctimestep - compute annual simulation time-step(s) via matrix multiplication
5	greg	1.1	.SH SYNOPSIS
6			.B dctimestep
7	greg	1.4	[
8			.B "\-n nsteps"
9			][
10	greg	1.10	.B "\-h"
11			][
12	greg	1.4	.B "\-o ospec"
13	greg	1.5	][
14	greg	1.10	.B "\-i{f\|d}
15	greg	1.8	][
16			.B "\-o{f\|d}
17	greg	1.4	]
18	greg	1.2	.B DCspec
19			[
20	greg	1.4	.B skyf
21	greg	1.2	]
22			.br
23			.B dctimestep
24	greg	1.4	[
25			.B "\-n nsteps"
26			][
27	greg	1.10	.B "\-h"
28			][
29	greg	1.4	.B "\-o ospec"
30	greg	1.5	][
31	greg	1.10	.B "\-i{f\|d}
32	greg	1.8	][
33			.B "\-o{f\|d}
34	greg	1.4	]
35	greg	1.1	.B Vspec
36	greg	1.12	.B Tbsdf
37	greg	1.1	.B Dmat.dat
38			[
39	greg	1.4	.B skyf
40	greg	1.1	]
41			.SH DESCRIPTION
42			.I Dctimestep
43	greg	1.2	has two invocation forms.
44			In the first form,
45			.I dctimestep
46			is given a daylight coefficient specification and an optional sky
47	greg	1.4	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	greg	1.2	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	greg	1.1	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	greg	1.12	.I rfluxmtx(1)
61			or
62	greg	1.3	.I rcontrib(1)
63	greg	1.1	for a particular set of windows or skylight openings.
64			The second argument is the window transmission matrix, or BSDF, given as
65	greg	1.12	a matrix or a standard XML description.
66	greg	1.1	The third argument is the Daylight matrix file that defines how sky patches
67			relate to input directions on the same opening.
68			This is usually computed using
69	greg	1.12	.I rfluxmtx
70			with separate runs for each window or skylight orientation.
71	greg	1.6	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	greg	1.10	.PP
78			If the input sky data lacks a header, the
79			.I \-n
80			option may be used to indicate the number of time steps, which
81			will be 1 for a sky vector.
82	greg	1.13	The sky input file must otherwise contain the number of
83	greg	1.12	columns (time steps) specified in each sky patch row,
84			whether it is read from the standard input or from a file.
85	greg	1.10	Input starts from the first patch at the first time step, then the
86			first patch at the second time step, and so on.
87	greg	1.12	Note that all matrix elements are RGB triplets, so the actual size
88			of the sky vector or matrix is three times the number of steps times
89			the number of sky patches.
90	greg	1.5	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	greg	1.6	format, respectively, which is more efficient for large matrices.
96	greg	1.14	These options are unnecessary when the sky input includes a header.
97	greg	1.1	.PP
98	greg	1.11	Any of the matrix or vector files may be read from a command
99			instead of a file by
100			using quotes and a beginning exclamation point ('!').
101			.PP
102	greg	1.9	The standard output of
103	greg	1.1	.I dctimestep
104	greg	1.8	is either a color vector with as many RGB triplets
105	greg	1.1	as there are rows in the View matrix, or a combined
106			.I Radiance
107			picture.
108	greg	1.2	Which output is produced depends on the first argument.
109	greg	1.1	A regular file name will be loaded and interpreted as a matrix to
110			generate a color results vector.
111			A file specification containing a '%d' format string will be
112			interpreted as a list of
113			.I Radiance
114			component pictures, which will be summed according to the computed
115			vector.
116	greg	1.4	.PP
117			The
118			.I \-o
119			option may be used to specify a file or a set of output files
120			to use rather than the standard output.
121			If the given specification contains a '%d' format string, this
122	greg	1.15	will be replaced by the time step index, starting from 0.
123	greg	1.4	In this way, multiple output pictures may be produced,
124	greg	1.6	or separate result vectors (one per time step).
125	greg	1.8	.PP
126	greg	1.10	A header will normally be produced on the output, unless the
127			.I \-h
128			option is specified.
129	greg	1.8	The
130			.I \-of
131			or
132			.I \-od
133			option may be used to specify IEEE float or double binary output
134			data, respectively.
135	greg	1.1	.SH EXAMPLES
136	greg	1.2	To compute workplane illuminances at 3:30pm on Feb 10th:
137			.IP "" .2i
138			gensky 2 10 15:30 \| genskyvec \| dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
139			.PP
140			To compute an image at 10am on the equinox from a set of component images:
141			.IP "" .2i
142	greg	1.6	gensky 3 21 10 \| genskyvec \| dctimestep dcomp%03d.hdr > view_03-21-10.hdr
143	greg	1.2	.PP
144	greg	1.1	To compute a set of illuminance contributions for Window 1 on
145			the Winter solstice at 2pm:
146			.IP "" .2i
147			gensky 12 21 14 \| genskyvec \| dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
148			.PP
149			To compute Window2's contribution to an interior view at 12 noon on the Summer solstice:
150			.IP "" .2i
151	greg	1.6	gensky 6 21 12 \| genskyvec \| dctimestep view%03d.hdr Blinds30.xml
152			Window2.dmx > view_6-21-12.hdr
153			.PP
154			To generate an hourly matrix of sensor value contributions from Skylight3
155			using a 3-phase calculation, where output columns are time steps:
156			.IP "" .2i
157	greg	1.10	gendaymtx -of Tampa.wea \| dctimestep WPpts.vmx
158	greg	1.6	shade3.xml Skylight3.dmx > wp_win3.dat
159			.PP
160			Generate a series of pictures corresponding to timesteps
161			in an annual simulation:
162			.IP "" .2i
163	greg	1.10	gendaymtx NYCity.wea \| dctimestep -o tstep%04d.hdr dcomp%03d.hdr
164	greg	1.8	.PP
165	greg	1.12	To multiply an irradiance view matrix through a pair of XML window layers using
166			a given exterior daylight matrix and sky vector:
167			.IP "" .2i
168			dctimestep Illum.vmx "!rmtxop -ff Blinds1.xml Windo1.xml" Exter.dmx Jan20.sky
169			.PP
170	greg	1.10	To multiply two matrices into a IEEE-float result with header:
171	greg	1.8	.IP "" .2i
172	greg	1.10	dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
173	greg	1.1	.SH AUTHOR
174			Greg Ward
175			.SH "SEE ALSO"
176	greg	1.12	gendaymtx(1), genskyvec(1), getinfo(1),
177			mkillum(1), rcollate(1), rcontrib(1),
178			rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)