man/man1/dctimestep.1

.\" RCSid $Id: dctimestep.1,v 1.22 2025/03/24 17:20:36 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 "\-x xres"
][
.B "\-y yres"
][
.B "\-i{a|f|d}
][
.B "\-o{a|f|d|c}
]
.B DCspec
[
.B skyf
]
.br
.B dctimestep
[
.B "\-n nsteps"
][
.B "\-h"
][
.B "\-o ospec"
][
.B "\-i{f|d}
][
.B "\-o{f|d|c}
]
.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 picture,
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 that specifies how window output
directions are related to some set of measured values, such as an array of
illuminance points or pictures.
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 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 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).
If input is a matrix rather than a set of pictures, the
.I \-x
and/or
.I \-y
options may be necessary to set the output picture size.
If only one dimension is specified, the other is computed based
on the number of rows in the result vectors.
.PP
A header will normally be produced on the output, unless the
.I \-h
option is specified.
Default output format is ASCII text.
The
.I \-of,
.I \-od,
or
.I \-oc
option may be used to specify IEEE float, double, or RGBE (picture) output
data, respectively.
The
.I \-oc
option is set automatically if input is a collection of RGBE or XYZE pictures.
.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 a picture at 10am on the equinox from a set of component pictures:
.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 NOTES
.I Dctimestep
optimizes its matrix concatenation by checking for all-zero rows
or columns, thus avoiding unnecessary vector multiplications.
This can improve performance when a daylight matrix contains
zero-filled column vectors corresponding to hours of darkness.
.PP
It rarely makes sense to specify the
.I \-od
output option with
.I dctimestep,
since matrix operations are carried out using 32-bit "float" values.
This take less memory, but can also be less accurate than an
equivalent invocation of
.I rmtxop(1)
or
.I rcomb(1),
which perform all operations on 64-bit "double" values.
.PP
.I Dctimestep
does not accept on input or produce on output Radiance
spectral pictures.
This is a limitation of the implementation and its underlying
data representation.
Use instead the similar
.I pvsum(1)
tool for spectral input and output.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
dcglare(1), gendaymtx(1), genskyvec(1), getinfo(1), mkillum(1),
pvsum(1), ra_rgbe(1), rcollate(1), rcomb(1), rcontrib(1), rcrop(1),
rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)
Revision:	1.23
Committed:	Thu Mar 27 01:26:55 2025 UTC (7 weeks, 6 days ago) by greg
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.22:	+17 -10 lines
Log Message:	feat(pvsum): Added new pvsum tool for spectral data, similar to dctimestep
#	User	Rev	Content
1	greg	1.23	.\" RCSid $Id: dctimestep.1,v 1.22 2025/03/24 17:20:36 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.17	.B "\-x xres"
15			][
16			.B "\-y yres"
17			][
18	greg	1.23	.B "\-i{a\|f\|d}
19	greg	1.8	][
20	greg	1.23	.B "\-o{a\|f\|d\|c}
21	greg	1.4	]
22	greg	1.2	.B DCspec
23			[
24	greg	1.4	.B skyf
25	greg	1.2	]
26			.br
27			.B dctimestep
28	greg	1.4	[
29			.B "\-n nsteps"
30			][
31	greg	1.10	.B "\-h"
32			][
33	greg	1.4	.B "\-o ospec"
34	greg	1.5	][
35	greg	1.10	.B "\-i{f\|d}
36	greg	1.8	][
37	greg	1.22	.B "\-o{f\|d\|c}
38	greg	1.4	]
39	greg	1.1	.B Vspec
40	greg	1.12	.B Tbsdf
41	greg	1.1	.B Dmat.dat
42			[
43	greg	1.4	.B skyf
44	greg	1.1	]
45			.SH DESCRIPTION
46			.I Dctimestep
47	greg	1.2	has two invocation forms.
48			In the first form,
49			.I dctimestep
50			is given a daylight coefficient specification and an optional sky
51	greg	1.4	vector or matrix, which may be read from the standard input if unspecified.
52			The daylight coefficients are multiplied against these sky values
53			and the results are written to the standard output.
54	greg	1.18	This may be a list of color values or a combined Radiance picture,
55	greg	1.2	as explained below.
56			.PP
57			In the second form,
58			.I dctimestep
59	greg	1.1	takes four input files, forming a matrix expression.
60	greg	1.18	The first argument is the View matrix that specifies how window output
61	greg	1.1	directions are related to some set of measured values, such as an array of
62	greg	1.18	illuminance points or pictures.
63	greg	1.1	This matrix is usually computed by
64	greg	1.12	.I rfluxmtx(1)
65			or
66	greg	1.3	.I rcontrib(1)
67	greg	1.1	for a particular set of windows or skylight openings.
68			The second argument is the window transmission matrix, or BSDF, given as
69	greg	1.12	a matrix or a standard XML description.
70	greg	1.1	The third argument is the Daylight matrix file that defines how sky patches
71			relate to input directions on the same opening.
72			This is usually computed using
73	greg	1.12	.I rfluxmtx
74			with separate runs for each window or skylight orientation.
75	greg	1.6	The last file is the sky contribution vector or matrix,
76			typically computed by
77			.I genskyvec(1)
78			or
79			.I gendaymtx(1),
80			and may be passed on the standard input.
81	greg	1.10	.PP
82			If the input sky data lacks a header, the
83			.I \-n
84			option may be used to indicate the number of time steps, which
85			will be 1 for a sky vector.
86	greg	1.13	The sky input file must otherwise contain the number of
87	greg	1.12	columns (time steps) specified in each sky patch row,
88			whether it is read from the standard input or from a file.
89	greg	1.10	Input starts from the first patch at the first time step, then the
90			first patch at the second time step, and so on.
91	greg	1.12	Note that all matrix elements are RGB triplets, so the actual size
92			of the sky vector or matrix is three times the number of steps times
93			the number of sky patches.
94	greg	1.5	The
95			.I \-if
96			or
97			.I \-id
98			option may be used to specify that sky data is in float or double
99	greg	1.6	format, respectively, which is more efficient for large matrices.
100	greg	1.14	These options are unnecessary when the sky input includes a header.
101	greg	1.1	.PP
102	greg	1.11	Any of the matrix or vector files may be read from a command
103			instead of a file by
104			using quotes and a beginning exclamation point ('!').
105			.PP
106	greg	1.9	The standard output of
107	greg	1.1	.I dctimestep
108	greg	1.8	is either a color vector with as many RGB triplets
109	greg	1.23	as there are rows in the View matrix, or a combined Radiance
110	greg	1.1	picture.
111	greg	1.2	Which output is produced depends on the first argument.
112	greg	1.1	A regular file name will be loaded and interpreted as a matrix to
113			generate a color results vector.
114			A file specification containing a '%d' format string will be
115	greg	1.23	interpreted as a list of Radiance
116	greg	1.1	component pictures, which will be summed according to the computed
117			vector.
118	greg	1.4	.PP
119			The
120			.I \-o
121			option may be used to specify a file or a set of output files
122			to use rather than the standard output.
123			If the given specification contains a '%d' format string, this
124	greg	1.15	will be replaced by the time step index, starting from 0.
125	greg	1.4	In this way, multiple output pictures may be produced,
126	greg	1.6	or separate result vectors (one per time step).
127	greg	1.18	If input is a matrix rather than a set of pictures, the
128	greg	1.17	.I \-x
129			and/or
130			.I \-y
131	greg	1.18	options may be necessary to set the output picture size.
132	greg	1.17	If only one dimension is specified, the other is computed based
133			on the number of rows in the result vectors.
134	greg	1.8	.PP
135	greg	1.10	A header will normally be produced on the output, unless the
136			.I \-h
137			option is specified.
138	greg	1.21	Default output format is ASCII text.
139	greg	1.8	The
140	greg	1.16	.I \-of,
141			.I \-od,
142	greg	1.8	or
143	greg	1.16	.I \-oc
144			option may be used to specify IEEE float, double, or RGBE (picture) output
145	greg	1.8	data, respectively.
146	greg	1.21	The
147			.I \-oc
148			option is set automatically if input is a collection of RGBE or XYZE pictures.
149	greg	1.1	.SH EXAMPLES
150	greg	1.2	To compute workplane illuminances at 3:30pm on Feb 10th:
151			.IP "" .2i
152			gensky 2 10 15:30 \| genskyvec \| dctimestep workplaneDC.dmx > Ill_02-10-1530.dat
153			.PP
154	greg	1.18	To compute a picture at 10am on the equinox from a set of component pictures:
155	greg	1.2	.IP "" .2i
156	greg	1.6	gensky 3 21 10 \| genskyvec \| dctimestep dcomp%03d.hdr > view_03-21-10.hdr
157	greg	1.2	.PP
158	greg	1.1	To compute a set of illuminance contributions for Window 1 on
159			the Winter solstice at 2pm:
160			.IP "" .2i
161			gensky 12 21 14 \| genskyvec \| dctimestep IllPts.vmx Blinds20.xml Window1.dmx > Ill_12-21-14.dat
162			.PP
163	greg	1.23	To compute Window2's contribution to an interior view at 12 noon on the summer solstice:
164	greg	1.1	.IP "" .2i
165	greg	1.6	gensky 6 21 12 \| genskyvec \| dctimestep view%03d.hdr Blinds30.xml
166			Window2.dmx > view_6-21-12.hdr
167			.PP
168			To generate an hourly matrix of sensor value contributions from Skylight3
169			using a 3-phase calculation, where output columns are time steps:
170			.IP "" .2i
171	greg	1.10	gendaymtx -of Tampa.wea \| dctimestep WPpts.vmx
172	greg	1.6	shade3.xml Skylight3.dmx > wp_win3.dat
173			.PP
174			Generate a series of pictures corresponding to timesteps
175			in an annual simulation:
176			.IP "" .2i
177	greg	1.10	gendaymtx NYCity.wea \| dctimestep -o tstep%04d.hdr dcomp%03d.hdr
178	greg	1.8	.PP
179	greg	1.12	To multiply an irradiance view matrix through a pair of XML window layers using
180			a given exterior daylight matrix and sky vector:
181			.IP "" .2i
182			dctimestep Illum.vmx "!rmtxop -ff Blinds1.xml Windo1.xml" Exter.dmx Jan20.sky
183			.PP
184	greg	1.10	To multiply two matrices into a IEEE-float result with header:
185	greg	1.8	.IP "" .2i
186	greg	1.10	dctimestep -of Inp1.fmx Inp2.fmx > Inp1xInp2.fmx
187	greg	1.18	.SH NOTES
188			.I Dctimestep
189			optimizes its matrix concatenation by checking for all-zero rows
190			or columns, thus avoiding unnecessary vector multiplications.
191			This can improve performance when a daylight matrix contains
192			zero-filled column vectors corresponding to hours of darkness.
193			.PP
194			It rarely makes sense to specify the
195			.I \-od
196			output option with
197			.I dctimestep,
198			since matrix operations are carried out using 32-bit "float" values.
199			This take less memory, but can also be less accurate than an
200			equivalent invocation of
201	greg	1.21	.I rmtxop(1)
202			or
203			.I rcomb(1),
204			which perform all operations on 64-bit "double" values.
205	greg	1.23	.PP
206			.I Dctimestep
207			does not accept on input or produce on output Radiance
208			spectral pictures.
209			This is a limitation of the implementation and its underlying
210			data representation.
211			Use instead the similar
212			.I pvsum(1)
213			tool for spectral input and output.
214	greg	1.1	.SH AUTHOR
215			Greg Ward
216			.SH "SEE ALSO"
217	greg	1.23	dcglare(1), gendaymtx(1), genskyvec(1), getinfo(1), mkillum(1),
218			pvsum(1), ra_rgbe(1), rcollate(1), rcomb(1), rcontrib(1), rcrop(1),
219	greg	1.20	rfluxmtx(1), rmtxop(1), rtrace(1), vwrays(1)